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

package/src/custom/define.tsx

@@ -0,0 +1,172 @@
+import type React from 'react';
+import type { CustomPartsDeclaration } from './parts';
+import type { PropertyType } from './types';
+
+/**
+ * A developer component takes NO props. Everything it needs — the block, the
+ * breakpoint, the designer flag — arrives through `CustomBlockContext`, which
+ * is what lets a `<ThemeEditable>` five levels down work without threading.
+ * Typing the props as empty is deliberate: a component that declares required
+ * props fails to compile here rather than rendering with `undefined` for all
+ * of them, because nothing on the render path will ever supply one.
+ */
+export type CustomBlockComponent = React.ComponentType<Record<string, never>>;
+
+export interface CustomSettingOption {
+  label?: string;
+  value: unknown;
+}
+
+/**
+ * What a developer writes. Looser than `CustomSettingDescriptor` in exactly two
+ * places — `label` may be omitted, and an option may be a bare string/number —
+ * because those are the two shapes people write by hand. Registration
+ * normalizes both into the descriptor the editor receives.
+ */
+export interface CustomSettingDeclaration {
+  key: string;
+  type: PropertyType;
+  label?: string;
+  defaultValue?: unknown;
+  options?: Array<CustomSettingOption | string | number>;
+  min?: number;
+  max?: number;
+  step?: number;
+  unit?: string;
+  maxLength?: number;
+  helpText?: string;
+  group?: string;
+  showWhen?: { key: string; value: unknown };
+  /** Content field rather than a behaviour knob — see `CustomSettingDescriptor.editable`. */
+  editable?: boolean;
+}
+
+/**
+ * One merchant-fillable region. Each declared slot materializes as one
+ * reserved-type CHILD NODE of the block, so a block declaring three slots gets
+ * three tree rows the merchant fills independently.
+ *
+ * `name` stays optional, and omitting it stays meaningful: a block that
+ * declares a single slot needs no name at all, which is exactly what every
+ * block written against the original single-slot API already does.
+ */
+export interface CustomSlotDeclaration {
+  name?: string;
+  label?: string;
+  /** Carried to the editor; pz-theme does not enforce acceptance yet. */
+  accepts?: string[];
+  max?: number;
+}
+
+export interface CustomBlockOptions {
+  /** Shown in the editor's block picker. Defaults to the registration name. */
+  label?: string;
+  icon?: string;
+  group?: string;
+  /**
+   * Optional. An undeclared block still works: the runtime collector in
+   * `collect.ts` fills the descriptor from the first render, and the
+   * build-time extractor will supersede both. Declaring is what buys a
+   * complete picker entry BEFORE the block has ever been placed once.
+   */
+  settings?: CustomSettingDeclaration[];
+  slots?: CustomSlotDeclaration[];
+  /**
+   * Elements the developer stamped with `partAttrs()` that the merchant may
+   * restyle from the properties panel.
+   *
+   * `['row', 'tile']` for parts with one appearance, `{ row: { states:
+   * ['hover', 'open'] } }` for the ones whose appearance depends on what the
+   * shopper is doing. The field-derived `field-<key>` parts are added for free
+   * and must not be declared here.
+   */
+  parts?: CustomPartsDeclaration;
+}
+
+/**
+ * Tag value, not a `Symbol`.
+ *
+ * A brand can end up with two physical copies of pz-theme resolved at once — a
+ * hoisted one beside a nested one, or the installed package beside the stale
+ * copy webpack keeps serving out of `.next`. Each copy would own a distinct
+ * `Symbol()`, so a definition made by one copy would read as an unwrapped
+ * component to the other, silently losing every option the developer declared.
+ * A string tag compares equal across the copy boundary, and it is greppable.
+ */
+export const CUSTOM_BLOCK_MARKER = 'pz-theme.custom-block';
+
+export interface CustomBlockDefinition {
+  readonly $$pzCustomBlock: typeof CUSTOM_BLOCK_MARKER;
+  component: CustomBlockComponent;
+  options: CustomBlockOptions;
+}
+
+/** What `registerCustomBlocks` accepts per entry. */
+export type CustomBlockInput = CustomBlockDefinition | CustomBlockComponent;
+
+// React.memo() and forwardRef() return objects rather than functions. A brand
+// wrapping its block in either is ordinary React, so both have to pass.
+const isRenderable = (value: unknown): value is CustomBlockComponent =>
+  typeof value === 'function' ||
+  (typeof value === 'object' && value !== null && '$$typeof' in value);
+
+export const isCustomBlockDefinition = (
+  value: unknown
+): value is CustomBlockDefinition =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as { $$pzCustomBlock?: unknown }).$$pzCustomBlock ===
+    CUSTOM_BLOCK_MARKER;
+
+/**
+ * Wraps a component with the options the editor needs, and nothing else.
+ *
+ * It deliberately does NOT know its own name. `Component.name` is the obvious
+ * source and it is a trap: every production build minifies it, so a block
+ * authored as `PromoStrip` would register as `t` on the storefront and as
+ * `PromoStrip` in dev — the same composition would then render in one and be
+ * an unknown type in the other. The name lives at registration instead, keyed
+ * by the record, where minification cannot reach it.
+ *
+ * The documented shape is `export default defineCustomBlock(PromoStrip)`.
+ */
+export const defineCustomBlock = (
+  component: CustomBlockComponent,
+  options: CustomBlockOptions = {}
+): CustomBlockDefinition => {
+  if (!isRenderable(component)) {
+    throw new Error(
+      `[pz-theme] defineCustomBlock() expects a React component, received ${typeof component}. ` +
+        `Pass the component itself, not the result of calling it.`
+    );
+  }
+
+  return Object.freeze({
+    $$pzCustomBlock: CUSTOM_BLOCK_MARKER,
+    component,
+    options
+  });
+};
+
+/**
+ * Accepts the wrapper or a bare component.
+ *
+ * Someone will forget `defineCustomBlock` — the barrel entry looks identical
+ * either way — and a bare component is a complete block with no declared
+ * options, which is a shape the runtime collector already supports. Refusing
+ * it would buy nothing but a stack trace.
+ */
+export const normalizeCustomBlock = (
+  input: CustomBlockInput,
+  name: string
+): CustomBlockDefinition => {
+  if (isCustomBlockDefinition(input)) return input;
+
+  if (isRenderable(input)) return defineCustomBlock(input);
+
+  throw new Error(
+    `[pz-theme] Custom block "${name}" is neither a React component nor a defineCustomBlock() result ` +
+      `(received ${input === null ? 'null' : typeof input}). ` +
+      `Check the barrel entry — a missing default export lands here as undefined.`
+  );
+};

package/src/custom/editable-tags.ts

@@ -0,0 +1,120 @@
+import type { PropertyType } from './property-types';
+
+/**
+ * What a `ThemeEditable` does to the element it wraps.
+ *
+ * Deliberately NOT `PropertyType`. A kind answers "which prop carries the
+ * value", which is a render question; a `PropertyType` answers "which control
+ * does the panel draw", which is an editor question. They are one-to-one for
+ * three of the four members and one-to-TWO for `link` — a link is a label and
+ * a destination, and no single control edits both — so collapsing the two
+ * vocabularies would make `link` unrepresentable.
+ */
+export type EditableKind = 'text' | 'image' | 'link' | 'file';
+
+/**
+ * Tag -> kind. The wrapped JSX is the only place a developer states intent, so
+ * this map is what lets `<ThemeEditable name="headline"><h2>…</h2></…>` need no
+ * `type` prop at all.
+ *
+ * Only tags whose value target is unambiguous are listed. A `<div>` is absent
+ * on purpose: it may hold text, or a background image, or nothing the author
+ * meant to be edited, and cloning it with the wrong prop would silently blank
+ * the element. An explicit `type` is the escape hatch for those.
+ */
+export const EDITABLE_TAG_KINDS: Readonly<Record<string, EditableKind>> = {
+  img: 'image',
+
+  h1: 'text',
+  h2: 'text',
+  h3: 'text',
+  h4: 'text',
+  h5: 'text',
+  h6: 'text',
+  p: 'text',
+  span: 'text',
+  strong: 'text',
+  em: 'text',
+  small: 'text',
+  label: 'text',
+  li: 'text',
+  blockquote: 'text',
+
+  a: 'link',
+
+  video: 'file',
+  source: 'file'
+};
+
+export const EDITABLE_KINDS: readonly EditableKind[] = [
+  'text',
+  'image',
+  'link',
+  'file'
+];
+
+export const isEditableKind = (value: unknown): value is EditableKind =>
+  typeof value === 'string' &&
+  (EDITABLE_KINDS as readonly string[]).includes(value);
+
+/** Returns null for a tag with no unambiguous value target — see the map above. */
+export const inferEditableKind = (tag: string): EditableKind | null =>
+  EDITABLE_TAG_KINDS[tag] ?? null;
+
+/**
+ * The prop the resolved value is cloned onto.
+ *
+ * `link` writes `children` here and its href separately, because the href
+ * comes from a second setting with its own key.
+ */
+export const EDITABLE_KIND_TARGET: Readonly<
+  Record<EditableKind, 'children' | 'src'>
+> = {
+  text: 'children',
+  image: 'src',
+  file: 'src',
+  link: 'children'
+};
+
+/**
+ * The control the editor draws for each kind.
+ *
+ * Every member resolves to something in `SUPPORTED_PROPERTY_TYPES` — a kind
+ * that mapped to `richtext`, `multiselect` or `localetext` would render a
+ * control whose value can never reach the element (see property-types.ts).
+ */
+export const EDITABLE_KIND_PROPERTY_TYPES: Readonly<
+  Record<EditableKind, PropertyType>
+> = {
+  text: 'text',
+  image: 'image',
+  file: 'file',
+  // The label half. The destination half is a separate `url` setting.
+  link: 'text'
+};
+
+/**
+ * Suffix for a link's destination key: `cta` -> `ctaHref`.
+ *
+ * Capitalized so the derived key still satisfies `SETTING_KEY_PATTERN`, which
+ * allows camelCase but no separators.
+ */
+export const LINK_HREF_SUFFIX = 'Href';
+
+export const hrefKeyFor = (key: string): string => `${key}${LINK_HREF_SUFFIX}`;
+
+/**
+ * Prefix for the `data-part` a field element carries.
+ *
+ * Namespaced so a content field can never collide with a styling part the
+ * developer chose (`title`, `icon`, `panel` — all already published in live
+ * compositions), and so the editor can tell the two apart from the part name
+ * alone when it decides whether to offer the content control on the part.
+ *
+ * `sanitizePartName` (utils/part-styles.ts) keeps `[A-Za-z0-9_-]`, so both the
+ * hyphen here and a camelCase key survive into the generated selector intact.
+ */
+export const FIELD_PART_PREFIX = 'field-';
+
+export const fieldPartName = (key: string): string =>
+  `${FIELD_PART_PREFIX}${key}`;

package/src/custom/index.ts

@@ -0,0 +1,105 @@
+/**
+ * The custom block authoring API — everything a brand developer imports.
+ *
+ * THE BRAND BARREL IS IMPORTED FROM THE CLIENT ROOT ONLY — never from the
+ * server layout as well. `register.ts` carries `'use client'` because it must:
+ * it imports `blockRendererRegistry`, which pulls in all ~99 block modules, and
+ * most of those call hooks without a directive of their own. Reaching them from
+ * a server graph fails the brand's build at `accordion-block.tsx:1` with
+ * "You're importing a module that depends on `useState` into a React Server
+ * Component module". This was found by building a brand, not by a test — jest
+ * has no RSC graph, so the whole suite was green over it.
+ *
+ * Client-only registration loses nothing. `theme-block.tsx` is the single
+ * production reader of the renderer 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 module graph.
+ *
+ * Use this deep path, not the package root. `@akinon/pz-theme` re-exports the
+ * same symbols but also re-exports `ThemePlaceholder`, which imports
+ * `server-only`, so importing `registerCustomBlocks` from the root fails a
+ * client module with "cannot be imported from a Client Component module".
+ *
+ * The shape a brand writes:
+ *
+ *   // blocks/promo-strip.tsx
+ *   import { defineCustomBlock, ThemeEditable, ThemeSlot, useThemeSetting }
+ *     from '@akinon/pz-theme/src/custom';
+ *   export default defineCustomBlock(PromoStrip);
+ *
+ *   // blocks/index.ts — imported from the CLIENT ROOT only
+ *   registerCustomBlocks('acme', { 'promo-strip': PromoStrip });
+ *
+ * The block NAME lives in that record, never in `Component.name`: every
+ * production build minifies the function name, so a block authored as
+ * `PromoStrip` would register as `t` on the storefront and as `PromoStrip` in
+ * dev, and one composition would render in one build and be an unknown type in
+ * the other.
+ */
+
+export { defineCustomBlock } from './define';
+export type {
+  CustomBlockComponent,
+  CustomBlockDefinition,
+  CustomBlockInput,
+  CustomBlockOptions,
+  CustomSettingDeclaration,
+  CustomSettingOption,
+  CustomSlotDeclaration
+} from './define';
+
+export type { CustomPartDeclaration, CustomPartsDeclaration } from './parts';
+
+export { registerCustomBlocks } from './register';
+
+export { ThemeEditable } from './theme-editable';
+export type { ThemeEditableProps } from './theme-editable';
+export type { EditableKind } from './editable-tags';
+
+export { ThemeSlot } from './theme-slot';
+export type { ThemeSlotProps } from './theme-slot';
+
+export { useThemeSetting } from './use-theme-setting';
+export type {
+  ThemeSettingChoice,
+  ThemeSettingOptions
+} from './use-theme-setting';
+
+// What the editor bridge announces. Exported here rather than kept internal
+// because a brand that mounts its own announce path needs the same payload the
+// package would have sent, not a second construction of it.
+export { getCustomCatalog } from './catalog';
+export type {
+  CustomBlockDescriptor,
+  CustomCatalog,
+  CustomSettingDescriptor,
+  CustomSlotDescriptor,
+  PropertyType
+} from './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.
+export { CUSTOM_TYPE_PREFIX, isCustomThemeType } from './types';
+
+/**
+ * The slot-node grammar, exported for the same reason the type predicate is:
+ * the editor and the generator each hold a mirror of it, and a mirror can be
+ * diffed against one exported constant instead of a literal re-typed slightly
+ * wrong. `isSlotNode` is the one spelling of the check.
+ */
+export { CUSTOM_SLOT_BLOCK_TYPE, SLOT_NAME_PROPERTY } from './types';
+export { isSlotNode, slotNodeName } from './slot-nodes';
+
+/**
+ * Re-exported so a custom block is written against ONE module.
+ *
+ * `partAttrs` is what makes a developer's own markup addressable from the
+ * styling panel, so it is needed by essentially every block that has more than
+ * one element — and `ThemeEditable` already stamps its fields with it. Sending
+ * a developer to `@akinon/pz-theme/src/utils/part-styles` for the other half of
+ * the same job is the kind of split that ends in a hand-written
+ * `data-part="…"`, which `sanitizePartName` then has no chance to normalize.
+ */
+export { partAttrs } from '../utils/part-styles';

package/src/custom/parts.ts

@@ -0,0 +1,108 @@
+import { PART_STYLE_STATES } from '../utils/part-styles';
+import { FIELD_PART_PREFIX } from './editable-tags';
+import { PART_NAME_PATTERN } from './types';
+
+/**
+ * Developer-declared styling parts.
+ *
+ * Until now `descriptor.parts` was filled ONLY from `ThemeEditable` fields, so
+ * an element a developer stamped with `partAttrs('menuRow')` never reached the
+ * properties panel — a brand writing a menu could style its rows in its own
+ * stylesheet and nowhere else. The editor side already knows what to do with a
+ * declared part (it appends the advanced CSS families, the geometry family and
+ * the per-part custom-CSS hatch to any part group it is given); what was
+ * missing was the declaration reaching it.
+ *
+ * States are the reason this is not just a list of names. An active menu row,
+ * an open accordion header, a hovered tile — those are the whole point of
+ * styling a part, and a part with no states can express none of them.
+ */
+
+/** What a part declares beyond existing. */
+export interface CustomPartDeclaration {
+  /**
+   * Must be states the RENDERER can match — `PART_STYLE_STATES`. A state with
+   * no selector expression behind it produces a control that writes CSS which
+   * can never apply, which reads as "the editor does not save".
+   */
+  states?: readonly string[];
+}
+
+/**
+ * Both spellings a developer writes.
+ *
+ * The bare array is the cheap one and it is genuinely enough for a part that
+ * only ever has one appearance. The record is the one that carries states. They
+ * cost one normalizer between them, so both are accepted rather than making
+ * every block pay the record's syntax for a part that needs nothing from it.
+ */
+export type CustomPartsDeclaration =
+  | readonly string[]
+  | Readonly<Record<string, CustomPartDeclaration | true>>;
+
+export interface NormalizedPart {
+  name: string;
+  states: string[];
+}
+
+/**
+ * One shape out of the two, in the order the developer wrote them.
+ *
+ * Object key order is insertion order for non-numeric string keys, so a record
+ * is as deterministic as an array here — which matters because this order is
+ * the order the part groups appear in the properties panel.
+ */
+export const normalizePartsDeclaration = (
+  declaration: CustomPartsDeclaration | undefined
+): NormalizedPart[] => {
+  if (!declaration) return [];
+
+  if (Array.isArray(declaration)) {
+    return (declaration as readonly unknown[]).map((name) => ({
+      name: String(name),
+      states: []
+    }));
+  }
+
+  return Object.entries(
+    declaration as Record<string, CustomPartDeclaration | true>
+  ).map(([name, value]) => ({
+    name,
+    states:
+      value === true || !value?.states ? [] : Array.from(new Set(value.states))
+  }));
+};
+
+/** The reason a declared part name is refused, or null. */
+export const partNameError = (name: unknown): string | null => {
+  if (typeof name !== 'string' || !PART_NAME_PATTERN.test(name)) {
+    return (
+      `part name ${JSON.stringify(name)} could not survive into a CSS selector. ` +
+      `Use letters, digits, hyphens and underscores (max 64 characters) — sanitizePartName ` +
+      `strips everything else, so the part the catalog advertises and the part the stylesheet ` +
+      `matches would be different strings`
+    );
+  }
+
+  if (name.startsWith(FIELD_PART_PREFIX)) {
+    return (
+      `part name "${name}" uses the "${FIELD_PART_PREFIX}" prefix, which is reserved for the parts ` +
+      `ThemeEditable derives from a field key. Declaring one collides with the auto-derived part ` +
+      `for that field — today if the field exists, and the moment it is added if it does not. Rename it`
+    );
+  }
+
+  return null;
+};
+
+/** The reason a declared state is refused, or null. */
+export const partStateError = (state: unknown): string | null => {
+  if (typeof state === 'string' && PART_STYLE_STATES.includes(state)) {
+    return null;
+  }
+
+  return (
+    `state ${JSON.stringify(state)} has no selector behind it, so a control written into it ` +
+    `would emit CSS that can never match. Available: ${PART_STYLE_STATES.join(', ')}`
+  );
+};

package/src/custom/property-types.ts

@@ -0,0 +1,70 @@
+/**
+ * The control vocabulary a custom block may declare, mirroring the editor's
+ * `PropertyType` union (`pz-dynamic-widget/src/config/base-config.ts:3-20`).
+ *
+ * Closed on purpose, and closed in the same way every comparable product
+ * closes it (Shopify 31, Webflow 9, Puck 11): a brand cannot introduce a
+ * control type, because the form is rendered by an editor bundle the brand
+ * does not ship and cannot extend. Two of the editor's members are absent
+ * here rather than merely unsupported:
+ *
+ * - `custom` needs a `customRender` FUNCTION, which cannot cross postMessage.
+ * - `group` is a container the panel derives, not a leaf a block declares.
+ */
+export const CUSTOM_PROPERTY_TYPES = [
+  'text',
+  'toggle',
+  'select',
+  'multiselect',
+  'slider',
+  'url',
+  'color',
+  'image',
+  'file',
+  'richtext',
+  'localetext',
+  'typography',
+  'icon'
+] as const;
+
+export type PropertyType = (typeof CUSTOM_PROPERTY_TYPES)[number];
+
+/**
+ * The subset whose value provably survives the full round trip — panel write,
+ * persistence, and resolution back into a prop.
+ *
+ * The three excluded members are excluded for reasons that were verified, not
+ * guessed:
+ *
+ * - `multiselect` and `localetext` are stored UNBUCKETED by the editor
+ *   (`theme-basic-properties.tsx:1547-1548` passes arrays and locale objects
+ *   through without the per-breakpoint wrapper). `getResponsiveValue` then
+ *   rejects an array with a devWarn and returns the fallback, and a locale
+ *   object has no `desktop` key so it does too. They can never deliver a
+ *   value until a per-type resolver exists.
+ * - `richtext` has no safe renderer here. The allowlist sanitizer this repo
+ *   already owns parses by assigning to `innerHTML` on a live element, so the
+ *   sink is its first act — and pz-theme renders server-side, where there is
+ *   no `document` at all.
+ *
+ * Declaring one of these throws at define time rather than shipping a control
+ * that silently shows the default forever.
+ */
+export const SUPPORTED_PROPERTY_TYPES: readonly PropertyType[] = [
+  'text',
+  'toggle',
+  'select',
+  'slider',
+  'url',
+  'color',
+  'image',
+  'file',
+  'typography',
+  'icon'
+];
+
+export const isSupportedPropertyType = (
+  type: unknown
+): type is PropertyType =>
+  typeof type === 'string' &&
+  (SUPPORTED_PROPERTY_TYPES as readonly string[]).includes(type);