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

package/src/custom/theme-editable.tsx

@@ -0,0 +1,342 @@
+'use client';
+
+import React from 'react';
+
+import { getResponsiveValue } from '../utils';
+import { devWarn } from '../utils/dev-warn';
+import { partAttrs } from '../utils/part-styles';
+import { useCustomBlockContext } from './block-context';
+import type { CustomBlockContextValue } from './block-context';
+import type { PropertyType } from './property-types';
+import {
+  EDITABLE_KIND_PROPERTY_TYPES,
+  EDITABLE_KIND_TARGET,
+  fieldPartName,
+  hrefKeyFor,
+  inferEditableKind,
+  isEditableKind,
+  type EditableKind
+} from './editable-tags';
+import {
+  RESERVED_SETTING_KEYS,
+  SETTING_KEY_PATTERN,
+  materializeDefault
+} from './types';
+
+/**
+ * Reports one field to the runtime collection sink.
+ *
+ * `defaultValue` crosses `postMessage` to the editor, so only a primitive can
+ * be reported — the authored default of `<h2>New <b>season</b></h2>` is a React
+ * element tree, which is unserializable AND meaningless to a text input.
+ * Omitting it there is deliberate: the element still renders its own markup as
+ * the fallback, so the storefront looks right; only the panel's "reset to
+ * default" has nothing to offer.
+ */
+const reportField = (
+  collect: CustomBlockContextValue['collect'],
+  field: {
+    key: string;
+    type: PropertyType;
+    label: string;
+    authoredDefault: unknown;
+    /**
+     * Whether an element on screen will actually carry `field-<key>`. False for
+     * the href half of a link: one `ThemeEditable` clones ONE element, and that
+     * element already carries the label half's part.
+     */
+    hasPart: boolean;
+  }
+): void => {
+  if (!collect) return;
+
+  const serializable =
+    typeof field.authoredDefault === 'string' ||
+    typeof field.authoredDefault === 'number' ||
+    typeof field.authoredDefault === 'boolean'
+      ? field.authoredDefault
+      : undefined;
+
+  collect.setting({
+    key: field.key,
+    type: field.type,
+    label: field.label,
+    defaultValue: materializeDefault(serializable),
+    // `editable` is not decoration: the setting sink in `getCollectSink`
+    // (collect.ts) and `buildDescriptor` (register.ts) both turn it into a
+    // `field-<key>` entry in `descriptor.parts`, which is the list the editor
+    // offers as click targets and style scopes. Setting it for a key no
+    // element carries would advertise a part whose generated selector matches
+    // nothing — a control offered with nothing behind it, which is the exact
+    // failure the parts list exists to rule out.
+    ...(field.hasPart ? { editable: true } : {})
+  });
+};
+
+/**
+ * Unwraps the editor's image/file picker shape.
+ *
+ * That picker stores `{ url }` rather than a bare string (the same shape
+ * `pickImageSource` in blocks/image-block.tsx already unwraps), and `{ url }`
+ * has no `desktop` key — so feeding it straight to `getResponsiveValue` would
+ * return the fallback and the merchant's chosen image would never appear.
+ * Applied on both sides of the responsive read because either level can carry
+ * it: `{url}` when unbucketed, `{desktop: {url}}` when per-breakpoint.
+ */
+const unwrapUrlValue = (value: unknown): unknown => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
+
+  const url = (value as { url?: unknown }).url;
+  return typeof url === 'string' ? url : value;
+};
+
+const resolveFieldValue = (
+  raw: unknown,
+  carriesUrl: boolean,
+  authoredDefault: unknown,
+  breakpoint: string
+): unknown => {
+  const value = carriesUrl ? unwrapUrlValue(raw) : raw;
+  const resolved = getResponsiveValue(value, breakpoint, authoredDefault);
+
+  return carriesUrl ? unwrapUrlValue(resolved) : resolved;
+};
+
+/** `ctaLabel` -> `Cta Label`. A starting point the developer can override later. */
+const labelFromKey = (key: string): string => {
+  const spaced = key.replace(/([a-z0-9])([A-Z])/g, '$1 $2');
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+};
+
+export interface ThemeEditableProps {
+  /** Becomes the key in `block.properties` and the `field-<name>` part. */
+  name: string;
+  /** Overrides tag inference. The escape hatch for a container tag. */
+  type?: EditableKind;
+  children?: React.ReactNode;
+}
+
+/**
+ * Turns one element of a developer's JSX into a merchant-editable field.
+ *
+ * THE AUTHORED JSX IS THE DEFAULT. `<ThemeEditable name="headline"><h2>New
+ * season</h2></ThemeEditable>` declares a text field whose default is "New
+ * season" — read off the child, because there is nowhere else for a developer
+ * to state it and not needing a second declaration is the whole point of the
+ * design. The default is reported through the collect sink so it reaches the
+ * descriptor the editor renders its panel from.
+ *
+ * INJECTION IS A RE-RENDER, NEVER A DOM WRITE. The merchant value is resolved
+ * and `cloneElement`d onto the child, so React owns the result. This is the
+ * one thing the retired native widget got wrong: it patched `el.src` and
+ * `el.textContent` after mount, and React overwrote both on its next render —
+ * the value appeared, then vanished on the first unrelated state change.
+ *
+ * Clearing is per breakpoint, and that asymmetry is `getResponsiveValue`'s,
+ * not a local choice: a BARE `''` counts as unset and falls back to the
+ * authored JSX, while `{ desktop: '' }` resolves to the empty string and the
+ * field really is blank. The bucketed form is the only one the panel ever
+ * writes, so a merchant who clears the input gets an empty element rather than
+ * the developer's placeholder coming back — which is what clearing has to mean
+ * for it to be usable at all.
+ *
+ * Refusals are loud in development (a throw naming the wrapper) and inert in
+ * production (the child renders untouched plus a dev warning that never
+ * reaches a shopper). A mis-wrapped element must never blank a live
+ * storefront: the block around it may be the header.
+ */
+export function ThemeEditable({
+  name,
+  type,
+  children
+}: ThemeEditableProps): React.ReactElement {
+  const context = useCustomBlockContext();
+
+  // Untouched rather than empty, so a `<ThemeEditable>` copy-pasted into a
+  // plain component keeps rendering what the developer wrote while the warning
+  // tells them why nothing is editable.
+  if (!context) {
+    devWarn(
+      'ThemeEditable',
+      `"${name}" is outside a custom block, so it has no properties to read. ` +
+        `Wrap the component with defineCustomBlock() and render it through a ` +
+        `custom block type; the child renders unchanged in the meantime.`
+    );
+    return <>{children}</>;
+  }
+
+  // Dev throws so the developer sees the offending wrapper in the stack;
+  // production degrades to the authored markup, which is always a valid page.
+  const refuse = (reason: string): React.ReactElement => {
+    const message = `<ThemeEditable name="${name}"> ${reason}`;
+
+    if (process.env.NODE_ENV !== 'production') {
+      throw new Error(`[pz-theme] ${message}`);
+    }
+
+    devWarn('ThemeEditable', message);
+    return <>{children}</>;
+  };
+
+  if (!SETTING_KEY_PATTERN.test(name)) {
+    return refuse(
+      `has an unusable name. A field name must start with a lowercase letter ` +
+        `and contain only letters and digits (max 32) — it becomes both an ` +
+        `object key in block.properties and a data-part value.`
+    );
+  }
+
+  if (RESERVED_SETTING_KEYS.includes(name)) {
+    return refuse(
+      `uses "${name}", which the editor's property panel already treats ` +
+        `specially. The field would inherit behaviour it never asked for; ` +
+        `pick another name.`
+    );
+  }
+
+  if (type !== undefined && !isEditableKind(type)) {
+    return refuse(
+      `was given type="${String(type)}", which is not an editable kind. ` +
+        `Use text, image, link or file.`
+    );
+  }
+
+  const childArray = React.Children.toArray(children);
+
+  if (childArray.length === 0) {
+    return refuse(
+      `has no element child. It must wrap exactly one element — the element ` +
+        `is what carries the value and states the default.`
+    );
+  }
+
+  if (childArray.length > 1) {
+    return refuse(
+      `wraps ${childArray.length} children. It must wrap exactly one element; ` +
+        `cloning cannot know which of several should carry the value.`
+    );
+  }
+
+  const child = childArray[0];
+
+  if (!React.isValidElement(child)) {
+    return refuse(
+      `wraps a bare value rather than an element. Put the content in an ` +
+        `element (for example <p>…</p>) so there is a prop to write it to.`
+    );
+  }
+
+  // A component's props are its own contract — `src`/`children` may mean
+  // nothing to it, or something else entirely. Only a host element has props
+  // whose meaning is fixed by HTML.
+  if (typeof child.type !== 'string') {
+    return refuse(
+      `wraps a component rather than a host element. Cloning cannot know ` +
+        `which of its props carries the value; wrap the element inside the ` +
+        `component instead.`
+    );
+  }
+
+  const tag = child.type;
+  const kind = type ?? inferEditableKind(tag);
+
+  if (!kind) {
+    return refuse(
+      `wraps <${tag}>, which has no unambiguous place to put a value. Add an ` +
+        `explicit type (text, image, link or file), or wrap the specific ` +
+        `element that holds the content.`
+    );
+  }
+
+  const hrefKey = kind === 'link' ? hrefKeyFor(name) : null;
+
+  // The suffix pushes a long name past the 32-character cap, and the derived
+  // key has to satisfy the same pattern as the one the developer typed —
+  // otherwise the href silently has nowhere to be stored.
+  if (
+    hrefKey &&
+    (!SETTING_KEY_PATTERN.test(hrefKey) ||
+      RESERVED_SETTING_KEYS.includes(hrefKey))
+  ) {
+    return refuse(
+      `would need a companion key "${hrefKey}" for its destination, which is ` +
+        `not a usable field name. Shorten the name.`
+    );
+  }
+
+  const childProps = child.props as Record<string, unknown>;
+  const valueProp = EDITABLE_KIND_TARGET[kind];
+  const authoredValue = childProps[valueProp];
+  const authoredHref = hrefKey ? childProps.href : undefined;
+
+  // Theirs wins. A developer who wrote their own `data-part` did it to style
+  // the element, and those part names are already published in compositions —
+  // overwriting one would drop the styles the merchant already saved. Decided
+  // before the field is reported, because whether `field-<name>` ends up on the
+  // page is exactly what the report has to say.
+  const stampsFieldPart = typeof childProps['data-part'] !== 'string';
+
+  // Reported during render, not from an effect: the collection pass is a
+  // server render (see collect.ts), and effects never run there.
+  reportField(context.collect, {
+    key: name,
+    type: EDITABLE_KIND_PROPERTY_TYPES[kind],
+    label: labelFromKey(name),
+    authoredDefault: authoredValue,
+    hasPart: stampsFieldPart
+  });
+
+  if (hrefKey) {
+    // The destination rides on the same `<a>` as the label and has no element
+    // of its own, so it is a panel control, not a part.
+    reportField(context.collect, {
+      key: hrefKey,
+      type: 'url',
+      label: `${labelFromKey(name)} link`,
+      authoredDefault: authoredHref,
+      hasPart: false
+    });
+  }
+
+  const properties = (context.block.properties ?? {}) as Record<
+    string,
+    unknown
+  >;
+
+  const nextProps: Record<string, unknown> = {
+    [valueProp]: resolveFieldValue(
+      properties[name],
+      kind === 'image' || kind === 'file',
+      authoredValue,
+      context.currentBreakpoint
+    )
+  };
+
+  if (hrefKey) {
+    // A destination is a plain string in every control that writes one, so it
+    // never carries the picker's `{ url }` wrapper.
+    nextProps.href = resolveFieldValue(
+      properties[hrefKey],
+      false,
+      authoredHref,
+      context.currentBreakpoint
+    );
+  }
+
+  if (stampsFieldPart) {
+    // `use-designer-features.tsx` resolves the nearest `[data-part]` under the
+    // click and ships its value as `partName` on SELECT_BLOCK, so this one
+    // attribute is what makes clicking the element on canvas open its control.
+    // When the developer kept their own part the field is still edited from the
+    // property panel — it is only the click-to-focus shortcut, and the `parts`
+    // entry that would have advertised it, that are given up.
+    Object.assign(nextProps, partAttrs(fieldPartName(name)));
+  }
+
+  return React.cloneElement(
+    child as React.ReactElement<Record<string, unknown>>,
+    nextProps
+  );
+}
+
+export default ThemeEditable;

package/src/custom/theme-slot.tsx

@@ -0,0 +1,210 @@
+'use client';
+
+import React, { useEffect, useId } from 'react';
+import { DesignerPlaceholder } from '../blocks/product-block-utils';
+import { renderComposedChildren } from '../blocks/render-composed-children';
+import { devWarn } from '../utils/dev-warn';
+import { useCustomBlockContext } from './block-context';
+import type { CustomBlockContextValue } from './block-context';
+import {
+  resolveSlotChildren,
+  resolveUnnamedSlot,
+  slotNameError
+} from './slot-nodes';
+
+/**
+ * Which slot this instance opens, or why it cannot be told.
+ *
+ * A written name is taken at its word even when the block declared no slot of
+ * that name: a block that declares nothing at all is a supported shape, and its
+ * slots are discovered by rendering it.
+ */
+const resolveSlot = (
+  name: string | undefined,
+  declaredNames: readonly string[]
+): { name: string } | { error: string } => {
+  if (name === undefined) return resolveUnnamedSlot(declaredNames);
+
+  const nameError = slotNameError(name);
+
+  return nameError ? { error: nameError } : { name };
+};
+
+export interface ThemeSlotProps {
+  /** Shown on the empty band in the designer, e.g. "Promo content". */
+  label?: string;
+  /**
+   * Which declared slot this opens. Omit it on a block that opens a single
+   * region — that spelling is what every block written against the original
+   * single-slot API uses, and it keeps its meaning exactly.
+   */
+  name?: string;
+}
+
+/**
+ * Which `ThemeSlot` instance owns each NAME in this block instance.
+ *
+ * Keyed by the context VALUE rather than the block id, which buys three things
+ * at once: the scope is one block instance in one render pass, two concurrent
+ * server renders of the same block id cannot see each other's claim, and the
+ * entry is collected with the context object instead of leaking — server
+ * renders never run the cleanup effect below.
+ *
+ * The claim is still needed now that slots are nodes, and it means something
+ * sharper than it did: two `<ThemeSlot name="promo" />` in one component are a
+ * REAL duplicate, both resolving to the same slot node. Rendering both would
+ * put that node's children on screen twice, and two `data-block-id` wrappers
+ * answering to one id break selection in the editor.
+ */
+const slotOwners = new WeakMap<CustomBlockContextValue, Map<string, string>>();
+
+const claimSlot = (
+  context: CustomBlockContextValue,
+  name: string,
+  instanceId: string
+): boolean => {
+  const claims = slotOwners.get(context) ?? new Map<string, string>();
+  slotOwners.set(context, claims);
+
+  const owner = claims.get(name);
+  if (owner === undefined) {
+    claims.set(name, instanceId);
+    return true;
+  }
+
+  return owner === instanceId;
+};
+
+const releaseSlot = (
+  context: CustomBlockContextValue,
+  name: string,
+  instanceId: string
+): void => {
+  const claims = slotOwners.get(context);
+  if (claims?.get(name) === instanceId) claims.delete(name);
+};
+
+/**
+ * A merchant-fillable hole in a custom block: everything a merchant drops
+ * inside it renders here, through the same child pipeline every built-in
+ * container uses.
+ *
+ * ONE NODE PER SLOT. A declared slot materializes as a reserved-type child of
+ * the custom block and this renders THAT node's children, so a block can open
+ * several regions and each is filled independently — the editor addresses an
+ * insertion as `(placeholderId, sectionId, parentBlockId, index)`, and a slot
+ * that is a node is simply the parent.
+ *
+ * A SLOT WITH NO NODE IS NOT AN ERROR. Nothing creates the nodes until the
+ * merchant opens the region, and every composition saved before slots were
+ * nodes has none at all. Both cases draw the empty band in the designer and
+ * render nothing on the live site; `resolveSlotChildren` is what keeps the
+ * older shape rendering.
+ *
+ * EMPTY BEHAVES DIFFERENTLY PER SIDE. The designer draws a dashed band so the
+ * hole is visible and droppable; the live storefront renders nothing at all.
+ * That distinction is the whole point of the split — the empty branch of
+ * `GroupBlock` (blocks/group-block.tsx) still ships the literal string
+ * "Empty group block" to shoppers, which is exactly the outcome this must
+ * not repeat.
+ */
+export function ThemeSlot({ label, name }: ThemeSlotProps) {
+  const context = useCustomBlockContext();
+  // Stable for the life of the instance and distinct between two instances,
+  // which is what separates "the same slot re-rendering" from "a second slot
+  // claiming the same name".
+  const instanceId = useId();
+
+  const resolved = resolveSlot(name, context?.declaredSlotNames ?? []);
+  const slotName = 'name' in resolved ? resolved.name : null;
+  const ownsSlot =
+    context && slotName !== null
+      ? claimSlot(context, slotName, instanceId)
+      : false;
+
+  useEffect(() => {
+    if (!context || slotName === null || !ownsSlot) return;
+
+    // Hand the claim back on unmount so a slot behind a condition
+    // (`{isWide && <ThemeSlot name="aside" />}`) does not lock the block out of
+    // that name for the rest of the page's life.
+    return () => releaseSlot(context, slotName, instanceId);
+  }, [context, slotName, ownsSlot, instanceId]);
+
+  if (!context) {
+    devWarn(
+      'ThemeSlot',
+      'A ThemeSlot rendered outside a custom block, so there is no composition ' +
+        'to read children from and nothing is rendered. Render this component ' +
+        'through a block registered with registerCustomBlocks().'
+    );
+    return null;
+  }
+
+  const { block, isDesigner } = context;
+
+  if (slotName === null) {
+    const reason = (resolved as { error: string }).error;
+
+    devWarn(
+      'ThemeSlot',
+      `The custom block "${block.type}" renders a slot that cannot be resolved: ${reason}.`
+    );
+
+    return isDesigner ? (
+      <DesignerPlaceholder label={`Unresolved slot — ${reason}`} />
+    ) : null;
+  }
+
+  if (!ownsSlot) {
+    const named = slotName === '' ? 'an unnamed slot' : `the slot "${slotName}"`;
+
+    devWarn(
+      'ThemeSlot',
+      `The custom block "${block.type}" declares more than one ThemeSlot for ${named}. ` +
+        'Both resolve to the same slot node, so its children would render twice and two ' +
+        'wrappers would answer to one block id; the extra slot renders nothing. Give each ' +
+        'ThemeSlot its own name.'
+    );
+
+    return isDesigner ? (
+      <DesignerPlaceholder
+        label={`Duplicate slot — ${named} is already open in this block`}
+      />
+    ) : null;
+  }
+
+  // Reported during render, like the settings sink: the collection pass reads
+  // it synchronously and effects do not run on the server.
+  context.collect?.slot(
+    label === undefined ? { name: slotName } : { name: slotName, label }
+  );
+
+  const slotChildren = resolveSlotChildren(block, slotName);
+
+  const children = renderComposedChildren({
+    // Null is "this slot has no node yet", which renders exactly like an empty
+    // one — the merchant has simply never put anything here.
+    blocks: slotChildren ?? [],
+    placeholderId: context.placeholderId,
+    sectionId: context.sectionId,
+    isDesigner,
+    selectedBlockId: context.selectedBlockId,
+    currentBreakpoint: context.currentBreakpoint
+  });
+
+  // Empty is decided AFTER the pipeline, not from the array length: a slot
+  // holding only hidden children is empty on the storefront and full in the
+  // designer, and both sides have to draw what they actually rendered.
+  if (children.length === 0) {
+    return isDesigner ? (
+      <DesignerPlaceholder
+        label={`${label ?? (slotName || 'Slot')} — empty, add blocks from the editor`}
+      />
+    ) : null;
+  }
+
+  return <>{children}</>;
+}
+
+export default ThemeSlot;