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

package/src/utils/page-context-discovery.test.ts

@@ -0,0 +1,188 @@
+import { createPageContextDiscovery } from './page-context-discovery';
+import { evaluateVisibilityRules, VisibilityRuleContext } from './visibility-rules';
+
+const makeContext = (
+  pageContext: Record<string, unknown>
+): VisibilityRuleContext => ({
+  authState: 'guest',
+  breakpoint: 'desktop',
+  locale: 'tr',
+  currency: 'TRY',
+  pathname: '/',
+  searchParams: null,
+  pageContext
+});
+
+/**
+ * The picker writes a discovered path verbatim into a rule, so a path the
+ * evaluator cannot read is a block that disappears on the storefront while the
+ * canvas — which skips data conditions — still shows it. Every entry offered
+ * has to answer `exists` on the very page it was discovered from.
+ */
+const expectEveryDiscoveredPathToResolve = (
+  pageContext: Record<string, unknown>
+) => {
+  const discovery = createPageContextDiscovery(pageContext);
+  const unresolvable = discovery.entries
+    .map(entry => entry.path)
+    .filter(
+      path =>
+        !evaluateVisibilityRules(
+          { enabled: true, dataConditions: [{ path, operator: 'exists' }] },
+          makeContext(pageContext)
+        )
+    );
+
+  expect(unresolvable).toEqual([]);
+  return discovery;
+};
+
+describe('createPageContextDiscovery', () => {
+  const pdpContext = {
+    product: {
+      sku: 'TS-1',
+      stock: 3,
+      inStock: true,
+      attributes: { gender: 'Women', category: 'tops' },
+      tags: ['sale', 'new-season'],
+      images: [
+        { url: 'https://cdn.example.com/a.jpg', alt: 'front' },
+        { url: 'https://cdn.example.com/b.jpg', alt: 'back' }
+      ]
+    },
+    listing: {
+      totalCount: 2,
+      products: [
+        { sku: 'A', price: { value: 10, currency: 'TRY' } },
+        { sku: 'B', price: { value: 20, currency: 'TRY' } }
+      ]
+    }
+  };
+
+  it('offers only paths the rule evaluator can read', () => {
+    const discovery = expectEveryDiscoveredPathToResolve(pdpContext);
+
+    // The array-element paths are the majority of the interesting fields on a
+    // real page; they must be offered, not quietly dropped.
+    const paths = discovery.entries.map(entry => entry.path);
+    expect(paths).toContain('product.images[].url');
+    expect(paths).toContain('listing.products[].price.value');
+  });
+
+  it('keeps the array root alongside its element paths', () => {
+    const paths = createPageContextDiscovery(pdpContext).entries.map(
+      entry => entry.path
+    );
+
+    expect(paths).toContain('product.tags');
+    expect(paths).toContain('product.images');
+  });
+
+  it('drops merchant keys that cannot round-trip through a path', () => {
+    // Merchant payloads are untrusted: an attribute literally named
+    // "size.chart" would be offered as product.attributes.size.chart and read
+    // back as two nested keys that do not exist.
+    const context = {
+      product: {
+        attributes: {
+          'size.chart': 'https://cdn.example.com/size.pdf',
+          'legacy[0]': 'x',
+          '': 'y',
+          '  ': 'z',
+          gender: 'Women'
+        }
+      }
+    };
+
+    const discovery = expectEveryDiscoveredPathToResolve(context);
+    const paths = discovery.entries.map(entry => entry.path);
+
+    expect(paths).toEqual(['product.attributes.gender']);
+  });
+
+  it('drops prototype keys instead of offering a path into the prototype chain', () => {
+    const context = {
+      product: {
+        constructor: 'own-key-but-unreadable',
+        __proto__: 'also-unreadable',
+        sku: 'TS-1'
+      } as Record<string, unknown>
+    };
+
+    const paths = createPageContextDiscovery(context).entries.map(
+      entry => entry.path
+    );
+
+    expect(paths).toEqual(['product.sku']);
+  });
+
+  it('drops a root key that cannot round-trip', () => {
+    const discovery = createPageContextDiscovery({
+      'weird.root': { sku: 'A' },
+      product: { sku: 'B' }
+    });
+
+    expect(discovery.roots).toEqual(['product']);
+    expect(discovery.entries.map(entry => entry.path)).toEqual(['product.sku']);
+  });
+
+  it('drops keys the rule normaliser would trim into a different key', () => {
+    // A CSV import routinely produces an attribute named "size " — the rule
+    // normaliser trims the whole path, so `product.attributes.size ` is read
+    // back as `product.attributes.size` and the block never appears. A leading
+    // space on a root breaks the same way, from the other end.
+    const context = {
+      ' product': { sku: 'A' },
+      product: { attributes: { 'size ': 'L', ' fit': 'slim', gender: 'Women' } }
+    };
+
+    const discovery = expectEveryDiscoveredPathToResolve(context);
+
+    expect(discovery.roots).toEqual(['product']);
+    // The interior key keeps its space and still round-trips, so it stays.
+    expect(discovery.entries.map(entry => entry.path)).toEqual([
+      'product.attributes. fit',
+      'product.attributes.gender'
+    ]);
+  });
+
+  it('offers a field the page leaves empty as readable, not as broken', () => {
+    // `exists` says no for an empty listing or a null description, and that is
+    // the right answer — but the path is still one the evaluator can read, and
+    // a designer must be able to write `notExists` against it. Unreadable is
+    // the third answer: it fails both.
+    const sparse = {
+      product: { sku: 'TS-1', description: '', badge: null },
+      listing: { products: [], totalCount: 0 }
+    };
+
+    const paths = createPageContextDiscovery(sparse).entries.map(
+      entry => entry.path
+    );
+    expect(paths.length).toBeGreaterThan(0);
+
+    const unreadable = paths.filter(path => {
+      const answers = (['exists', 'notExists'] as const).map(operator =>
+        evaluateVisibilityRules(
+          { enabled: true, dataConditions: [{ path, operator }] },
+          makeContext(sparse)
+        )
+      );
+      return !answers[0] && !answers[1];
+    });
+
+    expect(unreadable).toEqual([]);
+  });
+
+  it('survives a self-referencing page context instead of overflowing the stack', () => {
+    const product: Record<string, unknown> = { sku: 'TS-1' };
+    product.self = product;
+
+    expect(() => createPageContextDiscovery({ product })).not.toThrow();
+    expectEveryDiscoveredPathToResolve({ product });
+  });
+
+  it('reports nothing for an absent page context', () => {
+    expect(createPageContextDiscovery(null)).toEqual({ roots: [], entries: [] });
+  });
+});

package/src/utils/page-context-discovery.ts

@@ -21,6 +21,27 @@ export interface PageContextDiscovery {
 const MAX_DISCOVERY_ENTRIES = 250;
 const MAX_SAMPLE_LENGTH = 60;
 
+/**
+ * Keys that cannot survive a round trip through a dotted path.
+ *
+ * Merchant payloads are untrusted, and an attribute literally named
+ * `size.chart` would be published as `product.attributes.size.chart`, read back
+ * as two nested keys that do not exist, and hide the block forever — while the
+ * canvas, which skips data conditions, keeps showing it. A key with a bracket
+ * mis-tokenises the same way, and an empty key resolves to its *parent*, which
+ * is worse: the rule quietly answers about the wrong value.
+ *
+ * `__proto__` / `constructor` / `prototype` are excluded for the same reason
+ * from the other end: the evaluator refuses to walk them, so offering them
+ * would hand a designer a path that never passes.
+ */
+const isRoundTrippableKey = (key: string): boolean =>
+  key.trim() !== '' &&
+  !/[.[\]]/.test(key) &&
+  key !== '__proto__' &&
+  key !== 'constructor' &&
+  key !== 'prototype';
+
 const getValueType = (value: unknown): DiscoveryValueType => {
   if (value === null) return 'null';
   if (Array.isArray(value)) return 'array';
@@ -65,7 +86,16 @@ export const createPageContextDiscovery = (
   const seen = new Set<string>();
 
   const pushEntry = (entry: PageContextDiscoveryEntry) => {
-    if (!entry.path || seen.has(entry.path) || entries.length >= MAX_DISCOVERY_ENTRIES) {
+    // The rule normaliser trims the whole path before reading it, so a path
+    // that ends in whitespace — a merchant attribute named "size ", which a
+    // CSV import produces routinely — is read back as a different key and the
+    // block never appears. Interior keys are untouched by that trim and stay.
+    if (
+      !entry.path ||
+      entry.path.trim() !== entry.path ||
+      seen.has(entry.path) ||
+      entries.length >= MAX_DISCOVERY_ENTRIES
+    ) {
       return;
     }
 
@@ -86,6 +116,10 @@ export const createPageContextDiscovery = (
         sample: formatSample(value)
       });
 
+      // `[]` is the one wildcard in this vocabulary and it means "any element":
+      // the rule evaluator resolves such a path to every element of the array,
+      // and the binding panel reads the same marker to map an iterator child
+      // onto `item.*`. The first element only supplies the shape and sample.
       if (value.length > 0) {
         walk(value[0], `${path}[]`);
       }
@@ -94,6 +128,8 @@ export const createPageContextDiscovery = (
 
     if (value && typeof value === 'object') {
       Object.entries(value as Record<string, unknown>).forEach(([key, child]) => {
+        if (!isRoundTrippableKey(key)) return;
+
         const nextPath = path ? `${path}.${key}` : key;
         walk(child, nextPath);
       });
@@ -108,12 +144,20 @@ export const createPageContextDiscovery = (
     });
   };
 
-  Object.entries(input).forEach(([rootKey, value]) => {
-    walk(value, rootKey);
+  // A root additionally may not carry leading whitespace: it sits at the front
+  // of every path built under it, and the rule normaliser trims there too.
+  // Not folded into isRoundTrippableKey because an interior key with edge
+  // whitespace does round-trip, and dropping those would cost real fields.
+  const roots = Object.keys(input).filter(
+    key => isRoundTrippableKey(key) && key === key.trim()
+  );
+
+  roots.forEach(rootKey => {
+    walk(input[rootKey], rootKey);
   });
 
   return {
-    roots: Object.keys(input),
+    roots,
     entries
   };
 };

package/src/utils/part-styles.ts

@@ -0,0 +1,229 @@
+/**
+ * Part styling: letting a designer style what is *inside* a functional block.
+ *
+ * Until now a block's styles produced exactly one rule, on the block root
+ * (`[data-block-id="…"]`), and every functional block drew its internals with
+ * inline styles. So a brand could move the variant dropdown around and hide
+ * it, but could not change its border, height or focus ring — the markup was
+ * out of reach and inline styles outrank any stylesheet anyway.
+ *
+ * A block now names its internals with `data-part` (see `partAttrs`), and a
+ * style key can address one:
+ *
+ *   "dropdown/border-color"          -> [data-block-id="x"] [data-part="dropdown"]
+ *   "dropdown/focus/border-color"    -> … [data-part="dropdown"]:focus-visible
+ *   "option/selected/background"     -> … [data-part="option"][data-state~="selected"]
+ *
+ * Values stay per breakpoint exactly like root styles, so nothing about
+ * storage, persistence or the responsive model changes — the key does all the
+ * work, which is also why existing published compositions are unaffected.
+ *
+ * Declarations are emitted `!important` on purpose: the element being styled
+ * usually carries the renderer's own inline defaults, and an override the
+ * designer just typed has to win over the default the block shipped with.
+ */
+
+/**
+ * State segment -> the selector suffixes that express it.
+ *
+ * Every state also matches `[data-state~="…"]`, including the ones that are
+ * really pseudo-classes. That is what lets the editor pin a state open: a
+ * designer cannot hover an element while typing a hover colour, so the canvas
+ * writes the state onto the element and the same rule applies.
+ */
+const STATE_SELECTORS: Record<string, string[]> = {
+  hover: [':hover', '[data-state~="hover"]'],
+  focus: [':focus-visible', ':focus', '[data-state~="focus"]'],
+  active: [':active', '[data-state~="active"]'],
+  // Native controls, ARIA and our own data-state all mean the same thing here,
+  // so each is covered rather than forcing renderers into one convention.
+  disabled: [':disabled', '[aria-disabled="true"]', '[data-state~="disabled"]'],
+  selected: [
+    '[data-state~="selected"]',
+    '[aria-selected="true"]',
+    '[aria-current="true"]'
+  ],
+  checked: [':checked', '[data-state~="checked"]', '[aria-checked="true"]'],
+  open: ['[data-state~="open"]', '[aria-expanded="true"]'],
+  invalid: ['[aria-invalid="true"]', '[data-state~="invalid"]'],
+  loading: ['[data-state~="loading"]'],
+  empty: ['[data-state~="empty"]'],
+  // Picked but not yet committed. A panel that stages its choices and applies
+  // them in one go has to show the shopper which ticks are already filtering
+  // the page and which are only waiting on the Apply button — "selected" alone
+  // cannot say both.
+  staged: ['[data-state~="staged"]'],
+  // A commerce answer is not binary. "We could not ask" has to look different
+  // from "we asked and it is not there", otherwise a store the shopper could
+  // still ring up reads as a dead end. `~=` matches whole tokens, so
+  // "unavailable" never satisfies the "available" selector.
+  available: ['[data-state~="available"]'],
+  unavailable: ['[data-state~="unavailable"]'],
+  unknown: ['[data-state~="unknown"]']
+};
+
+export const PART_STYLE_STATES = Object.keys(STATE_SELECTORS);
+
+/** Keys are `part/prop` or `part/state/prop`; `/` never appears in a CSS property. */
+const PART_KEY_DELIMITER = '/';
+
+export type ParsedPartKey = {
+  part: string;
+  state: string | null;
+  property: string;
+};
+
+export const parsePartStyleKey = (key: string): ParsedPartKey | null => {
+  if (!key || key.indexOf(PART_KEY_DELIMITER) === -1) return null;
+
+  const segments = key.split(PART_KEY_DELIMITER).filter(Boolean);
+
+  if (segments.length === 2) {
+    return { part: segments[0], state: null, property: segments[1] };
+  }
+
+  if (segments.length === 3 && STATE_SELECTORS[segments[1]]) {
+    return { part: segments[0], state: segments[1], property: segments[2] };
+  }
+
+  // Three segments with an unknown middle, or four+: not a part key. Returning
+  // null keeps it on the root bucket rather than silently dropping the style.
+  return null;
+};
+
+export const isPartStyleKey = (key: string): boolean =>
+  parsePartStyleKey(key) !== null;
+
+/** Builds the style key a descriptor writes into. */
+export const buildPartStyleKey = (
+  part: string,
+  property: string,
+  state?: string | null
+): string =>
+  state
+    ? [part, state, property].join(PART_KEY_DELIMITER)
+    : [part, property].join(PART_KEY_DELIMITER);
+
+/**
+ * `data-part` plus the states the renderer wants stylable. Renderers spread
+ * this onto the element instead of hand-writing the attributes, so the
+ * contract stays in one place.
+ *
+ *   <select {...partAttrs('dropdown')} />
+ *   <a {...partAttrs('option', { selected: isSelected, disabled })} />
+ */
+export const partAttrs = (
+  part: string,
+  states?: Record<string, boolean | undefined>
+): Record<string, string> => {
+  const attrs: Record<string, string> = { 'data-part': part };
+
+  if (states) {
+    const active = Object.entries(states)
+      .filter(([, on]) => on === true)
+      .map(([name]) => name);
+
+    if (active.length > 0) {
+      attrs['data-state'] = active.join(' ');
+    }
+  }
+
+  return attrs;
+};
+
+/** A part/state bucket of styles, ready for the CSS generator. */
+export type PartStyleBucket = {
+  part: string;
+  state: string | null;
+  styles: Record<string, unknown>;
+};
+
+/**
+ * Splits a block's styles into the root bucket and one bucket per
+ * part/state pair, preserving insertion order so generated CSS is stable
+ * (a moving stylesheet would defeat caching and make diffs unreadable).
+ */
+export const splitPartStyles = (
+  styles: Record<string, unknown> | undefined | null
+): { root: Record<string, unknown>; parts: PartStyleBucket[] } => {
+  const root: Record<string, unknown> = {};
+  const buckets = new Map<string, PartStyleBucket>();
+
+  Object.entries(styles || {}).forEach(([key, value]) => {
+    const parsed = parsePartStyleKey(key);
+
+    if (!parsed) {
+      root[key] = value;
+      return;
+    }
+
+    const bucketKey = `${parsed.part}::${parsed.state ?? ''}`;
+    const bucket = buckets.get(bucketKey) ?? {
+      part: parsed.part,
+      state: parsed.state,
+      styles: {}
+    };
+
+    bucket.styles[parsed.property] = value;
+    buckets.set(bucketKey, bucket);
+  });
+
+  return { root, parts: Array.from(buckets.values()) };
+};
+
+/** Only `[A-Za-z0-9_-]` survives, so a part name cannot break out of the selector. */
+const sanitizePartName = (part: string): string =>
+  String(part).replace(/[^A-Za-z0-9_-]/g, '');
+
+/**
+ * Confines a part rule to the block that declares the part.
+ *
+ * The rule is a descendant selector, and part names are deliberately generic
+ * (`header`, `panel`, `content`, `title`, `icon`, `list`, …) so a designer who
+ * learned one block's panel already knows the next one's. Those two facts
+ * collide as soon as a container block holds another block that named a part
+ * the same way: styling an accordion's header also restyled the header of a
+ * block sitting in its panel — an effect no panel announced and no panel could
+ * undo. Renaming the parts is not the fix; the names are shared on purpose and
+ * several of them are already published in live compositions.
+ *
+ * A part is owned by its *closest* `[data-block-id]` ancestor — the same rule
+ * the canvas already applies when deciding which part a click selected (see
+ * hooks/use-designer-features.tsx). In CSS that means excluding anything
+ * sitting inside a nested block. No renderer draws its own part inside a child
+ * block's wrapper, so nothing a block legitimately owns is caught by this.
+ *
+ * Wrapped in `:where()` because `:not()` otherwise takes the specificity of
+ * its argument. `:where()` contributes zero, so the rule keeps exactly the
+ * weight it had before and nothing re-orders in the cascade — the only
+ * elements that stop matching are the leaked ones. The guard is a single
+ * string per bucket and identical across a block's parts, which is what keeps
+ * it cheap on a path every composition walks.
+ */
+const buildOwnershipGuard = (blockSelector: string): string =>
+  `:not(:where(${blockSelector} [data-block-id] *))`;
+
+/**
+ * Selectors for one bucket. A state expands to one selector per accepted
+ * expression (`:disabled`, `[aria-disabled="true"]`, …) so a renderer can use
+ * whichever is natural for the element it is drawing.
+ */
+export const buildPartSelectors = (
+  blockSelector: string,
+  bucket: PartStyleBucket
+): string[] => {
+  const part = sanitizePartName(bucket.part);
+  if (!part) return [];
+
+  const base = `${blockSelector} [data-part="${part}"]`;
+  // Appended last: a state suffix can be an attribute selector, and those
+  // have to precede a pseudo-class inside a compound selector.
+  const owned = buildOwnershipGuard(blockSelector);
+
+  if (!bucket.state) return [`${base}${owned}`];
+
+  const suffixes = STATE_SELECTORS[bucket.state];
+  if (!suffixes) return [];
+
+  return suffixes.map((suffix) => `${base}${suffix}${owned}`);
+};