Skip to content

feat(sdk): internal UI kit, richer search responses - #20

Merged
Xyzcancer merged 80 commits into
masterfrom
feature/uikit-design-tokens
Oct 14, 2026
Merged

Xyzcancer merged 80 commits into
masterfrom
feature/uikit-design-tokens

Conversation

@Xyzcancer

Copy link
Copy Markdown
Contributor

Summary

  • Internal design-system UI kit: tokens, theme, components and blocks, stories V2, in-app popup. Not exported from rees46_sdk.dart; only the example imports it, from src/ui/personalization_ui.dart.
  • Bridge for the kit's stories (stories JSON, seen slides, audio session, opening links); hidden from the public API with the kit.
  • Search responses carry brands, filters, industrial filters, picture, old price and discount, as in the native SDKs.

Host impact: the plugin now depends on video_player and shared_preferences, and requires REES46 3.35.0 on iOS.

The package had no UI layer at all until now, only the pigeon bridge. Colours
land as a ThemeExtension so a host can override them through ThemeData and get
both schemes; the type scale, spacing, radii and elevation are constants for
now. The 16 icons are package assets — declared without the lib/ prefix, which
Flutter implies for packages, and read back as packages/rees46_sdk/assets/icons.

Flutter does not draw SVG without a dependency, so components that show an icon
take the asset path plus a builder and the consumer picks the renderer. The
space is reserved either way.

16 base components under lib/src/ui/components, all exported from
rees46_sdk.dart — Button, ButtonGroup, InputField, Checkbox, CheckboxWithLabel,
Tag, Badge, Loader, EmptyState, Title, SearchResultsTitle, Accordion,
ListLabel, Dots, Count and Rating.

InputField is built on TextField for selection and the copy menu, so it needs
Material in the tree. It wraps itself in a transparent Material, which covers
everything but MaterialLocalizations; that requirement is documented on the
class.

Nothing is wired into the existing widgets yet.
…sign system

One ThemeExtension now carries colours, radii and the font family, registered
on ThemeData like any other and overridable per subtree through Theme(data:)
— which is what a multi-shop app needs when two shops carry different
branding. PersonalizationColors stops being an extension of its own and
becomes a field of the theme; its of(context) delegates, so the widgets did
not need to change how they read colours.

Radii leave the widgets as literals. Where a widget keeps its metrics in a
const table the table cannot see the theme, so it holds a
PersonalizationRadiusToken and the value is resolved at build. The checkbox
painter takes the radius as a field and repaints when it changes.

The font was not a token until now — every TextStyle hardcoded a weight and
left the family to the platform. Every style now asks the theme for a family
and package per weight: the SDK does not bundle Inter, a host names its own.

Spacing, elevation and the type scale stay constants on purpose: they are the
layout of the design file, not its branding.
…, loader slot

Re-read against the file on 14 September: every radius in the button family
moved up by two — Button LG/MD/SM are now 12/10/8, Segmented MD is 8 — and the
SM button switched from the generic sm step to Button SM. They were Figma
variables all along, bound by Button, Input, Badge, Tag and Button Group, so
they become semantic fields on PersonalizationRadiusScale with matching tokens.
Segmented SM was not on the page and is inferred from the +2 step.

LG button is 48 now (vertical padding 8) and its icon-only form is 56x48, so
icon-only padding gets its own value per size. Background/Input is #F2F2F2 in
light; dark stays as it was, unmeasured.

The loader slot is 32 with the 26 ring centred inside — the ring alone put the
component at 34 against 40 on the page.
The first catalogue pieces, built on the base components. ProductImage is an
aspect-ratio slot (1:1, 4:3, 3:4) with a Background/Card placeholder — the
placeholder fill in the file is not bound to a variable, so the nearest token
stands in. ProductCard comes in the three shapes on the page: carousel (220
wide), grid (fills its cell) and list (image 120, price and action at the
bottom right). Each shape sets its own name and price type — 20/32, 18/28 and
16/24 for the price — so those live in a table rather than on the base scale.

The discount badge is the SM Badge in a new Semantic/Danger colour (#E51919),
which the card introduced and the Colors page does not carry; its dark value is
unmeasured and stays the same. Badge gains a view for it. Favorites is the
24x24 star pill from the Badge section.

Loading is not the component's job: the image slot is handed to the host —
the ImageView on Android, the UIImageView on iOS, an Image source in React
Native and an ImageProvider in Flutter.

Computed heights match the page: 390, 327 and 120.
The catalogue layouts on top of the product card. One list component carries
the three shapes from the page — Products Carousel (carousel cards, 16 apart,
horizontal) and Products Grid in its two views (grid cards two across, 16
apart both ways; list cards stacked 16 apart). The grid and list do not scroll
on their own: their height is their content, so they sit inside the host's
screen without a nested scroll. The carousel scrolls and reports the first
fully visible card.

RecommenderBlock is the three Recommender/* symbols as one component with a
layout switch: the title above, the list, and for the carousel a "show all"
ghost button in the title row and Dots below, driven by the carousel's
first-visible index. Spacing is 16 for the carousel and 12 for grid and list,
as on the page.

Product data is a plain value type with pre-formatted strings; the image is
handed to the host per card through imageLoader on Android and iOS, and is a
source or ImageProvider on React Native and Flutter.

One discrepancy noted, not resolved: the old price inside the compositions is
16/24 while the card's master component says 14/20. The master is followed.
…ate-cw icon

The last catalogue pieces. SuggestionRow is the Product and Category rows
from the page in their Image and Text forms — a 40px image, a title, a second
line that is the price for a product and the parent for a category, a chevron
on categories — with the query match set in bold as the suggestions mock
shows. The 10px gap between image and text is off the spacing scale and is
kept as drawn.

SearchSuggestions is the panel around those rows. The Search frame is a
sketch rather than a component — the header is hand-placed instead of the
InputField, the font is SF Pro — so only what reads unambiguously is taken:
tag chips 8 apart, category and product blocks 12 apart inside and between,
a 1px separator, 16px side insets. The separator is black at 4% in the file,
which no token carries; Line/Generic Subtle at 5% stands in.

Catalog is Search results and Category as one component: both are a header,
a product grid or list, then an optional loader, count and "load more"
button 12 apart. The header differs — SearchResultsTitle for one, Title with
the view switch for the other — so it is a slot rather than a variant.

The "load more" button carries arrow-rotate-cw, which the Icons page does not
have. It is taken from the button on the Search results symbol, exported at
24 and scaled to the 32 grid the other sixteen use; the generator lays it
down on all four platforms alongside them.
The UI kit is not used by the SDK yet and its surface may still move, so it
should not become public API just by landing on master. The src/ui exports
are gone from lib/rees46_sdk.dart and gathered in
lib/src/ui/personalization_ui.dart instead. Anything under src/ is an
implementation detail by Dart convention, and the analyzer says so to
whoever imports it; the example app does exactly that with an
`// ignore: implementation_imports` on the import.

Before the release the barrel is exported from rees46_sdk.dart and the kit
becomes ordinary public API.
The icons lived in lib/assets/icons while pubspec.yaml declared
assets/icons/. For a package's own assets the path is relative to the
package root — the "lib/ is implied" rule applies only to the
packages/<name>/... form an application writes — so the tool could not
find the directory and no icon reached the app bundle. Every
PersonalizationIcons key resolved to a missing asset at runtime.

The files move to assets/icons; the keys already read
packages/rees46_sdk/assets/icons/<name>.svg and stay as they are.
… blocks

A "UI Kit" route, reachable from the app bar and a button on the main
page, with two tabs. "Components" walks through every primitive in the
sizes, views and states the design file defines; "Blocks" shows the
compositions built from them — product cards, the three recommender
layouts, search suggestions and the catalogue with its header slot,
grid/list switch, count and load-more flow.

The kit stays out of the package barrel until its release, so the example
imports it directly and silences the implementation-import lint on that
line. The kit does not draw SVG itself: the example adds flutter_svg and
hands every icon through the components' iconBuilder. Product data is
static and images are plain NetworkImage providers.
The search suggestions panel was built from the sketch in the Card
section; the InstantSearchField page holds the real screens, and they
differ: a search field with a Cancel link on top, labelled sections,
recent searches with a Clear link and removable tags that wrap onto new
lines with a "more" tag at the end, and plain suggestion tags while
typing. PersonalizationInstantSearch replaces PersonalizationSearchSuggestions
with that layout; matches in the rows are bolded from the field's text.

PersonalizationFilters is the Search Results/Filters screen: a title
with a close button, range sections made of two input fields and option
sections made of checkboxes behind a "show more" accordion, with reset
and apply buttons at the bottom. The state of the checkboxes, the fields
and the expanded sections lives in the widget; the host gets the changes
through callbacks and the final sections on apply.

PersonalizationLink is the text link both screens use; the design file
has no symbol for it, the style comes from the screens. The input field
gains onSubmitted with the search key on the keyboard.
…6/24

The ProductCard page draws the card with 4:3, 1:1 and 3:4 images and
lets the card grow with the image, in the carousel and in the list. The
card now takes imageAspect, the list row is as tall as the larger of the
image and the text column instead of a fixed 120x120, and the products
list, recommender block and catalogue pass the aspect through to their
cards.

The old price in the carousel card is 16/24 on the ProductCard and
Product Carousel pages while the master component says 14/20; the pages
win, the mismatch is noted for the designer.
… the UI Kit screen

The Blocks tab replaces the old suggestions exhibit with the three
instant search states (recent searches, typing with bold matches, rows
with images), adds the filters screen and a row of cards in every image
aspect; Components gets the text link.
The Search Results/Empty State screen keeps the results title and puts
the empty state where the grid would be. PersonalizationCatalog now
takes an emptyText and builds PersonalizationEmptyState instead of the
products list when there are no products, so the host does not have to
assemble that screen by hand; the loader, count and load more button
stay under the host's control as before.
The Blocks segment gets the search results title over an empty
catalogue with "Found 0 products" and the empty state text.
…gh the bridge

The search models carried the intersection of what the two native
bridges delivered, which left out what a search screen needs: a
product's old price, discount and resized picture, the suggested
phrases of an instant search, the facets of a full search (brands,
shop filters by name, colours and sizes) and the last queries and
popular categories of a blank search. The Dart models now parse all of
them, each optional so an older native SDK still parses as before.

The iOS bridge serializes those fields from the native models it
already has, passes the `filters` facets to the native search and
paginates by product offset: the native iOS search takes an offset, so
page N with limit L is offset (N - 1) * L — page 2 used to skip two
products instead of a page. The Android bridge serializes its data
classes with Gson, so the new fields arrive with the next Android
release; it now also passes `filters` as the native SearchFilters.
SearchParams gains `filters` for the shop facets by name.
…ws without images

Wiring the components to live data showed that a product card had no
tap of its own (only the button), so nothing could open a product —
onTap wraps the card in a GestureDetector and is passed through the
list, recommender block and catalogue as onProductTap. The results
title can hide its filters and sort buttons. Instant search rows
without an image no longer draw an empty placeholder next to rows that
have one.
… SDK

Two widgets that own their state and loading, as the Figma guides for
InstantSearchField and SearchResultsScreen describe them — the Flutter
counterparts of the native ones, exported from the kit barrel.

PersonalizationInstantSearchField owns the input: below minChars it
shows the locally kept recent searches (per shop, in shared_preferences
— a new dependency — with clear and per-item removal as in the design)
and the products and popular categories of searchBlank; while typing it
debounces searchInstant and shows the suggested phrases as tags,
categories with their parent's name and products with prices. Stale
responses are dropped. Submitting adds to the history and hands the
phrase to the host; tapping a product or category stores the
instant_search attribution source and hands the object over.

PersonalizationSearchResultsScreen owns the query: it pages searchFull
with a load more button or infinite scroll, tracks the search event
once per query, builds the filters screen from the response's facets
(price range, brands, colours and sizes, and every shop facet with more
than one value), shows the applied values as removable tags and sends
them back as request parameters. The filters screen opens as an overlay
inside the widget; sorting stays with the host because the design file
has no picker.

Both take an explicit sdk handle or resolve one with REES46.getInstance
by an optional shopId, with the single registered shop as the default;
an unregistered shop leaves the widget empty with a debugPrint instead
of throwing from build.
The UI Kit screen gets a Search tab: the instant search field against
the demo shop, and the results screen it opens on submit, with back
returning to the field. Taps on products and categories only show a
snackbar; the sort button cycles relevance, price ascending and
descending in place of the picker the design file does not have.
searchManager.searchFull hands back a data class, and whatever that
class does not model is dropped before it reaches Dart — with the
released native SDK that is the shop's facets in `filters`, the old
price and the discount, so the results screen showed only price and
brand filters while the server had sent 88 facets. The bridge is a JSON
pipe, so full search now goes through the native SDK's raw search entry
point and forwards the response as is; the parameters are the same,
built on the legacy params class that entry point takes. Blank and
instant search keep the typed managers: their models carry what the
widgets read.
The full search response carries price_range, but the filters screen
only used it to decide whether to show the price section — the From /
to fields stayed empty. The range section now takes fromPlaceholder /
toPlaceholder, and the results screen fills them with the bounds, so
the user sees the limits while the request carries only what they
typed: prefilled values would have sent price_min / price_max on every
Apply and shown a price tag as if a filter were applied.
…oad more, dark fallback

Card in carousel and grid types splits into a top group (image, name, rating)
and a bottom group (price, button) with the slack between them; the list wraps
carousel and grid rows in IntrinsicHeight and stretches the cards, so a name
that wraps to two lines no longer pushes the button below its neighbours. The
catalogue hides the count and the "Load more" button while loading — the
Grid+Loader and List+Loader frames in the design file show only the loader in
their place. Without the theme extension the kit now picks its light or dark
set by the app theme's brightness instead of staying light.
…e catalogue

The example app registers the kit's light and dark theme extensions on its
MaterialApp, so the UI Kit screen follows the system scheme. Product photos are
bundled assets rather than picsum URLs — the showcase no longer depends on the
network. The catalogue exhibit gets the category title (title + view switch)
from the CatalogGrid page; the search results title stays with the search flow.
Category rows in the instant search exhibit drop their stand-in pictures: the
search API has none for categories.
Checking the kit's dark set meant leaving the app for the system settings and
coming back. The UI Kit app bar now carries a button cycling Auto -> Light ->
Dark, labelled with the mode it is in.

The mode lives in a ValueNotifier<ThemeMode> that MaterialApp.themeMode listens
to, so the whole example repaints and the kit follows through the theme
extension attached to each ThemeData. A plain notifier rather than a state
manager: neither the kit nor the example depends on one, and this needs no more.
The popup the server already sends on init and trackEvent, drawn from the design
system. Today the native SDKs present it themselves and only a boolean crosses
the bridge, so Flutter shows a UIKit or Android dialog over its own UI: it obeys
the platform's appearance rather than MaterialApp's themeMode, Navigator never
sees it, and widget tests cannot reach it. This is the Dart side of fixing that;
the popup payload still has to reach Dart, which is a separate change to the
bridge.

Source: InAppPopup / Modal page, component sets In App Popup/Modal and
In App Popup/Fullscreen — four views (image on top, image as background, text
only, icon) times two presentations. Position on screen is left to whoever
presents it; presentation only picks the metrics, since the fullscreen one drops
the corner radius, pads 24 instead of 20 and moves the type up a step.

Two departures from the file, both deliberate. The cross belongs to the popup
rather than to the image container, because the text and icon views have no
image and the file still draws a cross on them. And the text close button is not
in the file at all — the admin panel offers it as its own toggle next to the
action button, so it sits here as a secondary button under the primary one, and
an empty caption leaves just the cross.

Adds Background/Float and Background/Modal, which the file grew after the colours
were taken; the popup paints itself with Modal. Background/Card and
Background/Generic have drifted too — the kit still holds the pre-rework values —
so a full colour re-sync is due separately.

Buttons gain onDark: over a background image the file switches its controls to
the inverted palette, otherwise a secondary button's dark caption drowns in the
photograph.
Four exhibits on the Blocks tab, one per view, covering the button matrix the
admin panel can produce: one button, both buttons, close button with text, and
no buttons at all — where only the cross is left to dismiss with.
The widget is laid out but not fed by the SDK yet, and the reason is not obvious
from the Flutter side: the popup never crosses the bridge, and the native hook
needed to divert it exists on iOS but not on Android.
The widget supports both presentations, but only the modal one was on show, so
the fullscreen branch had never been rendered. Four more exhibits, one per view,
in a taller box since its padding and type are a step up.
android-sdk now has the popup interception point the TODO asked for, as
SDK.popupPresentationListener, but not in a release yet — the plugin still pins
v2.38.0. The TODO says so, adds the flag the Android plugin ignores today, and
corrects who reports the show: a popup kept back is neither reported nor
remembered by the native side, so Dart does both once the widget is on screen.
StoriesPlayback holds the viewer's logic without UI: the current story
and slide, the start slide of a story (first unseen, else the server's
start_position, from the start once viewed), seen slides marked when a
settled page enters them, pause reasons (hold, drag, sheet, background,
covered, host, loading, error), the products sheet that blocks
navigation and resets on every slide change, retry with a new entry
number, and a slide clock fed with real time deltas that a video's own
length and position can drive.
StoriesMediaCache keeps story videos in an LRU cache of 50 MB under
personalization_stories in the app cache dir, one per process for every
viewer. A file is downloaded once: a second request while it downloads
waits for the same download, and only a complete file is renamed into
place. HLS is left to the player. Plain dart:io, no new dependency.
StoriesSeenStore reads a shop's seen slides from the plugin once per
process and writes every new one through, so all bars and viewers of a
shop share one state that survives restarts; without the platform store
it stays in memory.

StoriesSound keeps the mute choice for the whole process (muted on the
first open), unmutes on the hardware volume-up key (the key event on
Android, the iOS session's volume through the bridge) and runs the iOS
audio session around video.
Viewer
- Runs on StoriesPlayback: a story is entered, tracked and marked seen
  only when its page settles, never on a half-swipe peek; it opens at
  the first unseen slide, else at start_position, from the start once
  viewed.
- Tap thirds (back / nothing / next, mirrored in RTL), hold from 200 ms,
  restart on the very first slide, close after the very last.
- Pauses on hold, drags, the products sheet, the app in the background,
  a screen covering it and the host; the slide clock adds real frame
  deltas only while running, so it ignores the animation scale and
  never skips slides on return. Vertical drags move a notifier, not the
  pages, and the player is paused only on transitions.
- The sheet is driven by the viewer: a tap outside or system back closes
  it, it blocks navigation and resets on every slide change.
- Media is fitted whole on the slide's background_color (black without
  it); slides without media sit on Background/Card. The scrim is 50% on
  bare media only. A media slide is one with a background, blank text
  blocks are skipped, end/right align to the end.
- The clock starts once media is ready; failure or 10 s without it
  shows Retry, a video also retries itself after 15 s. Videos last
  their real length, pause on buffering, play from the disk cache with
  mixWithOthers, and the next slide is preloaded.
- Product slides draw the card, every slide button, used products and
  the sound toggle, without text blocks. Prices follow the promo and
  fractional discount rules; the promo caption comes from the admin.
- Buttons, products and the carousel close the viewer first, then call
  onLinkClick / onProductClick. Dynamic slide ids are not tracked.

Widget
- PersonalizationStoriesController (open, openStory, pause, resume,
  reload) and PersonalizationStories.show for a block without the bar.
- Seen slides come from the per-shop store: the ring lights segments by
  index, and a viewed pinned story keeps a plain Semantic/Warning ring.
- A missing code, an unresolved shop, a failed or 15 s slow load hide
  the block and reach onError.
- Texts renamed to promoCaption, productButtonText, showProductsText,
  plus retryText, closeLabel, soundOnLabel, soundOffLabel; cover labels
  take up to two lines.
The live block takes a controller: buttons open the second story and
pause it for three seconds, reload the block, and show it without the
bar. The sample viewer gains a product slide over a video with two
buttons, used products and the sound toggle, a square photo fitted on
its letterbox colour, a photo that fails and offers Retry, and a
fractional discount. Covers show segments lit by index and a viewed
pinned story; a long label takes two lines.
…open

The viewer pops its route itself instead of maybePop, which the
sheet's PopScope held back. A video that keeps failing schedules one
automatic retry, not one per player update.
…n-tokens

# Conflicts:
#	example/ios/Podfile.lock
#	ios/rees46_sdk.podspec
#	lib/src/personalization_sdk.dart
@Xyzcancer
Xyzcancer merged commit 67169f6 into master Oct 14, 2026
2 of 3 checks passed
@Xyzcancer
Xyzcancer deleted the feature/uikit-design-tokens branch October 14, 2026 19:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant