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

package/src/custom/__tests__/define.test.tsx

@@ -0,0 +1,619 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+
+import blockRendererRegistry from '../../blocks/block-renderer-registry';
+import type { BlockRendererProps } from '../../blocks/block-renderer-registry';
+import { useCustomBlockContext } from '../block-context';
+import {
+  getCustomBlockDescriptor,
+  getCustomBlockTypes,
+  resetCustomCatalog
+} from '../catalog';
+import { resetCustomCollection } from '../collect';
+import { defineCustomBlock } from '../define';
+import { registerCustomBlocks } from '../register';
+import { ThemeSlot } from '../theme-slot';
+import { CUSTOM_LIMITS, isCustomThemeType } from '../types';
+
+/**
+ * The registry deliberately has no `unregister` — a build registers once and a
+ * storefront never takes a type back. A test file registers dozens of times
+ * into that same module state, so it reaches the private Map directly. The
+ * reach-in is also the only way to ENUMERATE the registry, which the
+ * offered-implies-renderable test below needs in both directions.
+ */
+const rendererMap = (): Map<string, unknown> =>
+  (blockRendererRegistry as unknown as { renderers: Map<string, unknown> })
+    .renderers;
+
+const registeredCustomTypes = (): string[] =>
+  Array.from(rendererMap().keys()).filter(isCustomThemeType);
+
+const clearCustomRenderers = (): void => {
+  const map = rendererMap();
+  registeredCustomTypes().forEach((type) => map.delete(type));
+};
+
+const Promo = () => <div>promo</div>;
+const BestSellers = () => <div>best sellers</div>;
+
+const props = (over: Partial<BlockRendererProps> = {}): BlockRendererProps => ({
+  block: {
+    id: 'b1',
+    type: 'custom:acme:promo-strip',
+    label: 'Promo',
+    properties: {},
+    styles: {},
+    order: 0,
+    hidden: false
+  },
+  placeholderId: 'header',
+  sectionId: 's1',
+  isDesigner: false,
+  ...over
+});
+
+const renderBlock = (type: string, over: Partial<BlockRendererProps> = {}) => {
+  const Renderer = blockRendererRegistry.getRenderer(type);
+  if (!Renderer) throw new Error(`No renderer registered for ${type}`);
+
+  return render(<Renderer {...props(over)} />);
+};
+
+beforeEach(() => {
+  resetCustomCatalog();
+  resetCustomCollection();
+  clearCustomRenderers();
+});
+
+describe('registerCustomBlocks — the offered-implies-renderable invariant', () => {
+  it('puts every registered block in BOTH the registry and the catalog, and nothing else in either', () => {
+    registerCustomBlocks('acme', {
+      'promo-strip': defineCustomBlock(Promo, { label: 'Promo strip' }),
+      // A bare component: someone will forget the wrapper, and a block with no
+      // declared options is a complete block.
+      'best-sellers': BestSellers
+    });
+
+    const expected = new Set([
+      'custom:acme:promo-strip',
+      'custom:acme:best-sellers'
+    ]);
+
+    expect(new Set(getCustomBlockTypes())).toEqual(expected);
+    expect(new Set(registeredCustomTypes())).toEqual(expected);
+    // Both directions between the two stores: a type the editor is offered but
+    // the build cannot render (or the reverse) is the failure this locks.
+    expect(new Set(registeredCustomTypes())).toEqual(
+      new Set(getCustomBlockTypes())
+    );
+  });
+
+  it('renders the developer component through the registered host', () => {
+    registerCustomBlocks('acme', { 'promo-strip': Promo });
+
+    const { container } = renderBlock('custom:acme:promo-strip');
+
+    expect(container.textContent).toContain('promo');
+  });
+});
+
+describe('registerCustomBlocks — refusing to shadow', () => {
+  it('throws rather than overwriting a type something else already claimed', () => {
+    // Simulates the other barrel/build that got there first. `register` is a
+    // bare Map.set, so without the refusal this call would silently win.
+    blockRendererRegistry.register('custom:acme:promo-strip', () => null);
+
+    expect(() =>
+      registerCustomBlocks('acme', { 'promo-strip': Promo })
+    ).toThrow(/already registered/);
+  });
+
+  it('throws when a second call re-registers the same name', () => {
+    // A record written as an object literal cannot express the same name
+    // twice — the engine collapses duplicate keys before registration sees
+    // them — so this is the observable form of a duplicate claim. The in-call
+    // guard exists for the same collision arriving from a record that was not
+    // written as a literal, and keeps phase 1 complete so phase 2 cannot throw
+    // half way through a barrel.
+    registerCustomBlocks('acme', { 'promo-strip': Promo });
+
+    expect(() =>
+      registerCustomBlocks('acme', { 'promo-strip': BestSellers })
+    ).toThrow(/already registered/);
+  });
+});
+
+describe('registerCustomBlocks — naming', () => {
+  it('throws on a vendor that is not a valid segment', () => {
+    expect(() => registerCustomBlocks('Acme Inc', { promo: Promo })).toThrow(
+      /vendor "Acme Inc"/
+    );
+  });
+
+  it('throws on a block name that is not a valid segment', () => {
+    expect(() => registerCustomBlocks('acme', { Promo_Strip: Promo })).toThrow(
+      /"Promo_Strip"/
+    );
+  });
+});
+
+describe('registerCustomBlocks — setting validation', () => {
+  it('throws naming the reserved key', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, {
+          settings: [{ key: 'items', type: 'text' }]
+        })
+      })
+    ).toThrow(/"items" is reserved/);
+  });
+
+  it('throws naming an unsupported control type and why it cannot deliver a value', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, {
+          settings: [{ key: 'tags', type: 'multiselect' }]
+        })
+      })
+    ).toThrow(/"multiselect" cannot deliver a value/);
+  });
+
+  it('throws on a key the part grammar cannot carry', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, {
+          settings: [{ key: 'promo/tone', type: 'text' }]
+        })
+      })
+    ).toThrow(/not a valid setting key/);
+  });
+
+  it('materializes a scalar default into a per-breakpoint value', () => {
+    registerCustomBlocks('acme', {
+      'promo-strip': defineCustomBlock(Promo, {
+        settings: [
+          {
+            key: 'tone',
+            type: 'select',
+            label: 'Tone',
+            options: ['light', 'dark'],
+            defaultValue: 'light'
+          }
+        ]
+      })
+    });
+
+    const descriptor = getCustomBlockDescriptor('custom:acme:promo-strip');
+
+    expect(descriptor?.settings[0].defaultValue).toEqual({ desktop: 'light' });
+    // The shorthand option list is normalized into what the panel renders.
+    expect(descriptor?.settings[0].options).toEqual([
+      { label: 'light', value: 'light' },
+      { label: 'dark', value: 'dark' }
+    ]);
+  });
+});
+
+describe('registerCustomBlocks — declared slots', () => {
+  it('keeps every declared name, the unnamed one included', () => {
+    registerCustomBlocks('acme', {
+      'promo-strip': defineCustomBlock(Promo, {
+        slots: [
+          { label: 'Body' },
+          { name: 'promo', label: 'Promo content' },
+          { name: 'aside' }
+        ]
+      })
+    });
+
+    const descriptor = getCustomBlockDescriptor('custom:acme:promo-strip');
+
+    // The name is what `<ThemeSlot name>` matches against the slot node, so it
+    // has to survive registration verbatim — the empty string included.
+    expect(descriptor?.slots).toEqual([
+      { name: '', label: 'Body' },
+      { name: 'promo', label: 'Promo content' },
+      { name: 'aside' }
+    ]);
+    expect(descriptor?.hasChildren).toBe(true);
+  });
+
+  it('throws naming a slot declared twice', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, {
+          slots: [{ name: 'promo' }, { name: 'promo' }]
+        })
+      })
+    ).toThrow(/declares the slot "promo" twice/);
+  });
+
+  it('throws on two unnamed slots, which resolve to the same node', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, { slots: [{}, {}] })
+      })
+    ).toThrow(/two unnamed slots/);
+  });
+
+  it('throws on a name that could not be matched against a node', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, {
+          slots: [{ name: 'Promo Content' }]
+        })
+      })
+    ).toThrow(/"Promo Content" is not valid/);
+  });
+
+  /**
+   * `accepts` and `max` are the only descriptor values pz-theme carries and
+   * never reads, so nothing HERE would notice a bad one — but the editor
+   * refuses the whole catalog over it, and a refused catalog empties a brand's
+   * entire palette with the only diagnosis sitting in a repo the developer is
+   * not working in. These four are the shapes its validator rejects, refused
+   * where the message can name the block that wrote them.
+   */
+  it('throws on an accepts list no block could ever satisfy', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, {
+          slots: [{ name: 'promo', accepts: [] }]
+        })
+      })
+    ).toThrow(/empty accepts list/);
+  });
+
+  it('throws on an accepts entry that is not a block type', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, {
+          slots: [{ name: 'promo', accepts: ['image', ''] }]
+        })
+      })
+    ).toThrow(/malformed accepts list/);
+  });
+
+  it('throws on a max that is not a count of blocks', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, {
+          slots: [{ name: 'promo', max: 0 }]
+        })
+      })
+    ).toThrow(/max 0, which is not a positive whole number/);
+
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, {
+          slots: [{ name: 'promo', max: 1.5 }]
+        })
+      })
+    ).toThrow(/max 1.5, which is not a positive whole number/);
+  });
+
+  it('carries a well-formed accepts and max through untouched', () => {
+    registerCustomBlocks('acme', {
+      'promo-strip': defineCustomBlock(Promo, {
+        slots: [{ name: 'promo', accepts: ['image', 'text'], max: 2 }]
+      })
+    });
+
+    expect(getCustomBlockDescriptor('custom:acme:promo-strip')?.slots).toEqual([
+      { name: 'promo', accepts: ['image', 'text'], max: 2 }
+    ]);
+  });
+});
+
+describe('registerCustomBlocks — declared parts', () => {
+  it('joins the declared parts to the field-derived ones in one list', () => {
+    registerCustomBlocks('acme', {
+      'promo-strip': defineCustomBlock(Promo, {
+        settings: [
+          { key: 'headline', type: 'text', label: 'Headline', editable: true }
+        ],
+        parts: ['row', 'tile']
+      })
+    });
+
+    const descriptor = getCustomBlockDescriptor('custom:acme:promo-strip');
+
+    expect(descriptor?.parts).toEqual(['field-headline', 'row', 'tile']);
+    // Nothing declared a state, so nothing rides along.
+    expect(descriptor?.partStates).toBeUndefined();
+  });
+
+  it('carries the states of the record form and drops them for the rest', () => {
+    registerCustomBlocks('acme', {
+      'promo-strip': defineCustomBlock(Promo, {
+        parts: {
+          row: { states: ['hover', 'open'] },
+          tile: true,
+          badge: {}
+        }
+      })
+    });
+
+    const descriptor = getCustomBlockDescriptor('custom:acme:promo-strip');
+
+    expect(descriptor?.parts).toEqual(['row', 'tile', 'badge']);
+    expect(descriptor?.partStates).toEqual({ row: ['hover', 'open'] });
+    // The wire shape stays JSON, states and all.
+    expect(descriptor).toEqual(JSON.parse(JSON.stringify(descriptor)));
+  });
+
+  it('throws on a name that could not survive into a selector', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, { parts: ['menu row'] })
+      })
+    ).toThrow(/could not survive into a CSS selector/);
+  });
+
+  it('throws on a name that collides with an auto-derived field part', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, {
+          settings: [
+            { key: 'headline', type: 'text', label: 'Headline', editable: true }
+          ],
+          parts: ['field-headline']
+        })
+      })
+    ).toThrow(/reserved for the parts ThemeEditable derives/);
+  });
+
+  it('throws naming a part declared twice', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, { parts: ['row', 'row'] })
+      })
+    ).toThrow(/declares the part "row" twice/);
+  });
+
+  it('throws naming a state the renderer has no selector for', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, {
+          parts: { row: { states: ['hover', 'sparkling'] } }
+        })
+      })
+    ).toThrow(/"sparkling" has no selector behind it/);
+  });
+
+  it('names the states that ARE available when it refuses one', () => {
+    // A refusal a developer cannot act on is a refusal they work around by
+    // dropping the state entirely.
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, {
+          parts: { row: { states: ['sparkling'] } }
+        })
+      })
+    ).toThrow(/Available: .*\bhover\b.*\bopen\b/);
+  });
+});
+
+describe('registerCustomBlocks — descriptor serialization', () => {
+  it('survives its own JSON round trip unchanged', () => {
+    registerCustomBlocks('acme', {
+      'promo-strip': defineCustomBlock(Promo, {
+        label: 'Promo strip',
+        icon: 'star',
+        group: 'Marketing',
+        settings: [
+          {
+            key: 'headline',
+            type: 'text',
+            label: 'Headline',
+            defaultValue: 'New season',
+            editable: true
+          },
+          {
+            key: 'tone',
+            type: 'select',
+            label: 'Tone',
+            options: [{ label: 'Light', value: 'light' }],
+            showWhen: { key: 'headline', value: 'New season' }
+          }
+        ],
+        slots: [{ label: 'Content' }]
+      })
+    });
+
+    const descriptor = getCustomBlockDescriptor('custom:acme:promo-strip');
+
+    expect(descriptor).toEqual(JSON.parse(JSON.stringify(descriptor)));
+    expect(descriptor?.hasChildren).toBe(true);
+    // An editable setting is addressable as a part, so clicking the element on
+    // canvas lands on its control.
+    expect(descriptor?.parts).toEqual(['field-headline']);
+  });
+
+  it('throws naming the path of a value JSON would drop', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': defineCustomBlock(Promo, {
+          settings: [
+            {
+              key: 'tone',
+              type: 'select',
+              // A function cannot cross postMessage; without the mechanical
+              // catch the editor would receive this option with no value.
+              options: [{ label: 'Light', value: () => 'light' }]
+            }
+          ]
+        })
+      })
+    ).toThrow(/does not survive JSON/);
+  });
+});
+
+describe('registerCustomBlocks — atomicity', () => {
+  it('leaves the first entry unregistered in both stores when a later one is invalid', () => {
+    expect(() =>
+      registerCustomBlocks('acme', {
+        'promo-strip': Promo,
+        'best-sellers': defineCustomBlock(BestSellers, {
+          settings: [{ key: 'items', type: 'text' }]
+        })
+      })
+    ).toThrow(/"items" is reserved/);
+
+    // A half-registered barrel is worse than a rejected one: the picker would
+    // offer a block the build can render and hide one it cannot.
+    expect(getCustomBlockTypes()).toEqual([]);
+    expect(registeredCustomTypes()).toEqual([]);
+    expect(blockRendererRegistry.hasRenderer('custom:acme:promo-strip')).toBe(
+      false
+    );
+  });
+});
+
+describe('CustomBlockHost — a throwing developer component', () => {
+  const Broken = () => {
+    throw new Error('brand component blew up');
+  };
+
+  let consoleError: jest.SpyInstance;
+  let consoleWarn: jest.SpyInstance;
+
+  beforeEach(() => {
+    // React logs every caught render error itself, and devWarn logs ours.
+    consoleError = jest.spyOn(console, 'error').mockImplementation(() => {});
+    consoleWarn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleError.mockRestore();
+    consoleWarn.mockRestore();
+  });
+
+  it('renders nothing on the live site and does not rethrow', () => {
+    registerCustomBlocks('acme', { 'promo-strip': Broken });
+
+    const { container } = renderBlock('custom:acme:promo-strip', {
+      isDesigner: false
+    });
+
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('renders a labelled box in the designer', () => {
+    registerCustomBlocks('acme', {
+      'promo-strip': defineCustomBlock(Broken, { label: 'Promo strip' })
+    });
+
+    const { container } = renderBlock('custom:acme:promo-strip', {
+      isDesigner: true
+    });
+
+    expect(container.textContent).toContain('Promo strip');
+    expect(container.textContent).toContain('failed to render');
+  });
+});
+
+describe('CustomBlockHost — runtime collection of slots', () => {
+  const TwoSlots = () => (
+    <>
+      <ThemeSlot name="promo" label="Promo" />
+      <ThemeSlot name="aside" />
+    </>
+  );
+
+  it('records each name the component opened, and only once per name', () => {
+    registerCustomBlocks('acme', { 'mega-menu': TwoSlots });
+
+    renderBlock('custom:acme:mega-menu', {
+      block: { ...props().block, type: 'custom:acme:mega-menu' }
+    });
+    // A second placement of the same type must not append the names again.
+    renderBlock('custom:acme:mega-menu', {
+      block: { ...props().block, type: 'custom:acme:mega-menu' }
+    });
+
+    const descriptor = getCustomBlockDescriptor('custom:acme:mega-menu');
+
+    expect(descriptor?.slots).toEqual([
+      { name: 'promo', label: 'Promo' },
+      { name: 'aside' }
+    ]);
+    // Opening any slot at all is what makes the block droppable.
+    expect(descriptor?.hasChildren).toBe(true);
+  });
+});
+
+describe('CustomBlockHost — runtime collection', () => {
+  const Collecting = () => {
+    const context = useCustomBlockContext();
+    context?.collect?.setting({
+      key: 'tone',
+      type: 'select',
+      label: 'Tone',
+      defaultValue: 'light'
+    });
+
+    return <div>collecting</div>;
+  };
+
+  it('lets an undeclared setting reach the catalog, once', () => {
+    registerCustomBlocks('acme', { 'promo-strip': Collecting });
+
+    renderBlock('custom:acme:promo-strip');
+    // A second placement of the same type must not append the key again.
+    renderBlock('custom:acme:promo-strip');
+
+    const descriptor = getCustomBlockDescriptor('custom:acme:promo-strip');
+
+    expect(descriptor?.settings).toHaveLength(1);
+    expect(descriptor?.settings[0]).toMatchObject({
+      key: 'tone',
+      type: 'select',
+      defaultValue: { desktop: 'light' }
+    });
+  });
+
+  it('drops one field part rather than pushing the catalog over the parts cap', () => {
+    const CollectingEditable = () => {
+      const context = useCustomBlockContext();
+      context?.collect?.setting({
+        key: 'tagline',
+        type: 'text',
+        label: 'Tagline',
+        editable: true
+      });
+
+      return <div>collecting</div>;
+    };
+
+    // The one place a descriptor can grow past the cap AFTER registration
+    // checked it: `buildDescriptor` counts the declared parts and the declared
+    // fields together, and an undeclared `ThemeEditable` discovered at render
+    // time adds one more. The cap belongs to the EDITOR, which drops the whole
+    // catalog above it — so a brand would lose every block in its palette over
+    // one field nobody declared.
+    const declared = Array.from(
+      { length: CUSTOM_LIMITS.partsPerType },
+      (_, index) => `row${index}`
+    );
+
+    registerCustomBlocks('acme', {
+      'promo-strip': defineCustomBlock(CollectingEditable, {
+        parts: declared
+      })
+    });
+
+    renderBlock('custom:acme:promo-strip');
+
+    const descriptor = getCustomBlockDescriptor('custom:acme:promo-strip');
+
+    // The setting still arrives, so the field keeps its control in the Content
+    // tab; only its styling group is lost.
+    expect(descriptor?.settings.map((setting) => setting.key)).toEqual([
+      'tagline'
+    ]);
+    expect(descriptor?.parts).toEqual(declared);
+    expect(descriptor?.parts).not.toContain('field-tagline');
+  });
+});