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

package/src/utils/visibility-rules.ts

@@ -1,5 +1,6 @@
 import { Block } from '../theme-block';
 import { Section } from '../theme-section';
+import { BREAKPOINT_FALLBACKS } from './breakpoints';
 import { devWarn } from './dev-warn';
 
 export type VisibilityAuthState = 'all' | 'authenticated' | 'guest';
@@ -9,6 +10,43 @@ export type VisibilityPathMatchType =
   | 'contains'
   | 'startsWith';
 
+/**
+ * Operators a data condition can use. `exists` / `notExists` answer for
+ * presence, the rest compare — three textual and four numeric, because a
+ * catalogue condition is as often "stock is below 5" as "gender is women".
+ */
+export type VisibilityDataOperator =
+  | 'exists'
+  | 'notExists'
+  | 'equals'
+  | 'notEquals'
+  | 'contains'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte';
+
+export const VISIBILITY_DATA_OPERATORS: VisibilityDataOperator[] = [
+  'exists',
+  'notExists',
+  'equals',
+  'notEquals',
+  'contains',
+  'gt',
+  'gte',
+  'lt',
+  'lte'
+];
+
+/** One condition against the page context, e.g. `product.attributes.gender`. */
+export interface VisibilityDataCondition {
+  path: string;
+  operator: VisibilityDataOperator;
+  value?: string;
+}
+
+export type VisibilityDataMatchMode = 'all' | 'any';
+
 export interface VisibilityRules {
   enabled?: boolean;
   authState?: VisibilityAuthState;
@@ -19,8 +57,41 @@ export interface VisibilityRules {
   pathnameValue?: string;
   queryParamKey?: string;
   queryParamValue?: string;
+  dataConditions?: VisibilityDataCondition[];
+  dataMatchMode?: VisibilityDataMatchMode;
 }
 
+/**
+ * Whether the viewport being rendered is on the rule's allow-list.
+ *
+ * The list is a set of breakpoint names, and until now there were only two to
+ * choose from. Every rule already published that says "mobile only" was written
+ * when `mobile` meant *everything below 1024* — so reading such a list
+ * literally against a three-way signal would hide a mobile-only banner on every
+ * tablet, silently, on compositions nobody touched.
+ *
+ * So the list falls through the way every other authored value in this system
+ * now does: a breakpoint the list does not mention inherits the answer given
+ * for the breakpoint it falls back to. A list naming `tablet` is read literally,
+ * which is what a rule authored in the current editor does.
+ *
+ * The one thing this cannot express is "phone but not tablet" — the data has no
+ * way to tell a deliberately-unticked tablet from one that could not be ticked
+ * when the rule was saved. That is a real limitation, and the alternative is
+ * changing what a published rule does, which is worse.
+ */
+export const isBreakpointAllowed = (
+  allowed: string[],
+  breakpoint: string
+): boolean => {
+  if (allowed.includes(breakpoint)) return true;
+
+  const chain = BREAKPOINT_FALLBACKS[breakpoint];
+  if (!chain) return false;
+
+  return chain.some((next) => allowed.includes(next));
+};
+
 export interface VisibilityRuleContext {
   authState: 'authenticated' | 'guest' | 'loading';
   breakpoint: string;
@@ -30,6 +101,18 @@ export interface VisibilityRuleContext {
   searchParams?: {
     get: (key: string) => string | null;
   } | null;
+  /**
+   * What the page is about — the product, the listing, the category. The server
+   * serializes this into the client tree and the walk below is pure, so both
+   * renders reach the same answer and the page hydrates into the shape it
+   * rendered. Absent (the default) means data conditions have nothing to read.
+   */
+  pageContext?: Record<string, unknown> | null;
+  /**
+   * The editor canvas usually sits on a page with no live product, so data
+   * conditions are not evaluated there — see evaluateVisibilityRules.
+   */
+  isDesigner?: boolean;
 }
 
 const normalizeStringArray = (value: unknown): string[] => {
@@ -39,6 +122,243 @@ const normalizeStringArray = (value: unknown): string[] => {
     .filter(Boolean);
 };
 
+/**
+ * A row with no path is an unfinished condition, not a condition that fails:
+ * it is dropped here. Keeping it and failing closed would let a designer save
+ * a half-typed row and blank the block on the storefront while the canvas —
+ * which skips data conditions — still shows it. That is the one failure mode
+ * nobody can debug from the editor.
+ */
+const normalizeDataConditions = (value: unknown): VisibilityDataCondition[] => {
+  if (!Array.isArray(value)) return [];
+
+  return value
+    // Annotated so the element type matches the predicate below: `value` is
+    // optional on a condition but always present in the object literal, and a
+    // type predicate must be assignable to what it narrows.
+    .map((entry): VisibilityDataCondition | null => {
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+        return null;
+      }
+
+      const candidate = entry as Record<string, unknown>;
+      const path = String(candidate.path || '').trim();
+      if (!path) return null;
+
+      const operator = VISIBILITY_DATA_OPERATORS.includes(
+        candidate.operator as VisibilityDataOperator
+      )
+        ? (candidate.operator as VisibilityDataOperator)
+        : 'exists';
+
+      return {
+        path,
+        operator,
+        value: String(candidate.value ?? '')
+      };
+    })
+    .filter((entry): entry is VisibilityDataCondition => entry !== null);
+};
+
+// Same notion of "there is nothing here" the per-row rules use: a product with
+// an empty attributes object carries no attribute, so `exists` must say no.
+const isEmptyValue = (value: unknown): boolean => {
+  if (value === undefined || value === null) return true;
+  if (typeof value === 'string') return value.trim() === '';
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === 'object') return Object.keys(value).length === 0;
+  return false;
+};
+
+/**
+ * The exact path shapes this file can read, and therefore the only shapes the
+ * field picker may offer: a key, `.key`, an index `[0]`, and the bare `[]` the
+ * discovery walk emits for "every element of this array".
+ *
+ * Anything else — `[*]`, a trailing dot, an empty segment — is refused rather
+ * than silently mis-tokenised into a shorter path that resolves to the wrong
+ * value (or, worse, to a parent that happens to exist).
+ */
+const READABLE_PATH = /^[^.[\]]+(?:\.[^.[\]]+|\[\d*\])*$/;
+const PATH_TOKEN = /[^.[\]]+|\[\d*\]/g;
+
+/**
+ * Segments that would read off the prototype chain rather than off the payload.
+ * Merchant data is untrusted, and `product.constructor` answering `exists` on
+ * every page is a rule that looks like it works and never does.
+ *
+ * Naming them is not enough on its own — `toString`, `valueOf` and the rest of
+ * Object.prototype answer the same way — so the walk below also reads own
+ * properties only. This list stays because a named refusal can warn the
+ * designer, where an own-property miss is indistinguishable from a typo.
+ */
+const UNREADABLE_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Resolve a path to the values it selects: one value for a plain path, one per
+ * element for each `[]` it crosses. `null` means the path is not readable at
+ * all, which is a different answer from "reads as nothing".
+ *
+ * Same walk the bindings use, so `product.images[0].url` reads identically.
+ */
+const readPageContextPaths = (
+  source: unknown,
+  path: string
+): unknown[] | null => {
+  if (!READABLE_PATH.test(path)) return null;
+
+  const tokens = path.match(PATH_TOKEN) || [];
+  if (tokens.some(token => UNREADABLE_SEGMENTS.has(token))) return null;
+
+  let values: unknown[] = [source];
+
+  for (const token of tokens) {
+    const next: unknown[] = [];
+
+    for (const value of values) {
+      if (value === undefined || value === null) continue;
+
+      if (token === '[]') {
+        // Pushed one by one: a listing can carry thousands of products and
+        // spreading that into an argument list is what blows the stack.
+        if (Array.isArray(value)) {
+          for (const element of value) next.push(element);
+        }
+        continue;
+      }
+
+      if (token.startsWith('[')) {
+        const index = Number.parseInt(token.slice(1, -1), 10);
+        if (Array.isArray(value)) next.push(value[index]);
+        continue;
+      }
+
+      // Own properties only. The page context is JSON the server serialized
+      // into the client tree, so everything real about the page is an own key;
+      // anything inherited is Object.prototype leaking in. It matters because
+      // a prototype member is a function, which every operator reads as
+      // "present" — `product.toString exists` would show the block on every
+      // page ever rendered. Also keeps SSR and hydration honest: a getter that
+      // lives on a class prototype server-side does not survive serialization.
+      if (Object.prototype.hasOwnProperty.call(value, token)) {
+        next.push((value as Record<string, unknown>)[token]);
+      }
+    }
+
+    values = next;
+    if (values.length === 0) return values;
+  }
+
+  return values;
+};
+
+/** null means "not comparable as text" (object, array, missing). */
+const toScalarString = (value: unknown): string | null => {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value) : null;
+  if (typeof value === 'boolean') return String(value);
+  return null;
+};
+
+const toComparableNumber = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string' && value.trim() !== '') return Number(value);
+  return Number.NaN;
+};
+
+/**
+ * A path that resolves to nothing hides the block — every operator except
+ * `notExists`, whose whole job is to answer for absence.
+ *
+ * Failing open is the tempting default and the wrong one: one typo in
+ * `product.attributes.gender` would put the women's size guide on every men's
+ * PDP and the "no results" copy on a page full of products. Wrong content that
+ * looks plausible survives QA; a block that never appears is caught in the
+ * first preview. Missing data also genuinely means "this page is not about
+ * that thing" — there is no `product` root on a category page — which is
+ * exactly when the block should stay away.
+ *
+ * A path this file cannot read is stricter still: it hides for every operator,
+ * `notExists` included, because "unreadable" is not evidence of absence.
+ */
+const evaluateDataCondition = (
+  condition: VisibilityDataCondition,
+  pageContext: Record<string, unknown> | null | undefined
+): boolean => {
+  const resolvedValues = readPageContextPaths(pageContext, condition.path);
+
+  if (resolvedValues === null) {
+    // Not "absent" but "unreadable": no operator can answer it, `notExists`
+    // included, so the block stays hidden and the warning names the path.
+    devWarn(
+      'visibilityRules',
+      `Cannot read the field path "${condition.path}"; the condition never passes (content stays hidden)`
+    );
+    return false;
+  }
+
+  // A `[]` in the path means "any element matches": one element carrying the
+  // value shows the block, and `exists` / `notExists` stay exact duals of each
+  // other. A path without `[]` selects a single value, so this is the same
+  // answer it has always given.
+  const presentValues = resolvedValues.filter(value => !isEmptyValue(value));
+  const isPresent = presentValues.length > 0;
+
+  if (condition.operator === 'exists') return isPresent;
+  if (condition.operator === 'notExists') return !isPresent;
+
+  if (!isPresent) return false;
+
+  const ruleValue = String(condition.value ?? '').trim();
+  if (!ruleValue) return false;
+
+  return presentValues.some(resolved =>
+    compareResolvedValue(resolved, condition.operator, ruleValue)
+  );
+};
+
+const compareResolvedValue = (
+  resolved: unknown,
+  operator: VisibilityDataOperator,
+  ruleValue: string
+): boolean => {
+  switch (operator) {
+    case 'equals':
+    case 'notEquals': {
+      // Case-insensitive: brands return "Women" while designers type "women",
+      // and a fail-closed rule turns that mismatch into an invisible block.
+      const scalar = toScalarString(resolved);
+      if (scalar === null) return false;
+      const matches = scalar.toLowerCase() === ruleValue.toLowerCase();
+      return operator === 'equals' ? matches : !matches;
+    }
+    case 'contains': {
+      if (Array.isArray(resolved)) {
+        return resolved.some(
+          entry => toScalarString(entry)?.toLowerCase() === ruleValue.toLowerCase()
+        );
+      }
+      const scalar = toScalarString(resolved);
+      return scalar !== null && scalar.toLowerCase().includes(ruleValue.toLowerCase());
+    }
+    case 'gt':
+    case 'gte':
+    case 'lt':
+    case 'lte': {
+      const left = toComparableNumber(resolved);
+      const right = toComparableNumber(ruleValue);
+      if (!Number.isFinite(left) || !Number.isFinite(right)) return false;
+
+      if (operator === 'gt') return left > right;
+      if (operator === 'gte') return left >= right;
+      if (operator === 'lt') return left < right;
+      return left <= right;
+    }
+    default:
+      return false;
+  }
+};
+
 export const normalizeVisibilityRules = (value: unknown): VisibilityRules => {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     // A truthy-but-non-object value (string, number, array) is a malformed
@@ -61,7 +381,9 @@ export const normalizeVisibilityRules = (value: unknown): VisibilityRules => {
       pathnameMatchType: 'any',
       pathnameValue: '',
       queryParamKey: '',
-      queryParamValue: ''
+      queryParamValue: '',
+      dataConditions: [],
+      dataMatchMode: 'all'
     };
   }
 
@@ -85,7 +407,9 @@ export const normalizeVisibilityRules = (value: unknown): VisibilityRules => {
         : 'any',
     pathnameValue: String(rules.pathnameValue || '').trim(),
     queryParamKey: String(rules.queryParamKey || '').trim(),
-    queryParamValue: String(rules.queryParamValue || '').trim()
+    queryParamValue: String(rules.queryParamValue || '').trim(),
+    dataConditions: normalizeDataConditions(rules.dataConditions),
+    dataMatchMode: rules.dataMatchMode === 'any' ? 'any' : 'all'
   };
 };
 
@@ -108,7 +432,7 @@ export const evaluateVisibilityRules = (
   if (
     rules.allowedBreakpoints &&
     rules.allowedBreakpoints.length > 0 &&
-    !rules.allowedBreakpoints.includes(context.breakpoint)
+    !isBreakpointAllowed(rules.allowedBreakpoints, context.breakpoint)
   ) {
     return false;
   }
@@ -161,6 +485,25 @@ export const evaluateVisibilityRules = (
     }
   }
 
+  // Data conditions are skipped on the canvas. Most editor pages carry no live
+  // product, so evaluating them would hide the block the instant the rule is
+  // saved — and a designer cannot style what they just made disappear. Visitor
+  // conditions above keep applying there, because those the canvas can preview
+  // (breakpoint switcher, locale switcher, auth toggle).
+  const dataConditions = rules.dataConditions || [];
+  if (!context.isDesigner && dataConditions.length > 0) {
+    const results = dataConditions.map(condition =>
+      evaluateDataCondition(condition, context.pageContext)
+    );
+
+    const isSatisfied =
+      rules.dataMatchMode === 'any'
+        ? results.some(Boolean)
+        : results.every(Boolean);
+
+    if (!isSatisfied) return false;
+  }
+
   return true;
 };