Skip to content

feat(ui): UI kit open to apps, shop widgets, stories V2 polls - #232

Merged
Xyzcancer merged 66 commits into
masterfrom
ui-components-use-cases
Nov 9, 2026
Merged

Xyzcancer merged 66 commits into
masterfrom
ui-components-use-cases

Conversation

@Xyzcancer

Copy link
Copy Markdown
Contributor

The UI kit is ordinary public API: the InternalPersonalizationUiApi opt-in marker is gone. The README does not announce it yet.

What the kit gains on this branch: a recommender block, search and category screens with filters and sorting, stories V2 polls and a share button, product cards on the shop's data.

Popups v3 and stories over API v3 (share links, polls) are not public API: they stay behind the opt-in marker InternalPersonalizationV3Api (level ERROR), and their entry points are hidden from Java.

SDK: typed getProductInfo and getProductsList, products with deeplinks and discount percent, a category with a price range and sorting, notification history with the shop secret, segments take the phone in the phone field.

Demo: a shop-only build type, a header menu that shows popups by hand, a mini-game opened by rees46://game.

The product of every listing now carries deeplink_android, deeplink_ios and
discount_percent. products/get sends "discount": false for a product without
a discount, so discount and discount_percent are read leniently instead of
failing the whole response.

Parsing is covered on saved live answers of recommendations, category, full
search and products/get.
getProductsList put the filters JSON under an empty parameter name, so the
server never saw them. iOS already sends them as filters.
New overloads next to the listener-based ones, in the style of
CategoryManager.getCategory: getProductInfo hands over a Product,
getProductsList a ProductsListResponse with total, products, brands,
categories, facets and price range built from the full search classes.
An answer that cannot be read goes to onError.
GET /notifications authenticates the shop by shop_secret and answers 400
"Incorrect shop credentials" without it, while the SDK stopped adding any
secret to requests. GetAllNotificationsUseCase gets variants with
shopSecret that send it as shop_secret; the variants without it stay as
they were and are deprecated in favour of the new ones.
PersonalizationProduct gets the product page url and the in-app deeplink
so a host can open the product it got from a tap.
Replaces the search mapper and serves every data widget: formatted price
or number with currency, old price only above the price, discount only
with an old price, picture or the original image, brand, url and the
Android deeplink. Search shows what it showed.
The API sends no rating, so the screen keeps it off by default and passes
the flag down to the catalog and its cards; a card with the flag off hides
the rating row even when the product has a rating. Presentational
components keep showing a rating they are given.
Keyed by shop, request kind and parameters; answers live 10 minutes, at
most 32 are kept and the oldest go first. Identical requests in flight
share one call, errors are not kept. Nothing uses it yet.
Idle, Loading, Content, Empty and Error, driven by a controller that runs
a request, retries the last one and drops answers of a request already
replaced. Not wired to a widget yet.
A first page that fails no longer leaves an empty screen: the catalog shows
errorText with a retryText button, built from the kit empty state and
button, and the tap asks for the first page again. A next page that fails
turns load more into a retry of that page and stops infinite scroll from
asking for it on every gesture. onError is called as before; both texts
are parameters like the other texts of the screen.
A range change instead of a full data set change: the cards stay the same,
only their rating row follows the flag.
The badge needs the old price and a positive discount, or else
discount_percent; zero, booleans and junk show none. Its text is
discount_formatted when it belongs to that number, otherwise number and
percent sign, with exactly one leading minus, so -0% and -true% are gone.
A request older than 30 seconds takes no new waiters and a new generation
loads instead; the last waiter leaving and clear() free the key at once.
An answer of an older generation, or one started before clear(), reaches
its own waiters but is not kept. A forced load skips the kept answer and
the running request, for Retry. A throwing waiter no longer keeps the
answer from the others, a cancelled one is never called, and the key
copies its parameters.
errorText and retryText given as null or an empty string fall back to the
default texts: without them the error had no button and infinite scroll
waited for a button that never came.
Covered for the first page and for a next page.
getProductInfo and getProductsList with callbacks were new abstract
methods on the public ProductsManager, so an implementation written
outside the SDK stopped compiling. They now have default bodies on top of
the listener-based methods with the shared parsing, and the module builds
interfaces with -Xjvm-default=all-compatibility so Java implementations
get them as default methods too.
A page that is not JSON reaches the listener as an empty object and used
to come out as an empty listing; an answer without products is now an
error. An array answer, which the listener-based method passed to a
callback nobody overrode, is an error too instead of no answer at all.
A listing or a product Gson cannot read reaches onError with the parse
error code.
products/get sends numbers as strings and an empty string for a missing
old price, which failed the whole product. oldprice now reads a number or
a numeric string and takes an empty string, a boolean or junk as no old
price; it is written back as a plain number.
The change goes out with a payload, and a card that gets only that payload
updates its rating row instead of being bound anew, so pictures are not
reloaded and do not blink.
Without price_formatted the card printed the double as is: 1.6499E7 for
large prices and a trailing .0 for whole ones.
Loading and Idle now go through post like the answers, as the KDoc
promised, and retry does nothing while the request is still running, so
a double tap no longer sends the same request twice.
The name PersonalizationRecommenderBlock goes to the block that loads its own
products. The presentational one keeps its parameters; the demo exhibits
follow the rename.
Carousel and grid get the showRating flag the catalog already has, and the
products block hands it to both. A block with no title text and no show-all
button has no title row, so the list starts at the top.
PersonalizationRecommenderBlock takes one source: a recommender code
(getExtendedRecommendation, with item, category and locations) or a
collection id (getCollection). It resolves the SDK like the search widgets
(app:shop_id or attach), loads through the shared response cache, and
draws the answer with the products block: title from the answer unless
the host sets one, limit, minProducts, action text, show all, dots and
the rating flag, off by default.

No skeleton: the block is gone while it loads and appears with a short
fade; a cached answer shows at once. Empty, too few products or an error
hide it; onLoaded and onError report. reload() goes past the cache and
keeps the shown block until the answer. A tap or the card button of a
recommendation sets the dynamic source with the block code before the
host callback.
PersonalizationRecommenderBlockWidget is an AndroidView over the block, like
the stories widget; a hidden block has zero height. Source and parameters
change on the same view with a new load; reload goes through
PersonalizationRecommenderBlockController.
The Blocks tab loads a recommender block of the demo shop as a carousel,
the same code as a grid and through the Compose wrapper, each with its
onLoaded / onError caption and a reload button. The static exhibits of
the products block stay.
getCategory gets a variant with priceMin, priceMax, sortBy and sortDir
next to brands, locations and filters. It has a default body that falls
back to the old method, so existing implementations of CategoryManager,
Java ones included, keep compiling; old calls resolve to the old method.
PersonalizationCategoryScreen is the sibling of the search results
screen: the same title with filters, sort and the counter, grid/list,
load more or infinite scroll, the empty state and errors with Retry.
Its source is getCategory with the applied brands, facets, price and
sorting; the category view is tracked once per category, and a product
tap sets no tracking source.

Everything but the source moved into PersonalizationListingScreen, so
the two screens share one implementation; the search screen keeps its
properties and behaviour. The applied filters type is now
PersonalizationListingScreen.Applied. The counter row drops the gap of
an empty prefix, for "N products".
A category answers with hundreds of facets and no priority, so the
filters screen was endless. Facets with more than one value now go by
the number of products that have them, and only the first maxFacets
(10 by default; null or 0 for all) are shown, on both results screens.
A facet with checked values stays visible, and an explicit facets list
from the host still wins, in the host's order.
The instant search field of Home moved into ShopSearchBar, with the
same behaviour: the panel opens on focus with the rest of the screen
hidden, Cancel or back closes it, a phrase opens Search, a product its
page, a category its page. Home and the product page use it.
The category page is the kit's PersonalizationCategoryScreen under the
shop's search field: filters, sorting, paging, the empty state and
errors come from the kit, and its own loader, paging and grid/list
switch are gone. Search and Category sort with a platform picker:
relevance, price both ways and discount.
A facet value that is a JSON object with a non-empty string title is
shown by that title, in the filters and in the applied tags; the request
still carries the original value. Values in the filters show the number
of products from the answer, "White (172)", which showValueCounts turns
off. facetValueTitle lets the host title values of the shop's facets
and wins over the JSON title. Only the format of the answer is used, no
rules by facet names or language.
Search and Category title the demo feed's stickers and product_type
facets and the product_type values, as an integrator sets the kit up
for its feed; other facets keep the kit's default titles.
…pup products open in the shop

A link to the demo site that is not a stories link opens in the browser instead of coming back to the demo.
…button, a header menu shows demo popups by hand
…consent checkbox takes the form's colors, kit blocks the theme of the popup's background
… outside, a popup or a story; trigger popups keep off it; #185 in the header's popup menu
…ies over API v3 move behind their own opt-in marker, hidden from Java
@Xyzcancer
Xyzcancer merged commit 5b4f344 into master Nov 9, 2026
1 check passed
@Xyzcancer
Xyzcancer deleted the ui-components-use-cases branch November 9, 2026 17:51
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