@akinon/pz-theme 2.0.159-beta.0 → 2.0.159-rc.16

package/src/custom/README.md

@@ -1,31 +1,16 @@
 # Custom blocks
 
-A brand developer writes a React component in their own repo and decides, at the
-point of use, what a merchant may change about it. The component appears in the
-theme editor's Add Block picker under **Brand blocks**, its declared fields are
-editable from the properties panel, and it can open a region the merchant fills
-with ordinary editor content.
-
-Nothing here is a schema kept alongside the component. The declaration *is* the
-usage.
-
-**Writing a whole area rather than one element inside it?** See
-[`README-sections.md`](./README-sections.md). A custom *section* owns its own
-band on the page: it gets the section root panel (geometry and content width),
-and it names the children that go inside it rather than opening a hole. A custom
-*block* is the right shape for one element the merchant drops into a band they
-composed.
-
-**Want a complete, commented example?** See `examples/header/` at the root of
-the pz-next repository: one header written at six levels, from basic to
-advanced, each building on the previous one. They are reference only — not
-shipped in the npm package and never imported by an app.
+A brand developer writes a React component in their own repo and decides, at the point of use, what a merchant may change about it. The component appears in the theme editor's Add Block picker under **Brand blocks**, its declared fields are editable from the properties panel, and it can open a region the merchant fills with ordinary editor content.
+
+Nothing here is a schema kept alongside the component. The declaration _is_ the usage.
+
+**Writing a whole area rather than one element inside it?** See [`README-sections.md`](./README-sections.md). A custom _section_ owns its own band on the page: it gets the section root panel (geometry and content width), and it names the children that go inside it rather than opening a hole. A custom _block_ is the right shape for one element the merchant drops into a band they composed.
+
+**Want a complete, commented example?** See `examples/header/` at the root of the pz-next repository: one header written at six levels, from basic to advanced, each building on the previous one. They are reference only — not shipped in the npm package and never imported by an app.
 
 ## The shape
 
-A "Complete the look" row for a product page — the merchant retypes its
-heading, chooses how many products it shows, drops a campaign banner beside it,
-and restyles the product cards. One block, all four mechanisms.
+A "Complete the look" row for a product page — the merchant retypes its heading, chooses how many products it shows, drops a campaign banner beside it, and restyles the product cards. One block, all four mechanisms.
 
 ```tsx
 // src/theme-blocks/complete-the-look.tsx
@@ -73,19 +58,28 @@ function CompleteTheLook() {
 export default defineCustomBlock(CompleteTheLook, {
   label: 'Complete the look',
   settings: [
-    { key: 'productCount', type: 'slider', label: 'How many products',
-      defaultValue: 4, min: 2, max: 8 },
-    { key: 'heading', type: 'text', label: 'Heading',
-      defaultValue: 'Complete the look', editable: true }
+    {
+      key: 'productCount',
+      type: 'slider',
+      label: 'How many products',
+      defaultValue: 4,
+      min: 2,
+      max: 8
+    },
+    {
+      key: 'heading',
+      type: 'text',
+      label: 'Heading',
+      defaultValue: 'Complete the look',
+      editable: true
+    }
   ],
   slots: [{ name: 'campaign', label: 'Campaign banner' }],
   parts: { card: { states: ['hover'] }, price: {} }
 });
 ```
 
-The product data is the developer's business — it is fetched in the component
-and the merchant never sees it as a control. What the merchant gets is the
-heading, the count, the banner region and the card styling.
+The product data is the developer's business — it is fetched in the component and the merchant never sees it as a control. What the merchant gets is the heading, the count, the banner region and the card styling.
 
 ```ts
 // src/theme-blocks/index.ts
@@ -101,51 +95,32 @@ import './configure-page-context';
 import '../../theme-blocks';
 ```
 
-The block name lives in the record passed to `registerCustomBlocks`, never in
-`Component.name`: a production build minifies function names, so a block
-authored as `CompleteTheLook` would register as `t` on the storefront and as
-`CompleteTheLook` in dev, and one composition would render in one build and be an
-unknown type in the other.
+The block name lives in the record passed to `registerCustomBlocks`, never in `Component.name`: a production build minifies function names, so a block authored as `CompleteTheLook` would register as `t` on the storefront and as `CompleteTheLook` in dev, and one composition would render in one build and be an unknown type in the other.
 
 ## Import it from the client root only
 
-Not from the server layout as well. `registerCustomBlocks` is a client module
-because it reaches the renderer registry, which imports every block module — and
-most of those call hooks without a directive of their own, because the only path
-that has ever reached them is a client one. Importing it from a server layout
-fails the brand's build outright.
+Not from the server layout as well. `registerCustomBlocks` is a client module because it reaches the renderer registry, which imports every block module — and most of those call hooks without a directive of their own, because the only path that has ever reached them is a client one. Importing it from a server layout fails the brand's build outright.
 
-Client-only registration loses nothing: `ThemeBlock` is the single production
-reader of the registry and is itself a client module, the server-side CSS
-generator never consults it, and SSR still resolves custom renderers because
-Next renders client components on the server through the client graph.
+Client-only registration loses nothing: `ThemeBlock` is the single production reader of the registry and is itself a client module, the server-side CSS generator never consults it, and SSR still resolves custom renderers because Next renders client components on the server through the client graph.
 
-Use the deep path `@akinon/pz-theme/src/custom`, not the package root — the root
-also re-exports `ThemePlaceholder`, which imports `server-only`.
+Use the deep path `@akinon/pz-theme/src/custom`, not the package root — the root also re-exports `ThemePlaceholder`, which imports `server-only`.
 
 ## `ThemeEditable`
 
 Makes one wrapped element merchant-editable. The wrapped tag decides the control:
 
 | Wrapped element | Control |
-|---|---|
+| --- | --- |
 | `<img>` | image picker |
 | `<h1>`–`<h6>`, `<p>`, `<span>`, `<strong>` | text box |
 | `<a>` | two controls — link text and href |
 | `<video>` | file picker |
 
-The authored JSX is the default value: `<ThemeEditable name="heading"><h2>Complete
-the look</h2></ThemeEditable>` declares a text field whose default is
-`Complete the look`, because there is nowhere else for a developer to state it.
+The authored JSX is the default value: `<ThemeEditable name="heading"><h2>Complete the look</h2></ThemeEditable>` declares a text field whose default is `Complete the look`, because there is nowhere else for a developer to state it.
 
-At render the merchant's value is applied by re-rendering the child through
-React — never by writing to the DOM. Three shapes are refused rather than
-guessed, and the message says which: a custom component instead of a host
-element, a bare expression with no element, and an ambiguous multi-child
-element. `type=` is the explicit escape.
+At render the merchant's value is applied by re-rendering the child through React — never by writing to the DOM. Three shapes are refused rather than guessed, and the message says which: a custom component instead of a host element, a bare expression with no element, and an ambiguous multi-child element. `type=` is the explicit escape.
 
-The authored text is written in the store's default language. Its other
-languages go in `translations`:
+The authored text is written in the store's default language. Its other languages go in `translations`:
 
 ```tsx
 <ThemeEditable name="label" translations={{ en: 'MENU' }}>
@@ -153,63 +128,33 @@ languages go in `translations`:
 </ThemeEditable>
 ```
 
-The editor is told `MENÜ` only. An English page shows `MENU` for as long as
-the field still says `MENÜ`, including the copy the editor seeds when the
-block is placed. Once the merchant types their own text, it shows as typed.
-This is the same rule as a per-language `useThemeSetting` default (below); a
-setting read for the same key, such as an accessible name, can share one
-constant with it.
+The editor is told `MENÜ` only. An English page shows `MENU` for as long as the field still says `MENÜ`, including the copy the editor seeds when the block is placed. Once the merchant types their own text, it shows as typed. This is the same rule as a per-language `useThemeSetting` default (below); a setting read for the same key, such as an accessible name, can share one constant with it.
 
 ## Links and the page's language
 
-Storefront paths are stored and authored without a locale: `/yatak-odasi/`,
-never `/en/yatak-odasi/`. On an English page that bare path is the Turkish
-site, so a link that goes out as written takes the shopper out of English. A
-visible `next/link` also prefetches it, which makes the middleware set
-`pz-locale=tr`, and every request after that comes back Turkish. You do not
-write the locale yourself; there are three places it goes on for you:
+Storefront paths are stored and authored without a locale: `/yatak-odasi/`, never `/en/yatak-odasi/`. On an English page that bare path is the Turkish site, so a link that goes out as written takes the shopper out of English. A visible `next/link` also prefetches it, which makes the middleware set `pz-locale=tr`, and every request after that comes back Turkish. You do not write the locale yourself; there are three places it goes on for you:
 
 | What you render | What to use |
-|---|---|
+| --- | --- |
 | The `<a>` that `ThemeEditable` wraps | Nothing: the locale is added to its href, whether the merchant set it or you did |
 | Any other link | `ThemeLink` in place of `next/link`, with the same props |
 | A bare string: a plain `<a>`, `router.push`, a url read off commerce data | `const localize = useLocalizeHref();` then `localize(url)` |
 
-`ThemeLink` prefetches nothing unless you pass `prefetch`. Next otherwise
-fetches a link's page the moment it scrolls into view, and because the locale
-lives in a cookie that any request to an unprefixed path rewrites, one link
-that slips past these rules would switch the whole session's language without
-anyone clicking it.
-
-All three come from `@akinon/pz-theme/src/custom`. An `<a>` nested deeper
-inside a `ThemeEditable` is not touched — that one is a link of yours, so it
-takes the row it belongs to above.
-
-A full URL to this same storefront counts as a path, `www.` or not: merchants
-paste the address bar, and `https://www.zsazsazsu.com.tr/yeni-urunler/` on an
-English page becomes `/en/yeni-urunler/` — which also lets the router take it
-without a page load. Addresses with no localized copy stay as they are: `/api`
-and `/_next`, and anything ending in a file (`/files/kvkk.pdf`,
-`/manifest.json`). So do external, `#hash`, `?query` and empty hrefs, and the
-OAuth `/{provider}/login/` routes.
-
-No locale is added when the URL strategy hides the page's own: the default
-locale under `hide-default-locale`, every locale under `subdomain` and
-`hide-all-locales`. To compare an address with the page's own, localize the
-stored side rather than stripping the locale off the current one:
-`localize(node.url) === pathname`.
+`ThemeLink` prefetches nothing unless you pass `prefetch`. Next otherwise fetches a link's page the moment it scrolls into view, and because the locale lives in a cookie that any request to an unprefixed path rewrites, one link that slips past these rules would switch the whole session's language without anyone clicking it.
+
+All three come from `@akinon/pz-theme/src/custom`. An `<a>` nested deeper inside a `ThemeEditable` is not touched — that one is a link of yours, so it takes the row it belongs to above.
+
+A full URL to this same storefront counts as a path, `www.` or not: merchants paste the address bar, and `https://www.zsazsazsu.com.tr/yeni-urunler/` on an English page becomes `/en/yeni-urunler/` — which also lets the router take it without a page load. Addresses with no localized copy stay as they are: `/api` and `/_next`, and anything ending in a file (`/files/kvkk.pdf`, `/manifest.json`). So do external, `#hash`, `?query` and empty hrefs, and the OAuth `/{provider}/login/` routes.
+
+No locale is added when the URL strategy hides the page's own: the default locale under `hide-default-locale`, every locale under `subdomain` and `hide-all-locales`. To compare an address with the page's own, localize the stored side rather than stripping the locale off the current one: `localize(node.url) === pathname`.
 
 ## `useThemeSetting`
 
-For values with no on-screen representation — how many products to fetch, which
-category, whether a carousel auto-advances, which side an image sits on. Without
-it every variation becomes a separate block in the picker.
+For values with no on-screen representation — how many products to fetch, which category, whether a carousel auto-advances, which side an image sits on. Without it every variation becomes a separate block in the picker.
 
-React's own rule that hooks are called unconditionally is doing useful work
-here: the language enforces that the declaration set is static.
+React's own rule that hooks are called unconditionally is doing useful work here: the language enforces that the declaration set is static.
 
-A `text` default can be written per language, and the hook still returns one
-string, the entry for the page's locale:
+A `text` default can be written per language, and the hook still returns one string, the entry for the page's locale:
 
 ```tsx
 const label = useThemeSetting('label', {
@@ -219,97 +164,83 @@ const label = useThemeSetting('label', {
 });
 ```
 
-The editor is only told the default language's entry, so a static `settings`
-declaration keeps that one plain string (`defaultValue: 'MENÜ'`). The
-translation applies for as long as the stored value is still that default,
-including the copy the editor seeds when the block is placed. Once the
-merchant types their own text, it shows as typed in every language. A text
-the merchant can translate themselves needs the `localetext` control, which a
-custom setting cannot declare yet: this package refuses the type (see
-`collect.ts`) because the editor stores such a value as a locale map with no
-breakpoint key, and the editor refuses it in a custom catalog for the same
-reason.
+The editor is only told the default language's entry, so a static `settings` declaration keeps that one plain string (`defaultValue: 'MENÜ'`). The translation applies for as long as the stored value is still that default, including the copy the editor seeds when the block is placed. Once the merchant types their own text, it shows as typed in every language. A text the merchant can translate themselves needs the `localetext` control, which a custom setting cannot declare yet: this package refuses the type (see `collect.ts`) because the editor stores such a value as a locale map with no breakpoint key, and the editor refuses it in a custom catalog for the same reason.
+
+A `richtext` setting gives the merchant the editor's rich text control and comes back as one HTML string for the page's language, already passed through `sanitizeRichText` (a DOM-free allowlist: paragraphs, headings, lists, emphasis, colour spans and safe links). The control stores the default language's text as a plain string and a locale map (`{ tr: '<p>…</p>', en: '<p>…</p>' }`) once another language has text of its own; the hook reads the page's language, then the default language, then the plain string, so a language the merchant has not written shows the default one. Render it with `dangerouslySetInnerHTML`; the default is written as HTML too:
+
+```tsx
+const html = useThemeSetting('body', {
+  type: 'richtext',
+  label: 'Body',
+  default: '<p>Sipariş <strong>bugün</strong> kapınızda.</p>'
+});
+
+<div dangerouslySetInnerHTML={{ __html: html }} />;
+```
 
 ## `ThemeSlot`
 
-A merchant-fillable region. A block may open several, and each is filled
-independently.
-
-**Each slot is a real child node.** A declared slot materializes as one
-reserved-type child of the custom block (`custom-slot`, carrying its name in
-`properties.slotName`), and `<ThemeSlot name="campaign" />` renders THAT node's
-children. That is what makes several slots possible without touching how
-insertion is addressed: the editor already inserts at `(placeholderId,
-sectionId, parentBlockId, index)`, and a slot that is a node is simply the
-parent. A block declaring three slots gets three rows in the layer tree.
-
-`<ThemeSlot />` with no name opens the block's single slot whatever it is
-called, so every block written against the original single-slot API keeps
-working unchanged. A block declaring several NAMED slots has nothing for a bare
-slot to resolve to, and it is refused with the names listed. Two
-`<ThemeSlot name="campaign" />` in one component are a real duplicate — both resolve
-to the same node — so the second is refused: its children would render twice and
-two wrappers would answer to one block id.
-
-A slot whose node does not exist yet is not an error: it draws the empty band in
-the designer and renders nothing live. The editor creates the nodes when the
-block is inserted and again on every theme load, so a block already sitting in a
-composition gets the rows for a slot the component gained later — insert alone
-would leave those regions unreachable, because the merchant's only route into a
-region is the add-block affordance on its tree row.
-
-Children sitting directly on the block (the pre-node shape) are the unnamed
-slot's, and only the unnamed slot's. The node wins that lookup once it exists,
-so the editor MOVES those children into the unnamed node when it creates it
-rather than appending the node beside them — appending would leave live content
-saved, listed in the tree, and drawn nowhere. A block whose type declares only
-named slots has nothing to move them into, so they stay where they are and stop
-rendering, which is what changing the component means.
+A merchant-fillable region. A block may open several, and each is filled independently.
+
+**Each slot is a real child node.** A declared slot materializes as one reserved-type child of the custom block (`custom-slot`, carrying its name in `properties.slotName`), and `<ThemeSlot name="campaign" />` renders THAT node's children. That is what makes several slots possible without touching how insertion is addressed: the editor already inserts at `(placeholderId, sectionId, parentBlockId, index)`, and a slot that is a node is simply the parent. A block declaring three slots gets three rows in the layer tree.
+
+`<ThemeSlot />` with no name opens the block's single slot whatever it is called, so every block written against the original single-slot API keeps working unchanged. A block declaring several NAMED slots has nothing for a bare slot to resolve to, and it is refused with the names listed. Two `<ThemeSlot name="campaign" />` in one component are a real duplicate — both resolve to the same node — so the second is refused: its children would render twice and two wrappers would answer to one block id.
+
+A slot whose node does not exist yet is not an error: it draws the empty band in the designer and renders nothing live. The editor creates the nodes when the block is inserted and again on every theme load, so a block already sitting in a composition gets the rows for a slot the component gained later — insert alone would leave those regions unreachable, because the merchant's only route into a region is the add-block affordance on its tree row.
+
+Children sitting directly on the block (the pre-node shape) are the unnamed slot's, and only the unnamed slot's. The node wins that lookup once it exists, so the editor MOVES those children into the unnamed node when it creates it rather than appending the node beside them — appending would leave live content saved, listed in the tree, and drawn nowhere. A block whose type declares only named slots has nothing to move them into, so they stay where they are and stop rendering, which is what changing the component means.
 
 ### Narrowing what a slot takes
 
 ```ts
 slots: [
-  { name: 'campaign', label: 'Campaign banner', accepts: ['image', 'text'], max: 2 },
+  {
+    name: 'campaign',
+    label: 'Campaign banner',
+    accepts: ['image', 'text'],
+    max: 2
+  },
   { name: 'sizeGuide', label: 'Size guide' }
-]
+];
 ```
 
-`accepts` limits the block types the merchant may put in the region and `max`
-limits how many; omit either for "anything" and "as many as you like". The
-editor enforces both where a block is WRITTEN into the composition, not only
-where it is offered, so a drag from elsewhere in the tree obeys them too.
+`accepts` limits the block types the merchant may put in the region and `max` limits how many; omit either for "anything" and "as many as you like". The editor enforces both where a block is WRITTEN into the composition, not only where it is offered, so a drag from elsewhere in the tree obeys them too.
 
-Neither is read by pz-theme — the renderer draws whatever the composition holds
-— but both are checked at declare time, because they are refused on arrival and
-the editor refuses the WHOLE catalog rather than one slot. `accepts: []` (a
-region nothing could ever go in) and a `max` that is not a positive whole number
-would otherwise empty a brand's entire palette, with the only explanation in a
-repo the developer is not working in.
+Neither is read by pz-theme — the renderer draws whatever the composition holds — but both are checked at declare time, because they are refused on arrival and the editor refuses the WHOLE catalog rather than one slot. `accepts: []` (a region nothing could ever go in) and a `max` that is not a positive whole number would otherwise empty a brand's entire palette, with the only explanation in a repo the developer is not working in.
 
 ## Detecting the editor canvas
 
-`useCustomBlockContext()` returns the context the block or section renders in,
-or `null` outside one. Its `isDesigner` is what to branch on when the canvas
-needs something the live site must not do — keep a menu open so the merchant
-can style it, or stop a link from navigating on click.
+`useCustomBlockContext()` returns the context the block or section renders in, or `null` outside one. Its `isDesigner` is what to branch on when the canvas needs something the live site must not do — keep a menu open so the merchant can style it, or stop a link from navigating on click.
 
 ```ts
 const isDesigner = useCustomBlockContext()?.isDesigner ?? false;
 ```
 
-`isDesigner` means "the editing affordances are on", not "the editor is
-attached". The editor's **Use preview** toggle turns it off while the editor
-stays open, so the canvas behaves like the live site: whatever you held open
-closes and links navigate again.
+`isDesigner` means "the editing affordances are on", not "the editor is attached". The editor's **Use preview** toggle turns it off while the editor stays open, so the canvas behaves like the live site: whatever you held open closes and links navigate again.
+
+## Reading the row a block is placed in
+
+A block dropped into a list's row layout (the child a designer marked as the
+row template of an order list, a product grid, an address list, …) renders once
+per row. The product lists open the product scope `useThemeProduct()` reads;
+every list also opens a row scope that carries the row itself:
+
+```ts
+import { useThemeRowScope } from '@akinon/pz-theme/src/blocks/row-scope';
+
+const scope = useThemeRowScope();
+```
+
+Inside a row it returns `{ listType, row, index }`, for example
+`listType: 'order-list'` with the order's `number` and `items` on `row`; anywhere
+else it returns `null`. `row` is the same record the row's bindings resolve
+against, so whatever a text block can bind to (`item.number`), code can read.
+Import it from that deep path for the same reason as `useThemePageContext`: the
+package root is not importable from a client module.
 
 ## Reporting what happened
 
-A custom unit can report a moment — a strip was seen, a lookbook was opened, a
-tab was changed — and the brand decides in its own repo what that moment means
-to GA4, Insider or its own service. The theme never names an analytics event and
-never pushes to a tag manager, which is why one renderer can serve brands whose
-schemas disagree.
+A custom unit can report a moment — a strip was seen, a lookbook was opened, a tab was changed — and the brand decides in its own repo what that moment means to GA4, Insider or its own service. The theme never names an analytics event and never pushes to a tag manager, which is why one renderer can serve brands whose schemas disagree.
 
 ```tsx
 import { useThemeSignal } from '@akinon/pz-theme/src/custom';
@@ -327,9 +258,7 @@ const LookbookStrip = () => {
 };
 ```
 
-For the "first time it becomes true" case — a section seen, a promo shown — use
-the latching form. A `null` key means "not ready yet" and reports nothing, which
-is what stops a unit reporting before the data it describes has resolved:
+For the "first time it becomes true" case — a section seen, a promo shown — use the latching form. A `null` key means "not ready yet" and reports nothing, which is what stops a unit reporting before the data it describes has resolved:
 
 ```tsx
 useThemeSignalOnce({
@@ -339,8 +268,7 @@ useThemeSignalOnce({
 });
 ```
 
-Outside React — a module-level bus, a delegated document listener — call the
-primitive directly:
+Outside React — a module-level bus, a delegated document listener — call the primitive directly:
 
 ```ts
 import { emitThemeSignal } from '@akinon/pz-theme/src/custom';
@@ -365,69 +293,42 @@ useEffect(
 
 Four things the emitter does so a call site does not have to:
 
-- **It is silent while the editor is attached, browse mode included.** It reads
-  the editor handshake flag itself, so do NOT wrap a report in an `isDesigner`
-  check — that prop means "the editing affordances are on", goes false under
-  **Use preview**, and a report guarded on it reports a designer's clicks as a
-  shopper's.
-- **`{ key, once: true }` is the latch**, reset on client-side navigation. A
-  repeat inside the same page view is a no-op.
-- **A ceiling** — 24 per key, 200 per page view. An autoplaying carousel would
-  otherwise emit continuously, billed to whatever the brand forwards to.
-- **The payload is closed to flat scalars** and sanitized at emit. A product
-  object, a DOM node or shopper-typed text is dropped with a dev warning, which
-  is how the no-PII rule is enforced rather than reviewed.
-
-A brand's own moment must be namespaced `custom.<something>`, so it can never
-collide with a name this package adds later and a bridge can tell the two apart.
-The package's own names are listed in `THEME_SIGNAL_NAMES`.
+- **It is silent while the editor is attached, browse mode included.** It reads the editor handshake flag itself, so do NOT wrap a report in an `isDesigner` check — that prop means "the editing affordances are on", goes false under **Use preview**, and a report guarded on it reports a designer's clicks as a shopper's.
+- **`{ key, once: true }` is the latch**, reset on client-side navigation. A repeat inside the same page view is a no-op.
+- **A ceiling** — 24 per key, 200 per page view. An autoplaying carousel would otherwise emit continuously, billed to whatever the brand forwards to.
+- **The payload is closed to flat scalars** and sanitized at emit. A product object, a DOM node or shopper-typed text is dropped with a dev warning, which is how the no-PII rule is enforced rather than reviewed.
+
+A brand's own moment must be namespaced `custom.<something>`, so it can never collide with a name this package adds later and a bridge can tell the two apart. The package's own names are listed in `THEME_SIGNAL_NAMES`.
 
 ## Styling parts
 
-The `field-<key>` parts come free from `ThemeEditable`. Everything else a block
-draws is offered to the properties panel only if it is DECLARED:
+The `field-<key>` parts come free from `ThemeEditable`. Everything else a block draws is offered to the properties panel only if it is DECLARED:
 
 ```ts
-parts: ['row', 'tile']                       // the cheap form
-parts: { row: { states: ['hover', 'open'] } } // when appearance depends on state
+parts: ['row', 'tile']; // the cheap form
+parts: {
+  row: {
+    states: ['hover', 'open'];
+  }
+} // when appearance depends on state
 ```
 
-Declare the same name you stamp with `partAttrs('row')`, or the panel offers a
-control nothing on the page answers to. Only states the renderer can actually
-match are accepted (`PART_STYLE_STATES` in `utils/part-styles.ts`) — a state
-with no selector emits CSS that can never apply, so it is refused with the
-available list. The `field-` prefix is reserved and cannot be declared.
+Declare the same name you stamp with `partAttrs('row')`, or the panel offers a control nothing on the page answers to. Only states the renderer can actually match are accepted (`PART_STYLE_STATES` in `utils/part-styles.ts`) — a state with no selector emits CSS that can never apply, so it is refused with the available list. The `field-` prefix is reserved and cannot be declared.
 
 ## Declare `settings` and `slots`
 
-Runtime collection exists as a fallback, but it only runs on a type's first
-render and never re-announces — so a block that declares nothing reaches the
-editor with an empty panel until the editor is reloaded. Declare them.
+Runtime collection exists as a fallback, but it only runs on a type's first render and never re-announces — so a block that declares nothing reaches the editor with an empty panel until the editor is reloaded. Declare them.
 
 ## What the merchant still cannot restyle
 
-A field's own `field-<key>` part carries no states: declaring one is refused,
-because the `field-` prefix belongs to `ThemeEditable`. To give a field element
-a hover appearance, wrap it in an element you stamp and declare yourself.
+A field's own `field-<key>` part carries no states: declaring one is refused, because the `field-` prefix belongs to `ThemeEditable`. To give a field element a hover appearance, wrap it in an element you stamp and declare yourself.
 
 ## Limits
 
-Forty types per build, twenty-four settings, eight slots and thirty-two parts
-per type, and a 256 KB catalog. The whole catalog is posted to the editor on
-every placeholder announce, which is what the caps are protecting.
+Forty types per build, twenty-four settings, eight slots and thirty-two parts per type, and a 256 KB catalog. The whole catalog is posted to the editor on every placeholder announce, which is what the caps are protecting.
 
-Every one of them is refused at declare time, because the editor's answer to an
-over-cap catalog is to drop ALL of it — a single block over the parts cap costs
-the build every block in the palette. The one cap a declaration cannot fully
-guarantee is the parts cap: an undeclared `ThemeEditable` discovered at render
-time adds a `field-<key>` part after registration counted them, and if that
-would cross the cap the part is dropped with a warning rather than the catalog
-being put over. The field keeps its control in the Content tab and loses only
-its styling group.
+Every one of them is refused at declare time, because the editor's answer to an over-cap catalog is to drop ALL of it — a single block over the parts cap costs the build every block in the palette. The one cap a declaration cannot fully guarantee is the parts cap: an undeclared `ThemeEditable` discovered at render time adds a `field-<key>` part after registration counted them, and if that would cross the cap the part is dropped with a warning rather than the catalog being put over. The field keeps its control in the Content tab and loses only its styling group.
 
 ## Failure behaviour
 
-A composition naming a type this build does not register renders nothing on the
-live site and a labelled card in the designer, and the editor shows the block as
-an orphan row rather than dropping it — its stored properties survive a save
-untouched, so a type that comes back finds its content where it left it.
+A composition naming a type this build does not register renders nothing on the live site and a labelled card in the designer, and the editor shows the block as an orphan row rather than dropping it — its stored properties survive a save untouched, so a type that comes back finds its content where it left it.

package/src/custom/__tests__/use-theme-setting.test.tsx

@@ -367,3 +367,100 @@ describe('useThemeSetting — invalid declarations throw in development', () =>
     ).toThrow(/not one of the editor's control types/);
   });
 });
+
+describe('useThemeSetting — richtext', () => {
+  it('reads the breakpoint’s html and strips what the allowlist refuses', () => {
+    const { result } = renderHook(
+      () =>
+        useThemeSetting('body', {
+          type: 'richtext',
+          label: 'Body',
+          default: '<p>default</p>'
+        }),
+      {
+        wrapper: wrapperFor(
+          contextValue({
+            currentBreakpoint: 'mobile',
+            properties: {
+              body: {
+                desktop: '<p>desktop</p>',
+                mobile:
+                  '<p onclick="x()">mobile <script>x</script><b>bold</b></p>'
+              }
+            }
+          })
+        )
+      }
+    );
+
+    expect(result.current).toBe('<p>mobile <b>bold</b></p>');
+  });
+
+  it('sanitizes the authored default too', () => {
+    const { result } = renderHook(
+      () =>
+        useThemeSetting('body', {
+          type: 'richtext',
+          label: 'Body',
+          default: '<p><img src=x onerror=alert(1)>safe</p>'
+        }),
+      { wrapper: wrapperFor(contextValue()) }
+    );
+
+    expect(result.current).toBe('<p>safe</p>');
+  });
+
+  describe('written per language by the rich text control', () => {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const hooks = require('@akinon/next/hooks');
+    let localizationSpy: jest.SpyInstance;
+
+    const onPage = (locale: string) => {
+      const original = hooks.useLocalization;
+      localizationSpy = jest
+        .spyOn(hooks, 'useLocalization')
+        .mockImplementation(() => ({
+          ...original(),
+          locale,
+          defaultLocaleValue: 'tr',
+          locales: [{ value: 'tr' }, { value: 'en' }]
+        }));
+    };
+
+    afterEach(() => localizationSpy?.mockRestore());
+
+    const read = (body: unknown) =>
+      renderHook(
+        () =>
+          useThemeSetting('body', {
+            type: 'richtext',
+            label: 'Body',
+            default: '<p>default</p>'
+          }),
+        { wrapper: wrapperFor(contextValue({ properties: { body } })) }
+      ).result.current;
+
+    it('reads the page’s language out of the locale map and sanitizes it', () => {
+      onPage('tr');
+
+      expect(
+        read({
+          en: '<p>old</p>',
+          tr: '<p>sss <b>bold</b><script>x()</script></p>'
+        })
+      ).toBe('<p>sss <b>bold</b></p>');
+    });
+
+    it('falls back to the default language’s entry', () => {
+      onPage('en');
+
+      expect(read({ tr: '<p>türkçe</p>' })).toBe('<p>türkçe</p>');
+    });
+
+    it('still reads a breakpoint map written in the default language', () => {
+      onPage('tr');
+
+      expect(read({ desktop: '<p>desktop</p>' })).toBe('<p>desktop</p>');
+    });
+  });
+});

package/src/custom/collect.ts

@@ -42,9 +42,7 @@ import type { CustomSettingDescriptor, CustomSlotDescriptor } from './types';
  * through the one function below.
  */
 export type ThemeSettingChoice =
-  | string
-  | number
-  | { label?: string; value: unknown };
+  string | number | { label?: string; value: unknown };
 
 /**
  * Normalizes the shorthand into the `{label, value}` pairs the editor's select
@@ -80,8 +78,8 @@ export const normalizeSettingChoices = (
 
 /**
  * Why a control type is refused, named per type. "Unsupported" tells a
- * developer nothing actionable; each of these three fails for its own reason
- * and each has a different way out.
+ * developer nothing actionable; each of these fails for its own reason and
+ * each has a different way out.
  */
 const UNSUPPORTED_TYPE_REASON: Record<string, string> = {
   multiselect:
@@ -90,10 +88,7 @@ const UNSUPPORTED_TYPE_REASON: Record<string, string> = {
     'Use "select" and store one value until a per-type resolver exists',
   localetext:
     'the editor stores a localetext value as a locale map with no "desktop" key, so getResponsiveValue ' +
-    'falls back and the block would read its authored default forever. Use "text" and localize in the component',
-  richtext:
-    'there is no safe renderer for it here — the sanitizer this repo owns parses by assigning to innerHTML ' +
-    'on a live element, and pz-theme renders on the server where there is no document at all. Use "text"'
+    'falls back and the block would read its authored default forever. Use "text" and localize in the component'
 };
 
 /** The reason a setting key is refused, or null. Shared by the declared and the collected path. */