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

package/src/custom/types.ts

@@ -0,0 +1,251 @@
+import type { PropertyType } from './property-types';
+
+export type { PropertyType };
+
+/** Prefix every developer-authored type carries. Permanent once published. */
+export const CUSTOM_TYPE_PREFIX = 'custom:';
+
+/**
+ * `custom:<vendor>:<name>`. Both segments are lowercase and hyphen-separated.
+ *
+ * Two properties this buys, and both are load-bearing:
+ * - It can never collide with a built-in type. Neither closed enum contains a
+ *   colon, so `custom:acme:hero` and a future built-in `hero` cannot meet.
+ * - It is greppable, and `isCustomThemeType` below is the one spelling of it.
+ *   Most of the code that has to treat a developer-authored type differently
+ *   lives in the editor and the generator rather than here, so this export is
+ *   the shape those repos mirror: a mirror can be diffed against this grammar
+ *   instead of being re-derived slightly wrong.
+ */
+export const CUSTOM_TYPE_PATTERN =
+  /^custom:[a-z0-9][a-z0-9-]{0,47}:[a-z0-9][a-z0-9-]{0,47}$/;
+
+export const isCustomThemeType = (type: unknown): type is string =>
+  typeof type === 'string' && CUSTOM_TYPE_PATTERN.test(type);
+
+/** Vendor and block-name segments, validated separately for better errors. */
+export const CUSTOM_SEGMENT_PATTERN = /^[a-z0-9][a-z0-9-]{0,47}$/;
+
+/**
+ * A `ThemeEditable`/`useThemeSetting` key. Deliberately narrower than the type
+ * segments: it becomes an object key in `block.properties` AND is interpolated
+ * into a `data-part` value as `field-<key>`, so it excludes everything the part
+ * grammar reserves — `/` is the part-key delimiter and a leading `:` marks a
+ * root state.
+ */
+export const SETTING_KEY_PATTERN = /^[a-z][a-zA-Z0-9]{0,31}$/;
+
+/**
+ * A `data-part` value as `sanitizePartName` (utils/part-styles.ts) leaves it —
+ * that function keeps `[A-Za-z0-9_-]` and silently drops everything else.
+ *
+ * A declared part outside this grammar would be advertised in the catalog under
+ * one spelling and matched in CSS under another, so the control the editor drew
+ * for it would write styles no element on the page answers to. It also excludes
+ * both characters the style-key grammar reserves — `/` is the part-key
+ * delimiter and a leading `:` marks a root state — so a part name can never be
+ * mistaken for a key.
+ */
+export const PART_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+/**
+ * The reserved block type one declared slot materializes as.
+ *
+ * A slot IS a child node rather than a name resolved against the block's one
+ * `block.blocks` array, and that is what makes several slots possible at all:
+ * insertion is already addressed as `(placeholderId, sectionId, parentBlockId,
+ * index)`, so a slot that is a node is filled by the machinery that exists —
+ * the slot node's id is simply the parent id. Three declared slots are three
+ * child nodes and three tree rows the merchant fills independently.
+ *
+ * Deliberately NOT under the `custom:<vendor>:<name>` grammar. That prefix
+ * means "a type this brand's build renders", and a slot node is rendered by
+ * nobody: `ThemeSlot` reaches past it to its children and the node itself puts
+ * no element on the page. One reserved type also means the editor recognises a
+ * slot without consulting a brand's catalog.
+ */
+export const CUSTOM_SLOT_BLOCK_TYPE = 'custom-slot';
+
+/**
+ * The property carrying a slot node's name.
+ *
+ * `block.properties` and not `block.label`, because the label is the one field
+ * a merchant can rename from the layer tree (`RENAME_BLOCK`) — a rename would
+ * detach the node from the `<ThemeSlot name="…">` that reads it, and nothing
+ * would say why the region went empty. Properties survive a save verbatim: the
+ * editor's `buildBlockSchemaForHierarchy` copies the whole object into the
+ * widget schema and `reconstructBlock` reads it straight back, key for key.
+ */
+export const SLOT_NAME_PROPERTY = 'slotName';
+
+/**
+ * A slot name. Narrower than a part name, wider than a setting key.
+ *
+ * It is never interpolated into a selector, so the part grammar's restrictions
+ * do not apply; what it must do is match LITERALLY between the component's
+ * `<ThemeSlot name="…">` and the node the editor created, across a JSON round
+ * trip. Excluding whitespace and case-collapsing surprises is the whole job.
+ */
+export const SLOT_NAME_PATTERN = /^[a-z][a-zA-Z0-9-]{0,31}$/;
+
+/**
+ * Keys the editor's generic property panel already treats specially. A custom
+ * block naming a field one of these would silently inherit behaviour it never
+ * asked for — `items` is rerouted to a bespoke slider editor, `background-image`
+ * is `url()`-wrapped, `font-family` becomes a Google Font picker, and `htmlId`
+ * and `tag` are pulled out of the Content tab entirely.
+ *
+ * This list is duplicated from the editor on purpose and is the WRONG kind of
+ * copy — it is the fourth mirror of a contract in this system. It exists so the
+ * refusal works today; the derivation script that makes it self-maintaining is
+ * its own ticket, and until that lands this list is a known drift risk.
+ */
+export const RESERVED_SETTING_KEYS: readonly string[] = [
+  'items',
+  'backgroundImage',
+  'background-image',
+  'fontFamily',
+  'font-family',
+  'htmlId',
+  'tag',
+  'customCss',
+  'publish-window',
+  'typographyVariant',
+  'role'
+];
+
+/**
+ * Caps. Enforced at the sender; re-enforced on arrival in the editor, whose
+ * `CUSTOM_LIMITS` carries the same four numbers.
+ *
+ * Every one is a literal rather than derived from another, because each is
+ * mirrored INDEPENDENTLY on the far side: an expression here would let a change
+ * to one cap move a second one on the sender alone, and the receiver's answer
+ * to a catalog over any cap is to drop all of it.
+ */
+export const CUSTOM_LIMITS = {
+  typesPerBuild: 40,
+  settingsPerType: 24,
+  slotsPerType: 8,
+  /**
+   * Every part the catalog advertises — the field-derived ones and the
+   * developer-declared ones together.
+   *
+   * A LITERAL, matching the editor's `CUSTOM_LIMITS.partsPerType`, and not
+   * `settingsPerType + slotsPerType` even though 32 is what that arithmetic
+   * happens to produce. That sum was the real bound only while `field-<key>`
+   * was the one way a part came into existence; a developer now declares parts
+   * directly, so the two numbers describe different things and only look
+   * related. Left derived, raising the settings cap would silently raise this
+   * one on the SENDER while the receiver's stayed at 32 — and the receiver
+   * drops the WHOLE catalog over the cap, so a build would lose every block in
+   * its palette because an unrelated limit moved.
+   */
+  partsPerType: 32,
+  catalogBytes: 256 * 1024
+} as const;
+
+/**
+ * The serializable half of a custom block — everything the editor needs and
+ * nothing it cannot receive. Functions are structurally impossible here: the
+ * editor has no `eval`/`new Function`, and `postMessage` throws on a function
+ * anyway, so `condition`/`customRender` can never cross.
+ */
+export interface CustomSettingDescriptor {
+  key: string;
+  type: PropertyType;
+  label: string;
+  /** Always per-breakpoint. See `materializeDefault`. */
+  defaultValue?: unknown;
+  options?: Array<{ label: string; value: unknown }>;
+  min?: number;
+  max?: number;
+  step?: number;
+  unit?: string;
+  maxLength?: number;
+  helpText?: string;
+  group?: string;
+  showWhen?: { key: string; value: unknown };
+  /**
+   * Set when the setting came from a `ThemeEditable`, which makes it a content
+   * field rather than a behaviour knob. The editor uses it to offer the control
+   * on the `field-<key>` part as well as in the Content tab, so clicking the
+   * element on canvas lands on the right control.
+   */
+  editable?: boolean;
+}
+
+export interface CustomSlotDescriptor {
+  /**
+   * The name of the slot NODE this slot renders, matched literally. The empty
+   * string is the unnamed slot, which is what every block written against the
+   * single-slot API declares and what a legacy composition's children resolve
+   * to — see `resolveSlotChildren` in `slot-nodes.ts`.
+   */
+  name: string;
+  label?: string;
+  accepts?: string[];
+  max?: number;
+}
+
+export interface CustomBlockDescriptor {
+  type: string;
+  name: string;
+  label: string;
+  icon?: string;
+  group?: string;
+  hasChildren: boolean;
+  settings: CustomSettingDescriptor[];
+  slots: CustomSlotDescriptor[];
+  /**
+   * Every `data-part` the block advertises: the `field-<key>` parts derived
+   * from its `ThemeEditable` fields first, then the ones the developer declared
+   * through `defineCustomBlock({ parts })`.
+   *
+   * ONE FLAT LIST OF STRINGS, deliberately. The editor validates this field
+   * element by element and drops the whole catalog when an entry is not a
+   * string, so turning it into a list of objects to carry the states would make
+   * every block in the build vanish from the palette of any editor older than
+   * the change. The states ride alongside instead.
+   */
+  parts: string[];
+  /**
+   * Declared states per part, for the parts that declared any — `{ row:
+   * ['hover', 'open'] }`. Absent when no part declared a state, which is why it
+   * is optional rather than an empty object: an editor that has never heard of
+   * it ignores an unknown key, and a brand that declares no state sends nothing
+   * extra.
+   *
+   * Only states `buildPartSelectors` can actually match appear here
+   * (`PART_STYLE_STATES`); a state with no selector expression would produce a
+   * control writing CSS that can never apply.
+   */
+  partStates?: Record<string, string[]>;
+}
+
+export interface CustomCatalog {
+  vendor: string;
+  blocks: CustomBlockDescriptor[];
+}
+
+/**
+ * Per-breakpoint shape for every authored default.
+ *
+ * Not cosmetic. `handlePropertyChange` in the editor re-spreads an existing
+ * value only when it is ALREADY per-breakpoint; a bare scalar is replaced
+ * wholesale by `{tablet: v}` on the first non-desktop edit, after which
+ * `getResponsiveValue` finds no `desktop` key and falls back to the schema
+ * default — the merchant's desktop value is gone with no error. Materializing
+ * here means an authored default can never be that bare scalar.
+ *
+ * Values that are already objects (a per-breakpoint map the developer wrote
+ * themselves) and arrays (which are stored unbucketed) pass through untouched.
+ */
+export const materializeDefault = (value: unknown): unknown => {
+  if (value === undefined) return undefined;
+  if (value === null) return value;
+  if (Array.isArray(value)) return value;
+  if (typeof value === 'object') return value;
+
+  return { desktop: value };
+};

package/src/custom/use-theme-setting.ts

@@ -0,0 +1,225 @@
+'use client';
+
+import { getResponsiveValue } from '../utils';
+import { devWarn } from '../utils/dev-warn';
+import { useCustomBlockContext } from './block-context';
+import {
+  normalizeSettingChoices,
+  settingKeyError,
+  settingTypeError
+} from './collect';
+import type { ThemeSettingChoice } from './collect';
+import type { PropertyType } from './property-types';
+import { materializeDefault } from './types';
+import type { CustomSettingDescriptor } from './types';
+
+// Re-exported so a block file still reaches the option shorthand through the
+// module it writes its settings against. The declaration itself moved to
+// `collect.ts` with the normalizer that consumes it — see the note there.
+export type { ThemeSettingChoice };
+
+/**
+ * What each control type resolves to, so a call needs no type argument — the
+ * comparison in the documented example (`tone === 'dark'`) only typechecks
+ * because `select` maps to `string`.
+ *
+ * Total over `PropertyType`, including the three types that throw at runtime:
+ * the map is an index, not a permission.
+ */
+interface SettingValueByType {
+  text: string;
+  select: string;
+  url: string;
+  color: string;
+  icon: string;
+  image: string;
+  file: string;
+  richtext: string;
+  toggle: boolean;
+  slider: number;
+  typography: Record<string, unknown>;
+  multiselect: string[];
+  localetext: Record<string, string>;
+}
+
+/**
+ * Stands in for TypeScript 5.4's `NoInfer`. Brands consume this package as
+ * source and compile it with their own TypeScript, several of them older.
+ *
+ * Without it, `default: 'light'` makes the return type the literal `'light'`
+ * and `tone === 'dark'` becomes a compile error about non-overlapping types —
+ * the API would reject the exact snippet it documents.
+ */
+type NoInferred<T> = [T][T extends unknown ? 0 : never];
+
+export interface ThemeSettingOptions<
+  TType extends PropertyType = PropertyType,
+  TValue = unknown
+> {
+  type: TType;
+  label: string;
+  default?: NoInferred<TValue>;
+  options?: ReadonlyArray<ThemeSettingChoice>;
+  min?: number;
+  max?: number;
+  step?: number;
+  unit?: string;
+  maxLength?: number;
+  helpText?: string;
+  group?: string;
+  showWhen?: { key: string; value: unknown };
+  /**
+   * Marks the setting as a content field rather than a behaviour knob, so the
+   * editor also offers it on the `field-<key>` part. `ThemeEditable` sets it;
+   * a hand-written call has no on-screen element to attach a control to and
+   * should leave it alone.
+   */
+  editable?: boolean;
+}
+
+/**
+ * Throws rather than warns. A malformed key or an unreadable control type
+ * produces a panel control that shows its default forever and silently drops
+ * whatever the merchant types into it — a failure that surfaces weeks later as
+ * "the editor does not save". Production skips the check: by then the
+ * declaration is fixed at build time, and a storefront must not go down over a
+ * property panel.
+ *
+ * The rules come from `collect.ts` rather than being restated here. Both paths
+ * refuse the same key for the same reason, and a copy of the rule that drifted
+ * would be worse than no check at all — the hook would accept a key the
+ * collector then dropped, leaving a setting with no control and no error.
+ */
+const assertDeclarationIsValid = (
+  key: string,
+  options: ThemeSettingOptions<PropertyType, unknown>
+): void => {
+  if (process.env.NODE_ENV === 'production') return;
+
+  const reason = settingKeyError(key) ?? settingTypeError(options.type);
+  if (!reason) return;
+
+  throw new Error(`[pz-theme] useThemeSetting: ${reason}.`);
+};
+
+const buildDescriptor = (
+  key: string,
+  options: ThemeSettingOptions<PropertyType, unknown>
+): CustomSettingDescriptor => {
+  const descriptor: CustomSettingDescriptor = {
+    key,
+    type: options.type,
+    label: options.label
+  };
+
+  // Per-breakpoint from the start: a bare scalar default is replaced wholesale
+  // by the editor on the first non-desktop edit, taking the merchant's desktop
+  // value with it. See the note on `materializeDefault`.
+  if (options.default !== undefined) {
+    descriptor.defaultValue = materializeDefault(options.default);
+  }
+
+  const choices = normalizeSettingChoices(options.options);
+  if (choices) descriptor.options = choices;
+
+  if (options.min !== undefined) descriptor.min = options.min;
+  if (options.max !== undefined) descriptor.max = options.max;
+  if (options.step !== undefined) descriptor.step = options.step;
+  if (options.unit !== undefined) descriptor.unit = options.unit;
+  if (options.maxLength !== undefined) descriptor.maxLength = options.maxLength;
+  if (options.helpText !== undefined) descriptor.helpText = options.helpText;
+  if (options.group !== undefined) descriptor.group = options.group;
+  if (options.showWhen !== undefined) descriptor.showWhen = options.showWhen;
+  if (options.editable) descriptor.editable = true;
+
+  return descriptor;
+};
+
+/**
+ * Separates "no default was authored" from "the authored default is an empty
+ * string". `getResponsiveValue` defaults its own third parameter to `''`, so
+ * passing `undefined` for the fallback would silently become `''`.
+ */
+const NOT_AUTHORED = Symbol('pz-theme.notAuthored');
+
+const resolveAuthoredDefault = (
+  value: unknown,
+  breakpoint: string
+): unknown => {
+  const resolved = getResponsiveValue(value, breakpoint, NOT_AUTHORED);
+
+  // An object default is a per-breakpoint map by the convention
+  // `materializeDefault` sets — except for `typography`, whose natural default
+  // is a style object with no `desktop` key. Resolving that would yield
+  // nothing and the control would read as unset, so a default that resolves to
+  // nothing is handed back whole rather than dropped.
+  return resolved === NOT_AUTHORED ? value : resolved;
+};
+
+/**
+ * Declares one merchant-editable value that has no on-screen representation —
+ * how many products a grid shows, which category it pulls from, whether a
+ * slider auto-advances, which side the image sits on.
+ *
+ * Without it, every variation becomes its own entry in the add menu: one
+ * component shipped four times as "Promo strip (left)", "Promo strip (right)"
+ * and so on. `ThemeEditable` covers the other half — the values a merchant
+ * edits by clicking the thing itself.
+ *
+ * A HOOK rather than a prop, and that is the load-bearing part. React requires
+ * hooks to be called unconditionally, so the set of settings a component
+ * declares is identical on every render — which is what makes the declaration
+ * statically knowable and lets the whole property panel be built from a single
+ * render pass. A prop bag or a runtime `declare()` call could sit behind an
+ * `if`, and the panel would gain and lose controls as the merchant edited.
+ *
+ * The declaration IS the registration: there is no second schema file to keep
+ * in step, so a setting cannot drift from its use.
+ */
+export function useThemeSetting<
+  TType extends PropertyType,
+  TValue = SettingValueByType[TType]
+>(key: string, options: ThemeSettingOptions<TType, TValue>): TValue {
+  const context = useCustomBlockContext();
+  const declaration = options as ThemeSettingOptions<PropertyType, unknown>;
+
+  assertDeclarationIsValid(key, declaration);
+
+  if (!context) {
+    // Never throws: a developer previewing the component in a plain React tree,
+    // a storybook or a unit test should see the declared defaults, not a crash.
+    // The key rides in the message so distinct misplacements dedupe
+    // independently inside `devWarn`.
+    devWarn(
+      'useThemeSetting',
+      `"${key}" was read outside a custom block, so the merchant's value is ` +
+        `unreachable and the declared default is used instead. Render this ` +
+        `component through a block registered with registerCustomBlocks().`
+    );
+    return declaration.default as TValue;
+  }
+
+  // Reported on every render rather than once from an effect: the collection
+  // pass renders the component and reads the sink synchronously, and on the
+  // server effects never run at all.
+  context.collect?.setting(buildDescriptor(key, declaration));
+
+  const breakpoint = context.currentBreakpoint;
+
+  // `block.properties[key]`, never `block.value` — `value` is one slot per
+  // block, so the second setting would overwrite the first, and the backend
+  // drops attribute keys that were never declared.
+  const stored = context.block.properties?.[key];
+
+  // The sentinel again, for the same reason: handing `getResponsiveValue` an
+  // undefined fallback would resolve an undeclared default to `''`, so a
+  // `toggle` with no default would come back as an empty string rather than
+  // undefined.
+  const resolved = getResponsiveValue(stored, breakpoint, NOT_AUTHORED);
+
+  return (
+    resolved === NOT_AUTHORED
+      ? resolveAuthoredDefault(declaration.default, breakpoint)
+      : resolved
+  ) as TValue;
+}

package/src/index.ts

@@ -138,3 +138,69 @@ export { CheckoutPiecesProvider } from './chrome/checkout-pieces-provider';
 export { CheckoutPiece } from './chrome/checkout-piece';
 export { CHECKOUT_PIECE_KEYS } from './chrome/checkout-pieces';
 export type { CheckoutPieceKey } from './chrome/checkout-pieces';
+
+/**
+ * The custom block authoring API, named export by named export.
+ *
+ * Curated where the rest of this file is not, and where deep imports
+ * (`@akinon/pz-theme/src/custom`) are the de-facto norm everywhere else,
+ * because this is the only surface here consumed by code in ANOTHER REPO. A
+ * symbol that leaks out of `src/custom` becomes a compile dependency in a
+ * brand's block file the moment someone imports it, and removing it back out
+ * is then a breaking change in a repo this team does not own. Listing each
+ * export makes widening that surface a deliberate edit rather than the side
+ * effect of adding a file to the folder — which is exactly what `export *`
+ * would make it.
+ *
+ * `partAttrs` is deliberately absent: `export * from './utils'` above already
+ * publishes it at the root. The custom barrel re-exports it so a block file
+ * needs one import; adding it here too would be a second spelling of the same
+ * symbol from the same entry point.
+ *
+ * THIS ENTRY POINT IS SERVER-ONLY, which is why `registerCustomBlocks` cannot
+ * actually be used through it. `ThemePlaceholder` two dozen lines up imports
+ * `server-only`, and that poisons the whole module for a client graph — a
+ * brand's client root importing `registerCustomBlocks` from here gets "cannot
+ * be imported from a Client Component module" at build time. Registration is
+ * client-only (`custom/index.ts` explains why), so the barrel a brand writes
+ * imports from `@akinon/pz-theme/src/custom` instead. What these exports buy is
+ * discovery and the types, not a registration path.
+ */
+// The slot-node grammar (`CUSTOM_SLOT_BLOCK_TYPE`, `SLOT_NAME_PROPERTY`) and the
+// one spelling of the check (`isSlotNode`) are named here for the repos that
+// mirror the grammar rather than re-deriving it.
+export {
+  defineCustomBlock,
+  registerCustomBlocks,
+  ThemeEditable,
+  ThemeSlot,
+  useThemeSetting,
+  getCustomCatalog,
+  isCustomThemeType,
+  CUSTOM_TYPE_PREFIX,
+  CUSTOM_SLOT_BLOCK_TYPE,
+  SLOT_NAME_PROPERTY,
+  isSlotNode,
+  slotNodeName
+} from './custom';
+export type {
+  CustomBlockComponent,
+  CustomBlockDefinition,
+  CustomBlockDescriptor,
+  CustomBlockInput,
+  CustomBlockOptions,
+  CustomCatalog,
+  CustomPartDeclaration,
+  CustomPartsDeclaration,
+  CustomSettingDeclaration,
+  CustomSettingDescriptor,
+  CustomSettingOption,
+  CustomSlotDeclaration,
+  CustomSlotDescriptor,
+  EditableKind,
+  PropertyType,
+  ThemeEditableProps,
+  ThemeSettingChoice,
+  ThemeSettingOptions,
+  ThemeSlotProps
+} from './custom';