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

package/src/custom/__tests__/theme-slot.test.tsx

@@ -0,0 +1,387 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+
+// Stub the recursive ThemeBlock (default export) with a countable marker, the
+// same way group-block.test.tsx does — a slot is only honest if the children
+// it hands over are the ones that reach the renderer.
+jest.mock('../../theme-block', () => ({
+  __esModule: true,
+  default: ({ block }: { block: { id: string } }) => (
+    <div data-testid="tb" data-id={block.id} />
+  )
+}));
+
+import { CustomBlockContext } from '../block-context';
+import type { CustomBlockContextValue } from '../block-context';
+import { CUSTOM_SLOT_BLOCK_TYPE, SLOT_NAME_PROPERTY } from '../types';
+import type { CustomSlotDescriptor } from '../types';
+import type { Block } from '../../theme-block';
+import { ThemeSlot } from '../theme-slot';
+import { resetDevWarnCacheForTests } from '../../utils/dev-warn';
+
+const child = (id: string, hidden = false, order = 0): Block => ({
+  id,
+  type: 'text',
+  label: id,
+  value: '',
+  properties: {},
+  styles: {},
+  order,
+  hidden
+});
+
+/**
+ * A slot node exactly as the editor writes one: the reserved type, the name in
+ * `properties`, and the merchant blocks as its children.
+ */
+const slotNode = (name: string, blocks: Block[]): Block => ({
+  id: `slot-${name || 'unnamed'}`,
+  type: CUSTOM_SLOT_BLOCK_TYPE,
+  label: name || 'Slot',
+  properties: { [SLOT_NAME_PROPERTY]: name },
+  styles: {},
+  order: 0,
+  hidden: false,
+  blocks
+});
+
+const contextValue = ({
+  blocks,
+  isDesigner = false,
+  slotSink,
+  declaredSlotNames
+}: {
+  blocks?: Block[];
+  isDesigner?: boolean;
+  slotSink?: (descriptor: CustomSlotDescriptor) => void;
+  declaredSlotNames?: string[];
+} = {}): CustomBlockContextValue => ({
+  block: {
+    id: 'b1',
+    type: 'custom:acme:promo-strip',
+    label: 'Promo strip',
+    properties: {},
+    styles: {},
+    order: 0,
+    hidden: false,
+    blocks
+  },
+  placeholderId: 'p',
+  sectionId: 's',
+  isDesigner,
+  currentBreakpoint: 'desktop',
+  ...(declaredSlotNames ? { declaredSlotNames } : {}),
+  ...(slotSink ? { collect: { setting: jest.fn(), slot: slotSink } } : {})
+});
+
+const renderSlot = (
+  value: CustomBlockContextValue | null,
+  slot: React.ReactNode = <ThemeSlot />
+) =>
+  render(
+    value === null ? (
+      <>{slot}</>
+    ) : (
+      <CustomBlockContext.Provider value={value}>
+        {slot}
+      </CustomBlockContext.Provider>
+    )
+  );
+
+const markers = (container: HTMLElement) =>
+  Array.from(container.querySelectorAll('[data-testid="tb"]'));
+
+const bands = (container: HTMLElement) =>
+  Array.from(container.querySelectorAll('[data-theme-block-placeholder]'));
+
+beforeEach(() => {
+  resetDevWarnCacheForTests();
+});
+
+describe('ThemeSlot — children', () => {
+  it('renders the block children through ThemeBlock, in order', () => {
+    const { container } = renderSlot(
+      contextValue({ blocks: [child('a', false, 2), child('b', false, 0)] })
+    );
+
+    expect(markers(container).map((m) => m.getAttribute('data-id'))).toEqual([
+      'b',
+      'a'
+    ]);
+  });
+
+  it('drops hidden children on the live site and keeps them in the designer', () => {
+    const blocks = [child('visible'), child('concealed', true)];
+
+    const live = renderSlot(contextValue({ blocks }));
+    expect(markers(live.container)).toHaveLength(1);
+
+    const designer = renderSlot(contextValue({ blocks, isDesigner: true }));
+    expect(markers(designer.container)).toHaveLength(2);
+  });
+});
+
+describe('ThemeSlot — empty', () => {
+  it('draws a labelled band in the designer', () => {
+    const { container } = renderSlot(
+      contextValue({ blocks: [], isDesigner: true }),
+      <ThemeSlot label="Promo content" />
+    );
+
+    expect(bands(container)).toHaveLength(1);
+    expect(container.textContent).toContain('Promo content');
+  });
+
+  it('renders nothing at all on the live site', () => {
+    const { container } = renderSlot(contextValue({ blocks: [] }));
+
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('is empty on the live site when every child is hidden, band-only in the designer', () => {
+    const blocks = [child('concealed', true)];
+
+    const live = renderSlot(contextValue({ blocks }));
+    expect(live.container).toBeEmptyDOMElement();
+
+    const designer = renderSlot(contextValue({ blocks, isDesigner: true }));
+    expect(markers(designer.container)).toHaveLength(1);
+    expect(bands(designer.container)).toHaveLength(0);
+  });
+});
+
+describe('ThemeSlot — named slots', () => {
+  const nodes = [
+    slotNode('promo', [child('in-promo')]),
+    slotNode('aside', [child('in-aside')])
+  ];
+
+  it('renders the children of its own node and of no other slot', () => {
+    const { container } = renderSlot(
+      contextValue({ blocks: nodes }),
+      <ThemeSlot name="promo" />
+    );
+
+    expect(markers(container).map((m) => m.getAttribute('data-id'))).toEqual([
+      'in-promo'
+    ]);
+  });
+
+  it('fills every declared slot independently in one render', () => {
+    const { container } = renderSlot(
+      contextValue({ blocks: nodes, declaredSlotNames: ['promo', 'aside'] }),
+      <>
+        <ThemeSlot name="promo" />
+        <ThemeSlot name="aside" />
+      </>
+    );
+
+    expect(markers(container).map((m) => m.getAttribute('data-id'))).toEqual([
+      'in-promo',
+      'in-aside'
+    ]);
+  });
+
+  it('draws the band for a slot whose node does not exist yet, and nothing live', () => {
+    const designer = renderSlot(
+      contextValue({ blocks: nodes, isDesigner: true }),
+      <ThemeSlot name="footer" label="Footer content" />
+    );
+
+    expect(bands(designer.container)).toHaveLength(1);
+    expect(designer.container.textContent).toContain('Footer content');
+
+    const live = renderSlot(
+      contextValue({ blocks: nodes }),
+      <ThemeSlot name="footer" />
+    );
+
+    expect(live.container).toBeEmptyDOMElement();
+  });
+
+  it('refuses a name the editor could never have written', () => {
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    const { container } = renderSlot(
+      contextValue({ blocks: nodes }),
+      <ThemeSlot name="Promo Content" />
+    );
+
+    expect(container).toBeEmptyDOMElement();
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('"Promo Content" is not valid')
+    );
+
+    warn.mockRestore();
+  });
+});
+
+describe('ThemeSlot — a composition saved before slots were nodes', () => {
+  it('renders children that sit directly on the block', () => {
+    const { container } = renderSlot(
+      contextValue({ blocks: [child('legacy')] })
+    );
+
+    expect(markers(container).map((m) => m.getAttribute('data-id'))).toEqual([
+      'legacy'
+    ]);
+  });
+
+  it('never hands another slot node to the unnamed slot', () => {
+    // The half-migrated shape: one region already opened as a node, one child
+    // still sitting on the block. The unnamed slot owns the second and must
+    // not also render the first.
+    const { container } = renderSlot(
+      contextValue({
+        blocks: [slotNode('promo', [child('in-promo')]), child('loose')]
+      })
+    );
+
+    expect(markers(container).map((m) => m.getAttribute('data-id'))).toEqual([
+      'loose'
+    ]);
+  });
+});
+
+describe('ThemeSlot — a bare ThemeSlot', () => {
+  it('opens the single declared slot whatever it is called', () => {
+    const { container } = renderSlot(
+      contextValue({
+        blocks: [slotNode('promo', [child('in-promo')])],
+        declaredSlotNames: ['promo']
+      })
+    );
+
+    expect(markers(container).map((m) => m.getAttribute('data-id'))).toEqual([
+      'in-promo'
+    ]);
+  });
+
+  it('takes the unnamed slot when the block declares one beside named ones', () => {
+    const { container } = renderSlot(
+      contextValue({
+        blocks: [slotNode('', [child('in-unnamed')]), slotNode('promo', [])],
+        declaredSlotNames: ['', 'promo']
+      })
+    );
+
+    expect(markers(container).map((m) => m.getAttribute('data-id'))).toEqual([
+      'in-unnamed'
+    ]);
+  });
+
+  it('is refused when several named slots leave nothing to resolve', () => {
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    const { container } = renderSlot(
+      contextValue({
+        blocks: [slotNode('promo', [child('in-promo')])],
+        declaredSlotNames: ['promo', 'aside'],
+        isDesigner: true
+      })
+    );
+
+    // The message has to name the alternatives: the next edit a developer
+    // makes is typing one of them.
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('<ThemeSlot name="promo" />')
+    );
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('<ThemeSlot name="aside" />')
+    );
+    expect(bands(container)).toHaveLength(1);
+    expect(markers(container)).toHaveLength(0);
+  });
+});
+
+describe('ThemeSlot — the same slot opened twice in one component', () => {
+  it('renders the node children once, not twice', () => {
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    const { container } = renderSlot(
+      contextValue({ blocks: [slotNode('promo', [child('in-promo')])] }),
+      <>
+        <ThemeSlot name="promo" />
+        <ThemeSlot name="promo" />
+      </>
+    );
+
+    expect(markers(container)).toHaveLength(1);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('declares more than one ThemeSlot')
+    );
+
+    warn.mockRestore();
+  });
+
+  it('explains itself on the designer canvas rather than going blank', () => {
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    const { container } = renderSlot(
+      contextValue({ blocks: [child('only')], isDesigner: true }),
+      <>
+        <ThemeSlot />
+        <ThemeSlot />
+      </>
+    );
+
+    expect(bands(container)).toHaveLength(1);
+    expect(container.textContent).toContain('Duplicate slot');
+
+    warn.mockRestore();
+  });
+});
+
+describe('ThemeSlot — declaration reported to the sink', () => {
+  it('forwards every slot the component opens, with its label', () => {
+    const slotSink = jest.fn();
+
+    renderSlot(
+      contextValue({ blocks: [child('only')], slotSink }),
+      <>
+        <ThemeSlot name="body" label="Promo content" />
+        <ThemeSlot name="aside" />
+      </>
+    );
+
+    expect(slotSink).toHaveBeenCalledTimes(2);
+    expect(slotSink).toHaveBeenCalledWith({
+      name: 'body',
+      label: 'Promo content'
+    });
+    expect(slotSink).toHaveBeenCalledWith({ name: 'aside' });
+  });
+
+  it('reports the single unnamed slot as the empty name', () => {
+    const slotSink = jest.fn();
+
+    renderSlot(contextValue({ blocks: [child('only')], slotSink }));
+
+    expect(slotSink).toHaveBeenCalledWith({ name: '' });
+  });
+});
+
+describe('ThemeSlot — used outside a custom block', () => {
+  it('renders nothing and warns instead of crashing', () => {
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    const { container } = renderSlot(null);
+
+    expect(container).toBeEmptyDOMElement();
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('outside a custom block')
+    );
+
+    warn.mockRestore();
+  });
+});

package/src/custom/__tests__/use-theme-setting.test.tsx

@@ -0,0 +1,260 @@
+import React from 'react';
+import { renderHook } from '@testing-library/react';
+
+import { CustomBlockContext } from '../block-context';
+import type { CustomBlockContextValue } from '../block-context';
+import type { CustomSettingDescriptor } from '../types';
+import { useThemeSetting } from '../use-theme-setting';
+import { resetDevWarnCacheForTests } from '../../utils/dev-warn';
+
+type SettingSink = (descriptor: CustomSettingDescriptor) => void;
+
+const contextValue = ({
+  properties = {},
+  currentBreakpoint = 'desktop',
+  sink
+}: {
+  properties?: Record<string, unknown>;
+  currentBreakpoint?: string;
+  sink?: SettingSink;
+} = {}): CustomBlockContextValue => ({
+  block: {
+    id: 'b1',
+    type: 'custom:acme:promo-strip',
+    label: 'Promo strip',
+    properties,
+    styles: {},
+    order: 0,
+    hidden: false
+  },
+  placeholderId: 'p',
+  sectionId: 's',
+  isDesigner: false,
+  currentBreakpoint,
+  ...(sink ? { collect: { setting: sink, slot: jest.fn() } } : {})
+});
+
+const wrapperFor = (value: CustomBlockContextValue | null) => {
+  const Wrapper = ({ children }: { children: React.ReactNode }) =>
+    value === null ? (
+      <>{children}</>
+    ) : (
+      <CustomBlockContext.Provider value={value}>
+        {children}
+      </CustomBlockContext.Provider>
+    );
+
+  return Wrapper;
+};
+
+beforeEach(() => {
+  resetDevWarnCacheForTests();
+});
+
+describe('useThemeSetting — value resolution', () => {
+  it('reads the merchant value for the active breakpoint', () => {
+    const value = contextValue({
+      properties: { tone: { desktop: 'light', mobile: 'dark' } },
+      currentBreakpoint: 'mobile'
+    });
+
+    const { result } = renderHook(
+      () =>
+        useThemeSetting('tone', {
+          type: 'select',
+          label: 'Tone',
+          options: ['light', 'dark'],
+          default: 'light'
+        }),
+      { wrapper: wrapperFor(value) }
+    );
+
+    expect(result.current).toBe('dark');
+  });
+
+  it('falls back to the declared default when the merchant stored nothing', () => {
+    const { result } = renderHook(
+      () =>
+        useThemeSetting('tone', {
+          type: 'select',
+          label: 'Tone',
+          options: ['light', 'dark'],
+          default: 'light'
+        }),
+      { wrapper: wrapperFor(contextValue()) }
+    );
+
+    expect(result.current).toBe('light');
+  });
+
+  it('resolves a default that was itself authored per breakpoint', () => {
+    const { result } = renderHook(
+      () =>
+        useThemeSetting('columns', {
+          type: 'slider',
+          label: 'Columns',
+          default: { desktop: 4, mobile: 2 } as unknown as number
+        }),
+      { wrapper: wrapperFor(contextValue({ currentBreakpoint: 'mobile' })) }
+    );
+
+    expect(result.current).toBe(2);
+  });
+
+  it('returns undefined — not the empty string — when nothing is stored and no default was declared', () => {
+    const { result } = renderHook(
+      () => useThemeSetting('autoplay', { type: 'toggle', label: 'Autoplay' }),
+      { wrapper: wrapperFor(contextValue()) }
+    );
+
+    expect(result.current).toBeUndefined();
+  });
+
+  it('reads block.properties, never block.value', () => {
+    const value = contextValue();
+    value.block.value = 'from-value';
+
+    const { result } = renderHook(
+      () => useThemeSetting('heading', { type: 'text', label: 'Heading' }),
+      { wrapper: wrapperFor(value) }
+    );
+
+    expect(result.current).toBeUndefined();
+  });
+});
+
+describe('useThemeSetting — the declaration reported to the sink', () => {
+  const declareTone = (sink: SettingSink) =>
+    renderHook(
+      () =>
+        useThemeSetting('tone', {
+          type: 'select',
+          label: 'Tone',
+          options: ['light', 'dark'],
+          default: 'light'
+        }),
+      { wrapper: wrapperFor(contextValue({ sink })) }
+    );
+
+  it('normalizes the options shorthand into label/value pairs', () => {
+    const sink: SettingSink = jest.fn();
+    declareTone(sink);
+
+    expect(sink).toHaveBeenCalledWith(
+      expect.objectContaining({
+        key: 'tone',
+        type: 'select',
+        label: 'Tone',
+        options: [
+          { label: 'light', value: 'light' },
+          { label: 'dark', value: 'dark' }
+        ]
+      })
+    );
+  });
+
+  it('passes an already-normalized option list through untouched', () => {
+    const sink: SettingSink = jest.fn();
+    const pairs = [{ label: 'Two up', value: 2 }];
+
+    renderHook(
+      () =>
+        useThemeSetting('columns', {
+          type: 'select',
+          label: 'Columns',
+          options: pairs
+        }),
+      { wrapper: wrapperFor(contextValue({ sink })) }
+    );
+
+    expect(sink).toHaveBeenCalledWith(
+      expect.objectContaining({ options: pairs })
+    );
+  });
+
+  it('materializes a scalar default per breakpoint so the editor cannot drop it', () => {
+    const sink: SettingSink = jest.fn();
+    declareTone(sink);
+
+    expect(sink).toHaveBeenCalledWith(
+      expect.objectContaining({ defaultValue: { desktop: 'light' } })
+    );
+  });
+
+  it('omits optional fields that were never declared', () => {
+    const sink: SettingSink = jest.fn();
+
+    renderHook(
+      () => useThemeSetting('heading', { type: 'text', label: 'Heading' }),
+      { wrapper: wrapperFor(contextValue({ sink })) }
+    );
+
+    expect(sink).toHaveBeenCalledWith({
+      key: 'heading',
+      type: 'text',
+      label: 'Heading'
+    });
+  });
+});
+
+describe('useThemeSetting — used outside a custom block', () => {
+  it('returns the default and warns instead of crashing', () => {
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    const { result } = renderHook(
+      () =>
+        useThemeSetting('tone', {
+          type: 'select',
+          label: 'Tone',
+          options: ['light', 'dark'],
+          default: 'light'
+        }),
+      { wrapper: wrapperFor(null) }
+    );
+
+    expect(result.current).toBe('light');
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('was read outside a custom block')
+    );
+
+    warn.mockRestore();
+  });
+});
+
+describe('useThemeSetting — invalid declarations throw in development', () => {
+  const renderWith = (key: string, options: Record<string, unknown>) =>
+    renderHook(
+      () =>
+        useThemeSetting(
+          key,
+          options as unknown as Parameters<typeof useThemeSetting>[1]
+        ),
+      { wrapper: wrapperFor(contextValue()) }
+    );
+
+  it('rejects a key the part grammar cannot carry', () => {
+    expect(() =>
+      renderWith('Promo/Art', { type: 'text', label: 'Art' })
+    ).toThrow(/is not a valid setting key/);
+  });
+
+  it('rejects a key the editor panel already treats specially', () => {
+    expect(() => renderWith('items', { type: 'text', label: 'Items' })).toThrow(
+      /reserved/
+    );
+  });
+
+  it('rejects a control type whose value cannot be read back', () => {
+    expect(() =>
+      renderWith('tags', { type: 'multiselect', label: 'Tags' })
+    ).toThrow(/cannot deliver a value/);
+  });
+
+  it('rejects a type that is not a control at all', () => {
+    expect(() =>
+      renderWith('tone', { type: 'dropdown', label: 'Tone' })
+    ).toThrow(/not one of the editor's control types/);
+  });
+});

package/src/custom/block-context.ts

@@ -0,0 +1,64 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+import type { Block } from '../theme-block';
+import type {
+  CustomSettingDescriptor,
+  CustomSlotDescriptor
+} from './types';
+
+/**
+ * What `ThemeEditable`, `useThemeSetting` and `ThemeSlot` read.
+ *
+ * A context rather than props, because the whole point of the authoring model
+ * is that a developer writes ordinary JSX. Threading `block`/`breakpoint`
+ * through their own component tree to reach a `<ThemeEditable>` five levels
+ * down would be the tax this API exists to remove.
+ */
+export interface CustomBlockContextValue {
+  block: Block;
+  placeholderId: string;
+  sectionId: string;
+  isDesigner: boolean;
+  currentBreakpoint: string;
+  selectedBlockId?: string | null;
+  /**
+   * The slot names `defineCustomBlock` DECLARED, in declaration order, so a
+   * bare `<ThemeSlot />` can resolve to the block's single slot whatever it is
+   * called.
+   *
+   * From the definition and not from the catalog descriptor, which is the
+   * whole reason it is threaded here. The descriptor's `slots` array is
+   * APPENDED TO by runtime collection as each slot renders, so a component
+   * whose named slot renders before its bare one would see a one-entry list
+   * and resolve the bare slot onto the name the first one just claimed.
+   * The declaration never moves.
+   */
+  declaredSlotNames?: readonly string[];
+  /**
+   * Runtime collection sink. Present only while the block is rendering inside
+   * a host that is collecting — see `collect.ts`. The build-time extractor is
+   * the authoritative source of the descriptor; this is the fallback that
+   * makes the API work before the extractor exists, and the cross-check that
+   * catches a stale generated descriptor after it does.
+   */
+  collect?: {
+    setting: (descriptor: CustomSettingDescriptor) => void;
+    slot: (descriptor: CustomSlotDescriptor) => void;
+  };
+}
+
+export const CustomBlockContext =
+  createContext<CustomBlockContextValue | null>(null);
+
+/**
+ * Returns null outside a custom block rather than throwing.
+ *
+ * The three public components have to say something useful when a developer
+ * uses them in the wrong place — a plain React tree, a built-in block, a unit
+ * test. Each handles the null itself with a named message; a bare throw here
+ * would surface as a stack trace pointing at this file rather than at the
+ * `<ThemeEditable>` the developer actually mis-placed.
+ */
+export const useCustomBlockContext = (): CustomBlockContextValue | null =>
+  useContext(CustomBlockContext);