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

package/src/custom/__tests__/module-boundaries.test.ts

@@ -0,0 +1,156 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * The `'use client'` boundary inside `src/custom`, checked from source.
+ *
+ * Registration is client-only, but this folder is not. The directive-free
+ * modules here — `catalog.ts`, `types.ts`, `collect.ts`, `define.tsx`, the
+ * barrel — are reachable from the server graph and are actually read from it:
+ * `placeholder-registry.ts` calls `getCustomCatalog` without a directive of its
+ * own, and the server-only package root re-exports the barrel. React replaces
+ * each export of a `'use client'` module with a reference that throws
+ * "Attempted to call … from the server" the moment it is invoked, so one call
+ * from a directive-free module into a client one breaks whichever consumer is
+ * holding the server-side copy — and no jsdom test can see it, because jest has
+ * no RSC graph at all.
+ *
+ * What is refused is CALLING across the line, not importing across it: a client
+ * component referenced as an element type resolves fine from either graph. That
+ * is the distinction `bindHost` in `register.ts` leans on when it hands
+ * `CustomBlockHost` to `createElement` rather than calling it. The rule is also
+ * one-directional — a client module imports a plain one freely — and type-only
+ * imports are erased before the bundler sees them.
+ */
+const CUSTOM_DIR = path.resolve(__dirname, '..');
+
+const sourceFiles = (): string[] =>
+  fs
+    .readdirSync(CUSTOM_DIR)
+    .filter((entry) => /\.tsx?$/.test(entry))
+    .sort();
+
+const read = (file: string): string =>
+  fs.readFileSync(path.join(CUSTOM_DIR, file), 'utf8');
+
+const isClientModule = (file: string): boolean =>
+  /^['"]use client['"];/.test(read(file).trimStart());
+
+/** Sibling value imports as `{ bindings, specifier }`. Type imports erase. */
+const valueImports = (
+  source: string
+): Array<{ bindings: string[]; specifier: string }> =>
+  Array.from(
+    source.matchAll(/^import\s+(?!type\s)([^;]*?)\s+from\s+'(\.[^']*)';/gm)
+  )
+    .filter((match) => !match[2].startsWith('../'))
+    .map((match) => ({
+      specifier: match[2],
+      bindings: Array.from(match[1].matchAll(/[A-Za-z_$][\w$]*/g))
+        .map((binding) => binding[0])
+        .filter((name) => name !== 'type')
+    }));
+
+const resolved = (specifier: string): string | null =>
+  ['.ts', '.tsx']
+    .map((extension) => `${specifier.replace(/^\.\//, '')}${extension}`)
+    .find((candidate) => fs.existsSync(path.join(CUSTOM_DIR, candidate))) ??
+  null;
+
+/**
+ * Source with its comments removed.
+ *
+ * Every file here explains its boundary in prose, and the prose names the very
+ * symbols the scan looks for — an unstripped comment reports the rule's own
+ * documentation as a violation of it.
+ */
+const code = (source: string): string =>
+  source.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/\/\/[^\n]*/g, ' ');
+
+const isCalled = (source: string, name: string): boolean =>
+  new RegExp(String.raw`\b${name}\s*\(`).test(code(source));
+
+describe('src/custom module boundaries', () => {
+  it('has the client modules the render path needs and no more', () => {
+    // A directive here is not free — it decides which graph can call the file.
+    // Listing them makes adding one a deliberate edit.
+    expect(sourceFiles().filter(isClientModule)).toEqual([
+      'block-context.ts',
+      'block-host.tsx',
+      'register.ts',
+      'theme-editable.tsx',
+      'theme-slot.tsx',
+      'use-theme-setting.ts'
+    ]);
+  });
+
+  /**
+   * The renderer registry may only be reached from a client module.
+   *
+   * `blocks/block-renderer-registry.tsx` imports all ~99 block modules, and
+   * most of them call hooks without carrying a directive — they have never
+   * needed one, because the only path that reaches them is `theme-block.tsx`,
+   * which is a client module. Importing the registry from a directive-free
+   * module puts that whole tree into the importer's graph, and a brand barrel
+   * imported from a server layout then 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". `register.ts` carries
+   * `'use client'` for exactly this reason, and that is what makes registration
+   * client-only.
+   *
+   * This is precisely the case the first version of this file could not see:
+   * it filtered `../` specifiers out, and the offending import is
+   * `../blocks/block-renderer-registry`. It cost nothing in either suite —
+   * jest has no RSC graph, so 1741 tests stayed green over a defect that broke
+   * the first brand build attempted.
+   */
+  it('reaches the block renderer registry only from a client module', () => {
+    const withoutTypeImports = (source: string): string =>
+      code(source).replace(/import\s+type[^;]*;/g, ' ');
+
+    const offenders = sourceFiles()
+      .filter((file) => !isClientModule(file))
+      .filter((file) =>
+        /from\s+'\.\.\/blocks\/block-renderer-registry'/.test(
+          withoutTypeImports(read(file))
+        )
+      );
+
+    expect(offenders).toEqual([]);
+  });
+
+  it('never calls into a client module from a server-reachable one', () => {
+    const offences: string[] = [];
+
+    sourceFiles()
+      .filter((file) => !isClientModule(file))
+      .forEach((file) => {
+        const source = read(file);
+
+        valueImports(source).forEach(({ bindings, specifier }) => {
+          const target = resolved(specifier);
+          if (!target || !isClientModule(target)) return;
+
+          bindings
+            .filter((name) => isCalled(source, name))
+            .forEach((name) => {
+              offences.push(`${file} calls ${name}() from ${target}`);
+            });
+        });
+      });
+
+    expect(offences).toEqual([]);
+  });
+
+  it('keeps the barrel free of a directive of its own', () => {
+    // Still worth pinning under client-only registration, for the opposite
+    // reason to the one it was written for. The barrel publishes more than the
+    // client half: `getCustomCatalog`, `isCustomThemeType` and
+    // `CUSTOM_TYPE_PREFIX` all come from directive-free modules, and the
+    // server-only package root re-exports every one of them. A directive here
+    // would turn those into client references, so a server module calling
+    // `isCustomThemeType` from `@akinon/pz-theme` would throw. `register.ts`
+    // carries its own directive already, so the barrel would gain nothing.
+    expect(isClientModule('index.ts')).toBe(false);
+  });
+});

package/src/custom/__tests__/public-api.test.tsx

@@ -0,0 +1,427 @@
+import fs from 'fs';
+import path from 'path';
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+
+// The recursive renderer, stubbed with a countable marker so a slot's children
+// are assertable without every block renderer being dragged into the
+// assertion. Same stand-in `group-block.test.tsx` uses, and for the same
+// reason — `renderComposedChildren` is now shared by both.
+jest.mock('../../theme-block', () => ({
+  __esModule: true,
+  default: ({ block }: { block: { id: string } }) => (
+    <div data-testid="slot-child" data-id={block.id} />
+  )
+}));
+
+import blockRendererRegistry from '../../blocks/block-renderer-registry';
+import type { BlockRendererProps } from '../../blocks/block-renderer-registry';
+import { resetCustomCatalog } from '../catalog';
+import { resetCustomCollection } from '../collect';
+
+// Through the barrel, never the individual modules. That is the point of this
+// file: the three pieces each have their own suite, and every one of them
+// imports its subject directly, so a barrel that exported nothing at all would
+// still leave 86 green tests behind — while `@akinon/pz-theme/src/custom`, the
+// path a brand actually types, resolved to nothing.
+import {
+  CUSTOM_SLOT_BLOCK_TYPE,
+  CUSTOM_TYPE_PREFIX,
+  defineCustomBlock,
+  getCustomCatalog,
+  isCustomThemeType,
+  partAttrs,
+  registerCustomBlocks,
+  SLOT_NAME_PROPERTY,
+  ThemeEditable,
+  ThemeSlot,
+  useThemeSetting
+} from '../index';
+import * as customBarrel from '../index';
+
+const rendererMap = (): Map<string, unknown> =>
+  (blockRendererRegistry as unknown as { renderers: Map<string, unknown> })
+    .renderers;
+
+const clearCustomRenderers = (): void => {
+  const map = rendererMap();
+  Array.from(map.keys())
+    .filter(isCustomThemeType)
+    .forEach((type) => map.delete(type));
+};
+
+/** The ticket's own example, unaltered. If this stops compiling, the API broke. */
+function PromoStrip() {
+  const tone = useThemeSetting('tone', {
+    type: 'select',
+    label: 'Tone',
+    options: ['light', 'dark'],
+    default: 'light'
+  });
+
+  return (
+    <div
+      data-testid="promo"
+      className={tone === 'dark' ? 'bg-black' : 'bg-white'}
+      {...partAttrs('shell')}
+    >
+      <ThemeEditable name="art">
+        <img alt="Promo art" src="/default.jpg" />
+      </ThemeEditable>
+      <ThemeEditable name="headline">
+        <h2>New season</h2>
+      </ThemeEditable>
+      <ThemeSlot />
+    </div>
+  );
+}
+
+/** Registered without `defineCustomBlock`, which the barrel also has to accept. */
+const BestSellers = () => <div data-testid="best-sellers" />;
+
+/**
+ * The two ways a field ends up with no `field-<key>` element of its own: a
+ * link's destination rides on the one `<a>` its label already claimed, and a
+ * developer who wrote their own `data-part` keeps it.
+ */
+function LinkCard() {
+  return (
+    <div>
+      <ThemeEditable name="cta">
+        <a href="/sale">Shop now</a>
+      </ThemeEditable>
+      <ThemeEditable name="note">
+        <p data-part="footnote">Ends Friday</p>
+      </ThemeEditable>
+    </div>
+  );
+}
+
+/**
+ * The multi-slot shape end to end: three regions, one of them styled through a
+ * declared part. Written as a brand would write it, so the whole path is
+ * exercised — declaration, the slot names threaded through the host, and the
+ * slot nodes read back out of the composition.
+ */
+function MegaMenu() {
+  return (
+    <div>
+      <div {...partAttrs('row')}>
+        <ThemeSlot name="promo" label="Promo" />
+      </div>
+      <ThemeSlot name="links" label="Links" />
+      <ThemeSlot name="footer" label="Footer" />
+    </div>
+  );
+}
+
+const PROMO = 'custom:acme:promo-strip';
+const LINK_CARD = 'custom:acme:link-card';
+const MEGA_MENU = 'custom:acme:mega-menu';
+
+const slotNode = (name: string, childId: string) => ({
+  id: `slot-${name}`,
+  type: CUSTOM_SLOT_BLOCK_TYPE,
+  label: name,
+  properties: { [SLOT_NAME_PROPERTY]: name },
+  styles: {},
+  order: 0,
+  hidden: false,
+  blocks: [
+    {
+      id: childId,
+      type: 'text',
+      label: childId,
+      properties: {},
+      styles: {},
+      order: 0,
+      hidden: false
+    }
+  ]
+});
+
+const props = (over: Partial<BlockRendererProps> = {}): BlockRendererProps => ({
+  block: {
+    id: 'b1',
+    type: PROMO,
+    label: 'Promo',
+    properties: {},
+    styles: {},
+    order: 0,
+    hidden: false
+  },
+  placeholderId: 'header',
+  sectionId: 's1',
+  isDesigner: false,
+  ...over
+});
+
+const renderRegistered = (
+  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(() => {
+  registerCustomBlocks('acme', {
+    'promo-strip': defineCustomBlock(PromoStrip),
+    'best-sellers': BestSellers,
+    'link-card': LinkCard,
+    'mega-menu': defineCustomBlock(MegaMenu, {
+      label: 'Mega menu',
+      slots: [
+        { name: 'promo', label: 'Promo' },
+        { name: 'links', label: 'Links' },
+        { name: 'footer', label: 'Footer' }
+      ],
+      parts: { row: { states: ['hover', 'open'] } }
+    })
+  });
+});
+
+afterEach(() => {
+  clearCustomRenderers();
+  resetCustomCatalog();
+  resetCustomCollection();
+});
+
+describe('the documented barrel', () => {
+  it('registers both entries under the vendor from the call, not the component name', () => {
+    // Minification renames `PromoStrip` to a single letter; the record key is
+    // the only source that survives a production build.
+    expect(blockRendererRegistry.hasRenderer(PROMO)).toBe(true);
+    expect(blockRendererRegistry.hasRenderer('custom:acme:best-sellers')).toBe(
+      true
+    );
+    expect(PROMO.startsWith(CUSTOM_TYPE_PREFIX)).toBe(true);
+  });
+
+  it('renders the merchant value, the authored default and the slot in one pass', () => {
+    renderRegistered(PROMO, {
+      block: {
+        ...props().block,
+        properties: {
+          tone: { desktop: 'dark' },
+          headline: { desktop: 'Autumn' }
+        },
+        blocks: [
+          {
+            id: 'c1',
+            type: 'text',
+            label: 'c1',
+            properties: {},
+            styles: {},
+            order: 0,
+            hidden: false
+          }
+        ]
+      }
+    });
+
+    // useThemeSetting -> the stored value.
+    expect(screen.getByTestId('promo')).toHaveClass('bg-black');
+    // ThemeEditable -> the stored value where one exists...
+    expect(screen.getByRole('heading')).toHaveTextContent('Autumn');
+    // ...and the authored JSX where none does.
+    expect(screen.getByRole('img')).toHaveAttribute('src', '/default.jpg');
+    // ThemeSlot -> block.blocks, through the shared child pipeline.
+    expect(screen.getByTestId('slot-child')).toHaveAttribute('data-id', 'c1');
+  });
+
+  it('leaves a developer-authored part alone and stamps its own on the fields', () => {
+    renderRegistered(PROMO);
+
+    expect(screen.getByTestId('promo')).toHaveAttribute('data-part', 'shell');
+    expect(screen.getByRole('heading')).toHaveAttribute(
+      'data-part',
+      'field-headline'
+    );
+  });
+
+  it('collects a descriptor the editor could offer from a block that declared nothing', () => {
+    renderRegistered(PROMO);
+
+    const catalog = getCustomCatalog();
+    const descriptor = catalog?.blocks.find((entry) => entry.type === PROMO);
+
+    expect(catalog?.vendor).toBe('acme');
+    // The hook's key and both wrapped elements, from one render.
+    expect(descriptor?.settings.map((setting) => setting.key)).toEqual(
+      expect.arrayContaining(['tone', 'art', 'headline'])
+    );
+    // Every part the catalog advertises is one the DOM above actually carries.
+    expect(descriptor?.parts).toEqual(
+      expect.arrayContaining(['field-art', 'field-headline'])
+    );
+    // `<ThemeSlot />` alone makes the block droppable — no declaration needed.
+    expect(descriptor?.hasChildren).toBe(true);
+  });
+});
+
+describe('a block with several named slots', () => {
+  it('gives each slot its own node children and mixes none of them', () => {
+    const { container } = renderRegistered(MEGA_MENU, {
+      block: {
+        ...props().block,
+        type: MEGA_MENU,
+        blocks: [
+          slotNode('promo', 'in-promo'),
+          slotNode('links', 'in-links'),
+          slotNode('footer', 'in-footer')
+        ]
+      }
+    });
+
+    expect(
+      Array.from(container.querySelectorAll('[data-testid="slot-child"]')).map(
+        (node) => node.getAttribute('data-id')
+      )
+    ).toEqual(['in-promo', 'in-links', 'in-footer']);
+  });
+
+  it('renders the slots that do exist when the others have no node yet', () => {
+    // The state every composition starts in: the merchant has opened one
+    // region and not the others. Nothing crashes and nothing else appears.
+    const { container } = renderRegistered(MEGA_MENU, {
+      block: {
+        ...props().block,
+        type: MEGA_MENU,
+        blocks: [slotNode('links', 'in-links')]
+      }
+    });
+
+    expect(
+      Array.from(container.querySelectorAll('[data-testid="slot-child"]')).map(
+        (node) => node.getAttribute('data-id')
+      )
+    ).toEqual(['in-links']);
+  });
+
+  it('announces the slots and the declared part with its states', () => {
+    const descriptor = getCustomCatalog()?.blocks.find(
+      (entry) => entry.type === MEGA_MENU
+    );
+
+    expect(descriptor?.slots.map((slot) => slot.name)).toEqual([
+      'promo',
+      'links',
+      'footer'
+    ]);
+    expect(descriptor?.parts).toEqual(['row']);
+    expect(descriptor?.partStates).toEqual({ row: ['hover', 'open'] });
+  });
+});
+
+describe('the advertised parts and the rendered DOM', () => {
+  const partsIn = (container: HTMLElement): string[] =>
+    Array.from(container.querySelectorAll('[data-part]')).map(
+      (node) => node.getAttribute('data-part') as string
+    );
+
+  const descriptorFor = (type: string) =>
+    getCustomCatalog()?.blocks.find((entry) => entry.type === type);
+
+  it('advertises exactly the field parts the promo strip renders', () => {
+    const { container } = renderRegistered(PROMO);
+
+    // Set equality, not containment. A part in the catalog that no node
+    // answers to is a control the editor offers with nothing behind it — the
+    // styles a merchant saves against it generate a selector that matches
+    // nothing, and the click that should open it never resolves.
+    expect(new Set(descriptorFor(PROMO)?.parts)).toEqual(
+      new Set(partsIn(container).filter((part) => part.startsWith('field-')))
+    );
+  });
+
+  it('advertises no part for a field with no element of its own', () => {
+    const { container } = renderRegistered(LINK_CARD, {
+      block: { ...props().block, type: LINK_CARD }
+    });
+
+    const descriptor = descriptorFor(LINK_CARD);
+
+    // Both fields reach the panel...
+    expect(descriptor?.settings.map((setting) => setting.key)).toEqual([
+      'cta',
+      'ctaHref',
+      'note'
+    ]);
+    // ...and only the one element that carries `field-<key>` is advertised as
+    // a part. `ctaHref` shares the `<a>` with `cta`, and `note` gave its part
+    // up to the developer's own `footnote`.
+    expect(descriptor?.parts).toEqual(['field-cta']);
+    expect(partsIn(container)).toEqual(['field-cta', 'footnote']);
+    expect(new Set(descriptor?.parts)).toEqual(
+      new Set(partsIn(container).filter((part) => part.startsWith('field-')))
+    );
+  });
+});
+
+describe('the curated package root', () => {
+  /**
+   * Parsed from source rather than imported, exactly as
+   * `src/__tests__/registry-parity.test.ts` parses the registry — and here the
+   * reason is not weight but poison: `src/index.ts` re-exports
+   * `theme-placeholder`, which imports `server-only`, so the root entry throws
+   * "cannot be imported from a Client Component module" the moment a jsdom
+   * test (or a brand's client root) touches it. That constraint is why
+   * `@akinon/pz-theme/src/custom` is the documented path for block files, and
+   * it is also what makes the hand-written list in `src/index.ts` untestable
+   * by import: a renamed symbol there compiles fine and fails at the brand.
+   */
+  const rootSource = fs.readFileSync(
+    path.resolve(__dirname, '../../index.ts'),
+    'utf8'
+  );
+
+  const barrelSource = fs.readFileSync(
+    path.resolve(__dirname, '../index.ts'),
+    'utf8'
+  );
+
+  /** The names inside every `export { … } from '…'` clause a pattern selects. */
+  const exportedNames = (source: string, clause: RegExp): string[] =>
+    Array.from(source.matchAll(clause))
+      .flatMap((match) => match[1].split(','))
+      .map((name) => name.trim())
+      .filter(Boolean);
+
+  // `export type {` cannot match the runtime pattern: it requires `export {`
+  // with no word between, so the two lists stay disjoint.
+  const RUNTIME_FROM_CUSTOM = /export \{([^}]*)\} from '\.\/custom';/g;
+  const TYPES_FROM_CUSTOM = /export type \{([^}]*)\} from '\.\/custom';/g;
+  const ANY_TYPE_CLAUSE = /export type \{([^}]*)\} from '[^']*';/g;
+
+  it('names only bindings the custom barrel actually exports', () => {
+    const names = exportedNames(rootSource, RUNTIME_FROM_CUSTOM);
+
+    expect(names.length).toBeGreaterThan(0);
+    names.forEach((name) => {
+      expect(Object.keys(customBarrel)).toContain(name);
+    });
+  });
+
+  it('names only types the custom barrel actually exports', () => {
+    const rootTypes = exportedNames(rootSource, TYPES_FROM_CUSTOM);
+    const barrelTypes = exportedNames(barrelSource, ANY_TYPE_CLAUSE);
+
+    // Source-level because a type has no runtime binding to compare — the
+    // erased half of the surface would otherwise go completely unguarded.
+    expect(rootTypes.length).toBeGreaterThan(0);
+    expect(barrelTypes).toEqual(expect.arrayContaining(rootTypes));
+  });
+
+  it('does not publish partAttrs twice from one entry point', () => {
+    // `export * from './utils'` already puts it on the root. The custom barrel
+    // re-exports it so a block file needs one import; naming it in the root
+    // block too would be a second spelling of the same symbol.
+    expect(exportedNames(rootSource, RUNTIME_FROM_CUSTOM)).not.toContain(
+      'partAttrs'
+    );
+    expect(customBarrel.partAttrs).toBe(partAttrs);
+  });
+});