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

package/src/utils/property-switches.ts

@@ -0,0 +1,230 @@
+/**
+ * Property switches — a block that renders only while a property on an
+ * enclosing block says so, and a block revealed on hover of that block.
+ *
+ * A composed card (ZERO-4829's Product Card) is a tree of plain groups, texts
+ * and buttons, and the things a merchandiser wants to switch — the badge, the
+ * discount chip, the favourite, the colour swatches — are children several
+ * levels down. Without this, "no badge" means finding the right text block in
+ * the layer tree and hiding it; "favourite always visible" means editing CSS.
+ * With it, the card's ROOT carries a handful of booleans (`showBadge`,
+ * `favouriteOnHover`, …) the editor draws as toggles, and each child names the
+ * one it answers to:
+ *
+ *  - `properties.visibleWhenProperty: 'showBadge'` — the block is dropped when
+ *    the nearest enclosing block (or the section) that DEFINES `showBadge`
+ *    has it off. An ancestor that never set the property does not decide, so
+ *    a child whose switch nobody authored renders as it always did.
+ *  - `properties.hoverRevealWhenProperty: 'favouriteOnHover'` — when the
+ *    nearest definer has it on, the block is marked `revealOnHover` and the
+ *    element hovering reveals it — the nearest enclosing block that declares
+ *    `properties.hoverScope: true` (the card's root), else the definer itself
+ *    — is marked `hoverScope`; the block wrapper writes both as data
+ *    attributes and HOVER_REVEAL_CSS does the rest on pointer devices only.
+ *
+ * WHO DEFINES A SWITCH IS A CHAIN. The card's root can carry the switches, but
+ * so can whatever encloses the card — the product grid, the Product Cards
+ * section — and the nearest definer wins. That is the merchandiser's "hide the
+ * favourite on the section, then show it again on this one card": the section
+ * decides for every card that says nothing, a card that says something decides
+ * for itself. A card therefore leaves its switches UNSET by default and only
+ * writes one when the designer picks Show or Hide on it.
+ *
+ * Dropped, not `hidden`: the canvas keeps hidden blocks mounted so they stay
+ * selectable, which is right for the eye icon and wrong for a switch — a
+ * merchandiser who turns the badge off has to see it go.
+ *
+ * Pure, run once over the section tree before anything expands: the iterator
+ * copies a template's children as they are, so a child dropped here is absent
+ * from every clone and a marked one is marked on every clone.
+ */
+
+import type { Block } from '../theme-block';
+import type { Section } from '../theme-section';
+import { BREAKPOINT_FALLBACKS } from './breakpoints';
+
+export const VISIBLE_WHEN_PROPERTY = 'visibleWhenProperty';
+export const HOVER_REVEAL_WHEN_PROPERTY = 'hoverRevealWhenProperty';
+/** Declared on the block whose hover reveals the descendants that ask for one. */
+export const HOVER_SCOPE_PROPERTY = 'hoverScope';
+
+export const HOVER_SCOPE_ATTRIBUTE = 'data-hover-scope';
+export const REVEAL_ON_HOVER_ATTRIBUTE = 'data-reveal-on-hover';
+
+/**
+ * Desktop widths with a hovering pointer only. Below the desktop breakpoint
+ * the block is simply visible — what the brands' own cards do below `lg`, and
+ * what a designer previewing the mobile canvas on a desktop machine has to
+ * see; a touch tablet wide enough to count as desktop has no hover and shows
+ * it too. Keyboard users reach it through focus.
+ */
+export const HOVER_REVEAL_MEDIA = '(min-width: 1024px) and (hover: hover)';
+
+export const HOVER_REVEAL_CSS =
+  `@media ${HOVER_REVEAL_MEDIA}{` +
+  `[${HOVER_SCOPE_ATTRIBUTE}] [${REVEAL_ON_HOVER_ATTRIBUTE}]{opacity:0;transition:opacity .2s}` +
+  `[${HOVER_SCOPE_ATTRIBUTE}]:hover [${REVEAL_ON_HOVER_ATTRIBUTE}],` +
+  `[${HOVER_SCOPE_ATTRIBUTE}]:focus-within [${REVEAL_ON_HOVER_ATTRIBUTE}],` +
+  `[${REVEAL_ON_HOVER_ATTRIBUTE}]:focus-within{opacity:1}` +
+  '}';
+
+type Properties = Record<string, unknown>;
+
+interface Scope {
+  properties: Properties;
+  /**
+   * A section defines switches like any block, but it is not an element a
+   * pointer can hover — the section renderer writes no such attribute — so a
+   * hover reveal whose only candidate scope is the section stays visible.
+   */
+  isSection: boolean;
+  /** This block declared itself the hover scope of what it encloses. */
+  declaresHoverScope: boolean;
+  /** Set while the children are walked; written onto the node afterwards. */
+  hoverScope: boolean;
+}
+
+/**
+ * A per-breakpoint value, read the way the renderers read one. A local reader
+ * rather than `getResponsiveValue` from `./index`: that barrel pulls in the
+ * React helpers, and this pass is pure.
+ */
+const readResponsive = (value: unknown, breakpoint: string): unknown => {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return value;
+  }
+
+  const record = value as Properties;
+  const chain = [breakpoint, ...(BREAKPOINT_FALLBACKS[breakpoint] ?? []), 'desktop'];
+
+  for (const key of chain) {
+    if (record[key] !== undefined) return record[key];
+  }
+
+  return undefined;
+};
+
+/**
+ * A switch as authored: a boolean, the strings a select stores, or nothing.
+ * `undefined` means "not defined here", which is what lets the nearest
+ * definer be found — an empty string counts as undefined for the same reason
+ * (an editor control that was cleared).
+ */
+export const readSwitch = (
+  value: unknown,
+  breakpoint = 'desktop'
+): boolean | undefined => {
+  const raw = readResponsive(value, breakpoint);
+  if (raw === undefined || raw === null || raw === '') return undefined;
+  if (typeof raw === 'boolean') return raw;
+  if (typeof raw === 'number') return raw !== 0;
+
+  const normalized = String(raw).trim().toLowerCase();
+  if (normalized === 'true' || normalized === '1' || normalized === 'yes') {
+    return true;
+  }
+  if (normalized === 'false' || normalized === '0' || normalized === 'no') {
+    return false;
+  }
+
+  return undefined;
+};
+
+const readKey = (properties: Properties | undefined, name: string): string => {
+  const raw = readResponsive(properties?.[name], 'desktop');
+  return typeof raw === 'string' ? raw.trim() : '';
+};
+
+/** Innermost enclosing scope that defines the switch, or none. */
+const findDefiningScope = (
+  scopes: Scope[],
+  key: string,
+  breakpoint: string
+): { scope: Scope; value: boolean } | null => {
+  for (let index = scopes.length - 1; index >= 0; index -= 1) {
+    const value = readSwitch(scopes[index].properties[key], breakpoint);
+    if (value !== undefined) return { scope: scopes[index], value };
+  }
+
+  return null;
+};
+
+/**
+ * The element whose hover reveals a child: the nearest enclosing block that
+ * declared itself the scope, else the block that defined the switch. Never
+ * the section — there is nothing to hover.
+ */
+const findHoverScope = (scopes: Scope[], definer: Scope): Scope | null => {
+  for (let index = scopes.length - 1; index >= 0; index -= 1) {
+    if (scopes[index].declaresHoverScope) return scopes[index];
+  }
+
+  return definer.isSection ? null : definer;
+};
+
+const applyToBlocks = (
+  blocks: Block[] | undefined,
+  scopes: Scope[],
+  breakpoint: string
+): Block[] | undefined => {
+  if (!blocks || blocks.length === 0) return blocks;
+
+  const next: Block[] = [];
+
+  for (const block of blocks) {
+    const visibleKey = readKey(block.properties, VISIBLE_WHEN_PROPERTY);
+    if (visibleKey) {
+      const definer = findDefiningScope(scopes, visibleKey, breakpoint);
+      if (definer && !definer.value) continue;
+    }
+
+    let revealOnHover = false;
+    const hoverKey = readKey(block.properties, HOVER_REVEAL_WHEN_PROPERTY);
+    if (hoverKey) {
+      const definer = findDefiningScope(scopes, hoverKey, breakpoint);
+      const scope = definer?.value ? findHoverScope(scopes, definer.scope) : null;
+      if (scope) {
+        revealOnHover = true;
+        scope.hoverScope = true;
+      }
+    }
+
+    const own: Scope = {
+      properties: (block.properties || {}) as Properties,
+      isSection: false,
+      declaresHoverScope:
+        readSwitch(block.properties?.[HOVER_SCOPE_PROPERTY], breakpoint) === true,
+      hoverScope: false
+    };
+    const children = applyToBlocks(block.blocks, [...scopes, own], breakpoint);
+
+    next.push({
+      ...block,
+      ...(children !== block.blocks ? { blocks: children } : {}),
+      ...(revealOnHover ? { revealOnHover: true } : {}),
+      ...(own.hoverScope ? { hoverScope: true } : {})
+    });
+  }
+
+  return next;
+};
+
+/**
+ * The switches applied to every section. Each section is its own outermost
+ * scope, so a section property can drive a visibility switch too.
+ */
+export const applyPropertySwitchesToSections = (
+  sections: Section[],
+  breakpoint = 'desktop'
+): Section[] =>
+  sections.map((section) => {
+    const scope: Scope = {
+      properties: (section.properties || {}) as Properties,
+      isSection: true,
+      declaresHoverScope: false,
+      hoverScope: false
+    };
+    const blocks = applyToBlocks(section.blocks, [scope], breakpoint);
+
+    return blocks === section.blocks ? section : { ...section, blocks: blocks ?? [] };
+  });