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

package/src/blocks/icon-button-block.tsx

@@ -0,0 +1,180 @@
+'use client';
+
+import React from 'react';
+import { Image } from '@akinon/next/components/image';
+import { getResponsiveValue } from '../utils';
+import { escapeCssAttributeValue } from '../utils/css-safety';
+import { useThemeSettingsContext } from '../theme-settings-context';
+import { BlockRendererProps } from './block-renderer-registry';
+import { DesignerPlaceholder } from './product-block-utils';
+import type { IconSource } from './icon-source';
+import { IconGlyph, resolveIconSource } from './icon-source';
+
+/**
+ * A control that is nothing but an icon: the descriptor
+ * (pz-dynamic-widget `block-registry.ts`, `BlockType.ICON_BUTTON`) declares
+ * exactly two properties — `icon` and `iconSize` — plus the shared ones every
+ * block gets. Deliberately narrower than the plain `icon` block, which also
+ * carries `alt` and position controls; neither exists here and neither is
+ * invented.
+ *
+ * What makes it read as a button is the box: `color`, `background-color` and
+ * the four margins are real CSS properties, so the generated rule paints them
+ * on the `[data-block-id]` wrapper and this file never touches them. `color`
+ * arriving there is also how the glyph is tinted, since every glyph is drawn
+ * with `currentColor`.
+ *
+ * Clicking is not wired here either. `WithDesignerFeatures` reads `actionType`
+ * / `actionTarget` centrally and turns the wrapper into the trigger; this
+ * renderer draws no anchor and no button, so the type stays out of
+ * `NATIVELY_INTERACTIVE_BLOCK_TYPES`.
+ */
+
+/**
+ * The name a freshly dropped block carries.
+ *
+ * The editor seeds `block.label` from the descriptor's `name`
+ * (`block-crud.reducers.ts`: `label: blockConfig.name`), so "Icon Button" is
+ * the ABSENCE of an authored name rather than one — announcing it to a screen
+ * reader would be pure noise.
+ */
+const DEFAULT_BLOCK_LABEL = 'icon button';
+
+const DEFAULT_ICON_SIZE = 20;
+
+/** `favourite-empty` -> `Favourite empty`. */
+const humanizeIconKey = (key: string): string => {
+  const words = key.replace(/[-_]+/g, ' ').trim();
+  if (!words) return '';
+
+  return words.charAt(0).toUpperCase() + words.slice(1);
+};
+
+/**
+ * Where the accessible name comes from, given a descriptor that offers no
+ * `alt` and no `ariaLabel`.
+ *
+ * The only authorable text on this block is its layer-tree name — the editor
+ * persists a rename into `block.label` (RENAME_BLOCK), and the wrapper's
+ * `ariaProps` carry `aria-haspopup`/`aria-expanded` but never a name. So when
+ * an action turns that wrapper into `role="button"`, the name it computes
+ * comes from this subtree and nowhere else.
+ *
+ * Falling back to the picked catalogue key ("Basket") beats falling back to
+ * nothing: it is what the designer chose, and it is what the icon depicts.
+ */
+export const readIconButtonName = (
+  label: string | undefined,
+  source: IconSource
+): string => {
+  const authored = String(label || '').trim();
+  if (authored && authored.toLowerCase() !== DEFAULT_BLOCK_LABEL) {
+    return authored;
+  }
+
+  return source.kind === 'glyph' ? humanizeIconKey(source.key) : '';
+};
+
+const readSize = (value: unknown): number => {
+  const numeric = Number(
+    String(value ?? '')
+      .replace(/px$/i, '')
+      .trim()
+  );
+  if (!Number.isFinite(numeric) || numeric <= 0) return DEFAULT_ICON_SIZE;
+
+  return Math.min(256, numeric);
+};
+
+const IconButtonBlock = ({
+  block,
+  currentBreakpoint = 'desktop',
+  isDesigner = false
+}: BlockRendererProps) => {
+  const themeSettings = useThemeSettingsContext();
+
+  // Both are bucketed per breakpoint on a dropped block — the descriptor's
+  // `getDefaultValue` seeds `{ desktop: ... }` for each — which is the one
+  // shape a flat read would get wrong.
+  const iconValue = getResponsiveValue(
+    block.properties?.icon,
+    currentBreakpoint,
+    ''
+  );
+  const iconSize = readSize(
+    getResponsiveValue(
+      block.properties?.iconSize,
+      currentBreakpoint,
+      DEFAULT_ICON_SIZE
+    )
+  );
+
+  const source = resolveIconSource(iconValue, themeSettings);
+  const name = readIconButtonName(block.label, source);
+
+  // An icon with no name is decoration, and decoration must stay out of the
+  // accessibility tree: announcing an unnamed graphic gives a screen reader
+  // user a stop with nothing to read at it.
+  const labelAttrs = name
+    ? { role: 'img', 'aria-label': name, 'aria-hidden': undefined }
+    : { 'aria-hidden': true as const };
+
+  if (source.kind === 'none') {
+    return isDesigner ? (
+      <DesignerPlaceholder
+        label="Icon button (no icon)"
+        attribute="data-icon-button"
+      />
+    ) : null;
+  }
+
+  if (source.kind === 'glyph') {
+    return (
+      <IconGlyph
+        data-icon-button=""
+        glyph={source.glyph}
+        size={iconSize}
+        {...labelAttrs}
+      />
+    );
+  }
+
+  if (source.kind === 'svg') {
+    // The uploaded markup carries its own width/height attributes, so the
+    // authored size has to reach the injected `<svg>` rather than the span
+    // around it. A scoped rule rather than `icon-block`'s Tailwind arbitrary
+    // variants: those only exist if the consuming brand's Tailwind build
+    // scans this package, and a size control that silently does nothing on
+    // some brands is worse than one extra rule on all of them.
+    const scopeId = block.styleSourceId || block.id;
+    const markupCss =
+      `[data-icon-button-id="${escapeCssAttributeValue(scopeId)}"] svg` +
+      `{width:${iconSize}px;height:${iconSize}px;}`;
+
+    return (
+      <span
+        data-icon-button=""
+        data-icon-button-id={scopeId}
+        {...labelAttrs}
+        style={{ display: 'inline-flex' }}
+      >
+        <style>{markupCss}</style>
+        <span dangerouslySetInnerHTML={{ __html: source.markup }} />
+      </span>
+    );
+  }
+
+  return (
+    <Image
+      data-icon-button=""
+      src={source.url}
+      width={iconSize}
+      height={iconSize}
+      // An empty alt is the correct announcement for an unnamed icon; the
+      // component defaults it to '' anyway, and this makes that deliberate.
+      alt={name}
+    />
+  );
+};
+
+export default IconButtonBlock;

package/src/blocks/icon-group-block.tsx

@@ -0,0 +1,119 @@
+'use client';
+
+import React from 'react';
+import { getResponsiveValue } from '../utils';
+import { escapeCssAttributeValue } from '../utils/css-safety';
+import { BlockRendererProps } from './block-renderer-registry';
+import { DesignerPlaceholder } from './product-block-utils';
+import { renderComposedChildren } from './render-composed-children';
+
+/**
+ * A set of icons sized together.
+ *
+ * The descriptor (pz-dynamic-widget `block-registry.ts`,
+ * `BlockType.ICON_GROUP`) declares `properties: []` and a single `size` style,
+ * so everything this block owns is the size of the icons underneath it — the
+ * children are ordinary blocks, rendered through the package's own
+ * `renderComposedChildren` so they stay movable, hideable and renamable on the
+ * canvas.
+ *
+ * `size` is the one style key this file may read: it is not a CSS property any
+ * element understands, so the generator emits `size: 18` onto the wrapper and
+ * the browser drops it. Every other style the merchant sets — display, gap,
+ * padding, background — already lands on that wrapper and is deliberately
+ * untouched here.
+ */
+
+/** The descriptor's own default, so an unset control still sizes the set. */
+const DEFAULT_ICON_SIZE = 18;
+
+export interface IconGroupBlockProps extends BlockRendererProps {
+  /**
+   * A resolved colour to tint the set with. Only `icon-group-colored` passes
+   * one; see that file for why it must already be a real colour by the time it
+   * arrives.
+   */
+  tint?: string;
+}
+
+const readSize = (value: unknown): number => {
+  const numeric = Number(
+    String(value ?? '')
+      .replace(/px$/i, '')
+      .trim()
+  );
+  if (!Number.isFinite(numeric) || numeric <= 0) return DEFAULT_ICON_SIZE;
+
+  return Math.min(256, numeric);
+};
+
+const IconGroupBlock = ({
+  block,
+  placeholderId,
+  sectionId,
+  isDesigner,
+  selectedBlockId,
+  currentBreakpoint = 'desktop',
+  tint
+}: IconGroupBlockProps) => {
+  const children = renderComposedChildren({
+    blocks: block.blocks,
+    placeholderId,
+    sectionId,
+    isDesigner,
+    selectedBlockId,
+    currentBreakpoint
+  });
+
+  if (children.length === 0) {
+    return isDesigner ? (
+      <DesignerPlaceholder
+        label="Icon group (no icons)"
+        attribute="data-icon-group"
+      />
+    ) : null;
+  }
+
+  const size = readSize(
+    getResponsiveValue(block.styles?.size, currentBreakpoint, DEFAULT_ICON_SIZE)
+  );
+
+  // A stylesheet rather than inline styles because the elements being sized
+  // belong to the CHILD blocks: this block cannot reach into their markup, and
+  // a CSS rule is the only thing that crosses that boundary. Scoped to this
+  // block's own id so it sizes its own set and nothing else on the page, and
+  // written as a descendant rule so it outranks the width/height ATTRIBUTES an
+  // icon carries (a presentation attribute loses to any declaration).
+  //
+  // Safe to write as a bare `svg`/`img` descendant: the only other icons that
+  // could appear under this block are the designer's own action-toolbar
+  // glyphs, and that toolbar is portaled to <body> (action-toolbar.tsx), so it
+  // is never a DOM descendant of the group.
+  const scopeId = block.styleSourceId || block.id;
+  const scope = `[data-icon-group-id="${escapeCssAttributeValue(scopeId)}"]`;
+  const sizeCss = `${scope} svg,${scope} img{width:${size}px;height:${size}px;}`;
+
+  return (
+    <span
+      data-icon-group=""
+      data-icon-group-id={scopeId}
+      style={{
+        // Transparent to layout, so the merchant's `display: flex` and `gap`
+        // on the wrapper reach the icons instead of stopping at one flex item
+        // — the same reason `group-block` renders `className="contents"`.
+        // Inline rather than the Tailwind class because a brand whose Tailwind
+        // build does not scan this package would otherwise get a plain inline
+        // box here and lose the row layout entirely.
+        display: 'contents',
+        // Inherits into every child that draws with `currentColor`. Absent on
+        // the plain group, which is what keeps the twins one implementation.
+        ...(tint ? { color: tint } : null)
+      }}
+    >
+      <style>{sizeCss}</style>
+      {children}
+    </span>
+  );
+};
+
+export default IconGroupBlock;

package/src/blocks/icon-group-colored-block.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import React from 'react';
+import { getResponsiveValue, resolveThemeCssVariables } from '../utils';
+import { useThemeSettingsContext } from '../theme-settings-context';
+import { BlockRendererProps } from './block-renderer-registry';
+import IconGroupBlock from './icon-group-block';
+
+/**
+ * The icon group with the colour control on.
+ *
+ * Its descriptor is the plain group's descriptor plus one `color` style, so
+ * this is the plain renderer plus one resolved tint — not a second copy of it.
+ * Twins that are hand-copied drift: a fix to child rendering, to the empty
+ * state or to the size rule would have to be remembered twice, and the second
+ * one is the one nobody remembers.
+ *
+ * Why the colour is read here at all, when a real CSS property normally
+ * belongs to the generated rule on the wrapper: the swatch stores theme
+ * colours as the literal string `var(--theme-primary)`, and the storefront is
+ * not obliged to define that custom property anywhere — the theme's colours
+ * live in the theme SETTINGS object, which only `resolveThemeCssVariables`
+ * can look them up in. So the generated `color: var(--theme-primary)` can
+ * resolve to nothing at all, and an icon drawn with `currentColor` inherits
+ * whatever the page happened to have.
+ *
+ * The tint is therefore applied ONLY when resolution actually changed the
+ * string, i.e. when a token was mapped to a real colour. A plain hex is left
+ * entirely to the stylesheet, which keeps the merchant's per-breakpoint
+ * `color` — and the media queries the same sheet emits for it — intact.
+ */
+const IconGroupColoredBlock = (props: BlockRendererProps) => {
+  const themeSettings = useThemeSettingsContext();
+  const { block, currentBreakpoint = 'desktop' } = props;
+
+  const authored = String(
+    getResponsiveValue(block.styles?.color, currentBreakpoint, '') ?? ''
+  ).trim();
+  const resolved = authored
+    ? resolveThemeCssVariables(authored, themeSettings)
+    : '';
+  const tint = resolved && resolved !== authored ? resolved : undefined;
+
+  return <IconGroupBlock {...props} tint={tint} />;
+};
+
+export default IconGroupColoredBlock;

package/src/blocks/icon-source.tsx

@@ -0,0 +1,311 @@
+import React from 'react';
+
+/**
+ * The keys the editor's icon picker offers out of the box.
+ *
+ * Source of truth is the editor's `DEFAULT_ICON_CATEGORIES`
+ * (pz-dynamic-widget `src/pages/settings/constants.ts`), grouped there as
+ * navigation / actions / interface / visibility / miscellaneous. The picker
+ * stores the KEY when the brand has not uploaded its own SVG for it
+ * (`icon-input.tsx` saves the uploaded markup when there is any, and the bare
+ * key when there is not), so a storefront whose theme settings carry no icons
+ * was receiving values like `basket` with nothing to draw them with.
+ *
+ * Drawn to one recipe on purpose — 24x24, `stroke="currentColor"`,
+ * `fill="none"`, stroke width 1.5, round caps and joins — because these sit
+ * next to each other in a header row, and a set that mixes weights reads as
+ * broken long before anyone can say which glyph is wrong.
+ */
+export const ICON_GLYPHS: Record<string, React.ReactNode> = {
+  // navigation
+  home: (
+    <path d="M3.5 10.8L12 4l8.5 6.8V19a1.5 1.5 0 0 1-1.5 1.5h-4.2v-6H9.2v6H5A1.5 1.5 0 0 1 3.5 19z" />
+  ),
+  'back-arrow': <path d="M15 4.5L7.5 12l7.5 7.5" />,
+  'right-arrow': <path d="M9 4.5l7.5 7.5L9 19.5" />,
+  'down-arrow': <path d="M4.5 9l7.5 7.5L19.5 9" />,
+  'up-arrow': <path d="M4.5 15l7.5-7.5 7.5 7.5" />,
+
+  // actions
+  add: <path d="M12 4.5v15M4.5 12h15" />,
+  remove: <path d="M4.5 12h15" />,
+  close: <path d="M5.5 5.5l13 13M18.5 5.5l-13 13" />,
+  check: <path d="M4.5 12.5l5 5 10-11" />,
+  'circle-check': (
+    <>
+      <circle cx="12" cy="12" r="8.5" />
+      <path d="M8 12.2l2.6 2.6L16 9.4" />
+    </>
+  ),
+  'filter-icon': <path d="M4 5.5h16l-6.2 7.2V19l-3.6-2v-4.3z" />,
+  'sort-icon': (
+    <>
+      <path d="M7 4.5v15M3.8 16.3L7 19.5l3.2-3.2" />
+      <path d="M17 19.5v-15M13.8 7.7L17 4.5l3.2 3.2" />
+    </>
+  ),
+  // The picker control itself, not a bare chevron: a lone chevron here would
+  // be indistinguishable from `down-arrow` two rows up in the same grid.
+  'picker-icon': (
+    <>
+      <rect x="3.5" y="5" width="17" height="14" rx="2" />
+      <path d="M8.5 10.5l3.5 3.5 3.5-3.5" />
+    </>
+  ),
+  spinner: <path d="M12 3.5a8.5 8.5 0 1 0 8.5 8.5" />,
+
+  // interface
+  search: (
+    <>
+      <circle cx="10.8" cy="10.8" r="6.3" />
+      <path d="M15.4 15.4l5 5" />
+    </>
+  ),
+  basket: (
+    <>
+      <path d="M5 8h14l-1.1 12.5H6.1z" />
+      <path d="M9 8V6.4a3 3 0 0 1 6 0V8" />
+    </>
+  ),
+  'favourite-empty': (
+    <path d="M12 20.2l-7-6.6a4.3 4.3 0 0 1 6.1-6l.9 1 .9-1a4.3 4.3 0 0 1 6.1 6z" />
+  ),
+  // The only filled glyph in the set: an outline heart already means "not
+  // favourited", so the pair has to differ by fill rather than by shape.
+  'favourite-full': (
+    <path
+      fill="currentColor"
+      d="M12 20.2l-7-6.6a4.3 4.3 0 0 1 6.1-6l.9 1 .9-1a4.3 4.3 0 0 1 6.1 6z"
+    />
+  ),
+  gift: (
+    <>
+      <rect x="3.5" y="8" width="17" height="4" rx="1" />
+      <path d="M5.2 12v7.5a1 1 0 0 0 1 1h11.6a1 1 0 0 0 1-1V12" />
+      <path d="M12 8v12.5" />
+      <path d="M12 8H8.9A2.2 2.2 0 1 1 11.1 5.8 2.6 2.6 0 0 1 12 8z" />
+      <path d="M12 8h3.1A2.2 2.2 0 1 0 12.9 5.8 2.6 2.6 0 0 0 12 8z" />
+    </>
+  ),
+  share: (
+    <>
+      <circle cx="17.8" cy="5.8" r="2.6" />
+      <circle cx="6.2" cy="12" r="2.6" />
+      <circle cx="17.8" cy="18.2" r="2.6" />
+      <path d="M8.5 10.8l7-3.8M8.5 13.2l7 3.8" />
+    </>
+  ),
+  barcode: (
+    <path d="M4 5.5v13M7.2 5.5v13M10.4 5.5v13M13.6 5.5v13M16.8 5.5v13M20 5.5v13" />
+  ),
+  image: (
+    <>
+      <rect x="3.5" y="4.5" width="17" height="15" rx="2" />
+      <circle cx="8.6" cy="9.6" r="1.6" />
+      <path d="M4.2 16.8l4.8-4.6 3.8 3.6 2.6-2.4 4.4 4" />
+    </>
+  ),
+
+  // visibility
+  eye: (
+    <>
+      <path d="M2.8 12S6.6 5.8 12 5.8 21.2 12 21.2 12 17.4 18.2 12 18.2 2.8 12 2.8 12z" />
+      <circle cx="12" cy="12" r="3" />
+    </>
+  ),
+  'eye-blocked': (
+    <>
+      <path d="M2.8 12S6.6 5.8 12 5.8 21.2 12 21.2 12 17.4 18.2 12 18.2 2.8 12 2.8 12z" />
+      <circle cx="12" cy="12" r="3" />
+      <path d="M4.5 19.5l15-15" />
+    </>
+  ),
+  user: (
+    <>
+      <circle cx="12" cy="8.4" r="3.9" />
+      <path d="M4.5 20a7.5 7.5 0 0 1 15 0" />
+    </>
+  ),
+
+  // miscellaneous
+  hamburger: <path d="M4 7h16M4 12h16M4 17h16" />,
+  category: (
+    <>
+      <rect x="3.5" y="3.5" width="7" height="7" rx="1.2" />
+      <rect x="13.5" y="3.5" width="7" height="7" rx="1.2" />
+      <rect x="3.5" y="13.5" width="7" height="7" rx="1.2" />
+      <rect x="13.5" y="13.5" width="7" height="7" rx="1.2" />
+    </>
+  ),
+  trash: (
+    <>
+      <path d="M4 6.5h16" />
+      <path d="M9.5 6.5V4.6a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1v1.9" />
+      <path d="M6.6 6.5l1 13a1 1 0 0 0 1 .9h6.8a1 1 0 0 0 1-.9l1-13" />
+      <path d="M10.4 10v6.6M13.6 10v6.6" />
+    </>
+  ),
+  globe: (
+    <>
+      <circle cx="12" cy="12" r="8.5" />
+      <path d="M3.5 12h17" />
+      <path d="M12 3.5a15 15 0 0 1 0 17 15 15 0 0 1 0-17z" />
+    </>
+  )
+};
+
+/** What the resolver decided a stored icon value actually is. */
+export type IconSource =
+  | { kind: 'svg'; markup: string }
+  | { kind: 'url'; url: string }
+  | { kind: 'glyph'; key: string; glyph: React.ReactNode }
+  | { kind: 'none' };
+
+const NO_ICON: IconSource = { kind: 'none' };
+
+export const isInlineSvgMarkup = (value: string): boolean =>
+  value.includes('<svg') || value.includes('<?xml');
+
+/**
+ * Already addressable as it stands: a data URI, an absolute or
+ * protocol-relative URL, or a root-relative path the app serves itself.
+ */
+const isUrlValue = (value: string): boolean =>
+  value.startsWith('data:') ||
+  value.startsWith('http://') ||
+  value.startsWith('https://') ||
+  value.startsWith('//') ||
+  value.startsWith('/');
+
+/**
+ * A bare value that is a media path rather than a catalogue key.
+ *
+ * This distinction is the whole point of the module. Every bare value used to
+ * be prefixed with the image CDN host, so `basket` — the value the picker
+ * stores whenever the brand has not uploaded its own SVG — shipped as a
+ * request for `https://<cloud>/basket` and painted a broken image. A path
+ * announces itself: it has a directory separator, or a file extension.
+ */
+const looksLikeMediaPath = (value: string): boolean =>
+  value.includes('/') || /\.[a-z0-9]{2,4}$/i.test(value);
+
+/** Markup or URL, whichever the literal is; null when it is neither. */
+const classifyLiteral = (value: string): IconSource | null => {
+  if (isInlineSvgMarkup(value)) return { kind: 'svg', markup: value };
+  if (isUrlValue(value)) return { kind: 'url', url: value };
+  return null;
+};
+
+/**
+ * The panel stores a plain string, but published JSON has also carried `{url}`
+ * wrappers and localized maps, and `icon-block` has always unwrapped both.
+ * Kept here so every caller unwraps them the same way.
+ */
+const toIconString = (value: unknown): string => {
+  if (typeof value === 'string') return value.trim();
+  if (!value || typeof value !== 'object') return '';
+
+  const record = value as Record<string, unknown>;
+  if (typeof record.url === 'string') return record.url.trim();
+
+  const firstString = Object.values(record).find((v) => typeof v === 'string');
+  return firstString ? (firstString as string).trim() : '';
+};
+
+/**
+ * Answers what to draw for a stored icon value, in this order:
+ *
+ *   inline SVG markup -> data:/http(s)/root-relative URL
+ *   -> a key the brand uploaded into theme settings
+ *   -> a key in the inline catalogue
+ *   -> a genuine media path on the image CDN
+ *   -> nothing.
+ *
+ * Theme settings beat the catalogue because that upload IS the brand's
+ * override of the default icon; the catalogue is what a brand that never
+ * opened the settings page falls back to. The CDN branch is last, and now runs
+ * only for values that look like paths.
+ *
+ * `themeSettings.icons` holds raw SVG markup rather than URLs (the settings
+ * page injects it with `dangerouslySetInnerHTML`), but a brand that stored a
+ * URL there still resolves, because the stored value is classified rather than
+ * assumed.
+ */
+export const resolveIconSource = (
+  value: unknown,
+  themeSettings?: Record<string, unknown> | null
+): IconSource => {
+  const raw = toIconString(value);
+  if (!raw) return NO_ICON;
+
+  const literal = classifyLiteral(raw);
+  if (literal) return literal;
+
+  const uploaded = themeSettings?.icons as Record<string, unknown> | undefined;
+  if (uploaded && typeof uploaded === 'object') {
+    const stored = toIconString(uploaded[raw]);
+    // A theme-settings entry that is itself a bare key is not an icon; falling
+    // through to the catalogue draws something rather than nothing.
+    const storedSource = stored ? classifyLiteral(stored) : null;
+    if (storedSource) return storedSource;
+  }
+
+  const glyph = ICON_GLYPHS[raw];
+  if (glyph) return { kind: 'glyph', key: raw, glyph };
+
+  if (looksLikeMediaPath(raw)) {
+    const cloudName = process.env.NEXT_PUBLIC_IMAGE_CLOUD_NAME?.trim();
+    if (cloudName) {
+      return {
+        kind: 'url',
+        url: `https://${cloudName}/${raw.replace(/^\/+/, '')}`
+      };
+    }
+  }
+
+  return NO_ICON;
+};
+
+export interface IconGlyphProps
+  extends Omit<React.SVGProps<SVGSVGElement>, 'children'> {
+  /** A catalogue key, or the node a resolved `glyph` source carries. */
+  name?: string;
+  glyph?: React.ReactNode;
+  size?: number | string;
+}
+
+/**
+ * Draws one catalogue glyph at the set's shared recipe.
+ *
+ * `width`/`height` are attributes rather than CSS so the icon has an intrinsic
+ * size before any stylesheet arrives; a merchant who sizes the block still
+ * wins, because the generated rule lands on the wrapper around it.
+ */
+export const IconGlyph = ({
+  name,
+  glyph,
+  size = 24,
+  strokeWidth = 1.5,
+  ...rest
+}: IconGlyphProps) => {
+  const node = glyph ?? (name ? ICON_GLYPHS[name] : null);
+  if (!node) return null;
+
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={strokeWidth}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+      {...rest}
+    >
+      {node}
+    </svg>
+  );
+};