@akinon/pz-theme 2.0.78-rc.1 → 2.0.78

package/src/custom/define-section.tsx

@@ -0,0 +1,163 @@
+import type React from 'react';
+import type { CustomPartsDeclaration } from './parts';
+import type { CustomSettingDeclaration, CustomSlotDeclaration } from './define';
+
+/**
+ * A developer section component takes NO props, for the same reason a block
+ * does: everything it needs — the section node, the breakpoint, the designer
+ * flag — arrives through `CustomBlockContext`, so a `<ThemeRegion>` five levels
+ * down resolves without the developer threading anything through their tree.
+ */
+export type CustomSectionComponent = React.ComponentType<Record<string, never>>;
+
+/**
+ * One child the developer names and PLACES in JSX with `<ThemeRegion name=…>`.
+ *
+ * `block` is the type it is born as. The developer writes no descriptor for it:
+ * naming `search-box` is what buys the whole search-box panel, its shared
+ * controls and its part groups. That is the difference between this design and
+ * the retired one, where every child's controls had to be described by hand and
+ * the descriptors grew to 16,058 lines.
+ *
+ * `properties` and `styles` are the seed — what the region looks like the
+ * moment the section is added, before anyone has touched it. They are applied
+ * ONCE, at insert. Nothing re-applies them on a later load, so a merchant's
+ * edit is never quietly reverted.
+ */
+export interface CustomRegionDeclaration {
+  name: string;
+  /** The layer-tree row name. Defaults to the region name. */
+  label?: string;
+  block: string;
+  properties?: Record<string, unknown>;
+  styles?: Record<string, unknown>;
+  /**
+   * The block's own `value`, for the block types that keep their content there
+   * rather than in `properties` — an `image` reads `block.value` for its src, a
+   * `text` reads it for its text. Without this a seeded logo would come up
+   * blank and the merchant would have to find and re-upload an asset the brand
+   * already ships.
+   *
+   * Seeded ONCE, at insert, like `properties` and `styles`.
+   */
+  value?: unknown;
+}
+
+export interface CustomSectionOptions {
+  /** Shown in the editor's Add Section band. Defaults to the registration name. */
+  label?: string;
+  icon?: string;
+  /** The band this section is filed under. Defaults to the vendor's own band. */
+  group?: string;
+  settings?: CustomSettingDeclaration[];
+  /**
+   * The children the developer placed. Order here is the order they are seeded
+   * into `section.blocks`, which is the order the layer tree shows — but NOT
+   * what decides where they appear on screen. The JSX owns that, and no
+   * reordering in the tree can change it.
+   */
+  regions?: CustomRegionDeclaration[];
+  /** Merchant-fillable openings, identical in every way to a block's slots. */
+  slots?: CustomSlotDeclaration[];
+  /**
+   * Elements the developer stamped with `partAttrs()` that the merchant may
+   * restyle. Section parts already emit CSS — `generatePartCSS` runs against
+   * the section selector — and this is the declaration that gives them a panel.
+   */
+  parts?: CustomPartsDeclaration;
+  /** The section root's styles at insert. Same one-shot seed rule as a region's. */
+  styles?: Record<string, unknown>;
+  /**
+   * Placeholder slugs this section is offered on — `['header']` for a header.
+   * Absent means anywhere.
+   */
+  placeholders?: string[];
+  /**
+   * Keeps `rotate`, `scale`, `translate`, `filter` and `backdrop-filter` off the
+   * section root's panel.
+   *
+   * Set it on any section whose design contains a `position: fixed` or
+   * `sticky` descendant. Each of those five properties creates a containing
+   * block for a fixed descendant, so one of them applied to the root collapses
+   * the fixed child into the root's own box — a header measured at 1247px wide
+   * became 600px. The merchant has no way to know that and nothing reports it.
+   */
+  lockRootTransforms?: boolean;
+}
+
+/**
+ * Tag value, not a `Symbol` — see `CUSTOM_BLOCK_MARKER`. A brand can resolve two
+ * physical copies of pz-theme at once, and a `Symbol()` per copy would make one
+ * copy read the other's definition as a bare component, silently dropping every
+ * option the developer declared.
+ */
+export const CUSTOM_SECTION_MARKER = 'pz-theme.custom-section';
+
+export interface CustomSectionDefinition {
+  readonly $$pzCustomSection: typeof CUSTOM_SECTION_MARKER;
+  component: CustomSectionComponent;
+  options: CustomSectionOptions;
+}
+
+export type CustomSectionInput =
+  | CustomSectionDefinition
+  | CustomSectionComponent;
+
+// React.memo() and forwardRef() return objects rather than functions, and a
+// brand wrapping its section in either is ordinary React.
+const isRenderable = (value: unknown): value is CustomSectionComponent =>
+  typeof value === 'function' ||
+  (typeof value === 'object' && value !== null && '$$typeof' in value);
+
+export const isCustomSectionDefinition = (
+  value: unknown
+): value is CustomSectionDefinition =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as { $$pzCustomSection?: unknown }).$$pzCustomSection ===
+    CUSTOM_SECTION_MARKER;
+
+/**
+ * Wraps a section component with the options the editor needs.
+ *
+ * Like `defineCustomBlock` it deliberately does NOT read `Component.name`:
+ * production builds minify it, so a section authored as `ZsaHeader` would
+ * register as `t` on the storefront and as `ZsaHeader` in dev, and one
+ * composition would render in one build and be an unknown type in the other.
+ * The name lives at registration, keyed by the record.
+ *
+ *   export default defineCustomSection(ZsaHeader, { label: 'ZSA ZSA ZSU Header' });
+ */
+export const defineCustomSection = (
+  component: CustomSectionComponent,
+  options: CustomSectionOptions = {}
+): CustomSectionDefinition => {
+  if (!isRenderable(component)) {
+    throw new Error(
+      `[pz-theme] defineCustomSection() expects a React component, received ${typeof component}. ` +
+        `Pass the component itself, not the result of calling it.`
+    );
+  }
+
+  return Object.freeze({
+    $$pzCustomSection: CUSTOM_SECTION_MARKER,
+    component,
+    options
+  });
+};
+
+/** Accepts the wrapper or a bare component — see `normalizeCustomBlock`. */
+export const normalizeCustomSection = (
+  input: CustomSectionInput,
+  name: string
+): CustomSectionDefinition => {
+  if (isCustomSectionDefinition(input)) return input;
+
+  if (isRenderable(input)) return defineCustomSection(input);
+
+  throw new Error(
+    `[pz-theme] Custom section "${name}" is neither a React component nor a defineCustomSection() result ` +
+      `(received ${input === null ? 'null' : typeof input}). ` +
+      `Check the barrel entry — a missing default export lands here as undefined.`
+  );
+};

package/src/custom/index.ts

@@ -51,7 +51,70 @@ export type {
 
 export type { CustomPartDeclaration, CustomPartsDeclaration } from './parts';
 
-export { registerCustomBlocks } from './register';
+export { registerCustomBlocks, registerCustomSections } from './register';
+
+/**
+ * The SECTION authoring API.
+ *
+ * A section is what a developer reaches for when the whole area is theirs — a
+ * header, a product detail page — rather than one element inside an area the
+ * merchant composed. Two things follow from that and neither is available to a
+ * block:
+ *
+ * - The section root gets the section root panel: the geometry family and
+ *   Content Width, which the editor adds only for a section root or a part.
+ * - There is no merchant-created wrapper around it. A custom block has to live
+ *   inside a section somebody added, and that wrapper can carry `transform` or
+ *   `filter` — either of which traps a `position: fixed` descendant, measured
+ *   as a 1247px header collapsing to 600px. When the header IS the section, the
+ *   wrapper stops existing.
+ *
+ * The shape a brand writes:
+ *
+ *   // views/header/zzz-header.tsx
+ *   import { defineCustomSection, ThemeRegion, ThemeSlot, partAttrs }
+ *     from '@akinon/pz-theme/src/custom';
+ *
+ *   function ZsaHeader() {
+ *     return (
+ *       <header {...partAttrs('bar')}>
+ *         <ThemeRegion name="logo" />
+ *         <ThemeRegion name="basket" />
+ *         <ThemeSlot name="extras" label="Extra header actions" />
+ *       </header>
+ *     );
+ *   }
+ *
+ *   export default defineCustomSection(ZsaHeader, {
+ *     label: 'ZSA ZSA ZSU Header',
+ *     regions: [
+ *       { name: 'logo', label: 'Logo', block: 'image' },
+ *       { name: 'basket', label: 'Basket', block: 'mini-basket' }
+ *     ],
+ *     slots: [{ name: 'extras', label: 'Extra header actions' }],
+ *     lockRootTransforms: true
+ *   });
+ *
+ *   // views/header/index.ts — imported from the CLIENT ROOT only
+ *   registerCustomSections('zsazsazsu', { header: ZsaHeader });
+ *
+ * A REGION AND A SLOT ARE DIFFERENT PROMISES. A region is a child the developer
+ * named, chose the type of and PLACED; the merchant styles it, configures it,
+ * hides it or deletes it, but cannot reorder it or insert beside it, because
+ * the JSX owns the layout. A slot is an opening the merchant fills with
+ * whatever they like, in whatever order. Say which one you mean in the label.
+ */
+export { defineCustomSection } from './define-section';
+export type {
+  CustomRegionDeclaration,
+  CustomSectionComponent,
+  CustomSectionDefinition,
+  CustomSectionInput,
+  CustomSectionOptions
+} from './define-section';
+
+export { ThemeRegion } from './theme-region';
+export type { ThemeRegionProps } from './theme-region';
 
 export { ThemeEditable } from './theme-editable';
 export type { ThemeEditableProps } from './theme-editable';
@@ -78,6 +141,13 @@ export type {
   PropertyType
 } from './types';
 
+export { getCustomSectionCatalog } from './section-catalog';
+export type {
+  CustomRegionDescriptor,
+  CustomSectionCatalog,
+  CustomSectionDescriptor
+} from './section-types';
+
 // The predicate, not the pattern. Every consumer that has to treat a
 // developer-authored type differently tests this one function, so the grammar
 // stays in types.ts and cannot be re-derived slightly wrong somewhere else.
@@ -92,6 +162,18 @@ export { CUSTOM_TYPE_PREFIX, isCustomThemeType } from './types';
 export { CUSTOM_SLOT_BLOCK_TYPE, SLOT_NAME_PROPERTY } from './types';
 export { isSlotNode, slotNodeName } from './slot-nodes';
 
+/**
+ * The region grammar, exported for the same reason the slot grammar is: the
+ * editor holds a mirror of it, and a mirror can be diffed against one exported
+ * constant instead of a literal re-typed slightly wrong.
+ *
+ * `REGION_NAME_PROPERTY` is a reserved key on an ORDINARY block — a region is
+ * not a wrapper node, which is the whole point: the merchant gets that block
+ * type's own panel.
+ */
+export { REGION_NAME_PROPERTY, CUSTOM_SECTION_LIMITS } from './section-types';
+export { findRegionChild, isRegionNode, regionNodeName } from './region-nodes';
+
 /**
  * Re-exported so a custom block is written against ONE module.
  *

package/src/custom/region-nodes.ts

@@ -0,0 +1,72 @@
+import type { Block } from '../theme-block';
+import { REGION_NAME_PROPERTY } from './section-types';
+
+/**
+ * Reading regions back out of a composition.
+ *
+ * A declared region is seeded as one ORDINARY block in `section.blocks`,
+ * carrying `properties.regionName`. `<ThemeRegion name="search" />` finds that
+ * block and hands it to the same child pipeline every container uses, so the
+ * merchant styles and configures it through the panel that block type already
+ * has.
+ *
+ * THE ASYMMETRY WITH SLOTS IS DELIBERATE AND LOAD-BEARING. `resolveSlotChildren`
+ * has a legacy branch that treats a block's direct children as the content of
+ * its unnamed slot. Nothing like it can exist here: a section's direct children
+ * are the merchant's ordinary composed blocks, so a bare region falling back to
+ * them would swallow the entire section. A region resolves by NAME or not at
+ * all, and there is no unnamed region.
+ *
+ * Directive-free on purpose — `register.ts`, `theme-region.tsx` and the editor
+ * mirror all need the same answers, and only the second is a client module.
+ */
+
+/**
+ * The region name a block carries, or the empty string when it carries none.
+ *
+ * Both a bare string and a per-breakpoint bucket are read, for exactly the
+ * reason `slotNodeName` reads both: every other value in `block.properties` is
+ * per-breakpoint and the editor's `handlePropertyChange` re-buckets whatever it
+ * is given, so a bare-string-only reader would detach every region in every
+ * published composition the day anything routes this key through a property
+ * control.
+ */
+export const regionNodeName = (block: Block): string => {
+  const raw = block.properties?.[REGION_NAME_PROPERTY];
+
+  if (typeof raw === 'string') return raw;
+
+  if (raw && typeof raw === 'object') {
+    const desktop = (raw as Record<string, unknown>).desktop;
+    if (typeof desktop === 'string') return desktop;
+  }
+
+  return '';
+};
+
+export const isRegionNode = (block: Block): boolean =>
+  regionNodeName(block) !== '';
+
+/**
+ * The block seeded for one region, or null when the merchant deleted it.
+ *
+ * Null is NOT an error. Deleting a region is an ordinary composition edit and
+ * has to stay durable — a merchant who removes the language switcher from the
+ * header expects it gone on the next load, not re-seeded. The caller decides
+ * what to draw in its place, and only the designer draws anything.
+ *
+ * The FIRST match wins. Two blocks carrying one region name is only reachable
+ * by duplicating a region row in the layer tree; rendering both would put two
+ * `data-block-id` wrappers under one `<ThemeRegion>`, and the second is
+ * unreachable from the JSX either way.
+ */
+export const findRegionChild = (
+  container: { blocks?: Block[] } | null | undefined,
+  name: string
+): Block | null => {
+  if (!name) return null;
+
+  const children = container?.blocks ?? [];
+
+  return children.find((child) => regionNodeName(child) === name) ?? null;
+};