@akinon/pz-theme 2.0.71-beta.0 → 2.0.71

package/src/custom/README.md

@@ -0,0 +1,249 @@
+# 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.
+
+## 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.
+
+```tsx
+// src/theme-blocks/complete-the-look.tsx
+'use client';
+
+import {
+  defineCustomBlock,
+  partAttrs,
+  ThemeEditable,
+  ThemeSlot,
+  useThemeSetting
+} from '@akinon/pz-theme/src/custom';
+
+function CompleteTheLook() {
+  const productCount = useThemeSetting('productCount', {
+    type: 'slider',
+    label: 'How many products',
+    default: 4,
+    min: 2,
+    max: 8
+  });
+
+  const products = useRecommendations(productCount);
+
+  return (
+    <section>
+      <ThemeEditable name="heading">
+        <h2>Complete the look</h2>
+      </ThemeEditable>
+
+      <div>
+        {products.map((product) => (
+          <article key={product.pk} {...partAttrs('card')}>
+            <img src={product.image} alt="" />
+            <span {...partAttrs('price')}>{product.price}</span>
+          </article>
+        ))}
+      </div>
+
+      <ThemeSlot name="campaign" label="Campaign banner" />
+    </section>
+  );
+}
+
+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 }
+  ],
+  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.
+
+```ts
+// src/theme-blocks/index.ts
+import { registerCustomBlocks } from '@akinon/pz-theme/src/custom';
+import CompleteTheLook from './complete-the-look';
+
+registerCustomBlocks('gant', { 'complete-the-look': CompleteTheLook });
+```
+
+```ts
+// src/app/[pz]/client-root.tsx — CLIENT ROOT ONLY
+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.
+
+## 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.
+
+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`.
+
+## `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.
+
+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.
+
+## `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.
+
+React's own rule that hooks are called unconditionally is doing useful work
+here: the language enforces that the declaration set is static.
+
+## `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.
+
+### Narrowing what a slot takes
+
+```ts
+slots: [
+  { 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.
+
+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.
+
+## 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:
+
+```ts
+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 `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.
+
+## 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.
+
+## 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.
+
+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.