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

package/src/utils/row-visibility.ts

@@ -0,0 +1,273 @@
+/**
+ * Per-row visibility.
+ *
+ * A repeated row renders the same elements for every item — only bound values
+ * differ. Real catalogues are not like that: a discount badge exists on three
+ * products out of forty, a campaign label on two, a price-history caption only
+ * where there was a discount. Without this, a designer either shows an empty
+ * badge on every card or cannot have the badge at all.
+ *
+ * A block inside a row can carry `visibleWhen`, evaluated once per item. The
+ * result is written to the clone's existing `hidden` flag, so nothing
+ * downstream needs to learn a new concept — and the designer still sees the
+ * element on the canvas, because `hidden` only removes it on the storefront.
+ *
+ * The comparisons started out string-only, which cannot express the rule two
+ * brands print on every card: "lowest price in 30 days" when the previous
+ * price is above the current one, "advantage price" when it is below while the
+ * list price is above, nothing otherwise — one of them only past a 5% gap.
+ * That rule needs three things a string equality does not have: an ordering,
+ * a second *field* rather than a typed constant, and a percentage. All three
+ * are additive — a rule that sets none of them evaluates through exactly the
+ * same branches it did before.
+ */
+
+import { parseAmount } from '../blocks/commerce-format';
+
+export type RowVisibilityMode =
+  | 'always'
+  | 'not-empty'
+  | 'empty'
+  | 'equals'
+  | 'not-equals'
+  | 'truthy'
+  | 'falsy'
+  | 'greater-than'
+  | 'greater-or-equal'
+  | 'less-than'
+  | 'less-or-equal'
+  | 'percent-above'
+  | 'percent-below';
+
+/**
+ * Where the second operand comes from. Absent means the literal the designer
+ * typed — which is what every rule authored before this existed carries, so
+ * an untouched rule keeps comparing exactly what it compared before.
+ */
+export type RowVisibilityCompareTo = 'value' | 'field';
+
+export interface RowVisibilityRule {
+  field?: string;
+  mode?: RowVisibilityMode;
+  value?: string;
+  compareTo?: RowVisibilityCompareTo;
+  /** Percent forms only: how far apart the two sides have to be. */
+  threshold?: string;
+}
+
+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;
+};
+
+/** Same path walk the bindings use, so `item.foo.bar` behaves identically. */
+const readPath = (source: unknown, path: string): unknown => {
+  // A bare `item` names the row itself, the same spelling the bindings take —
+  // the only way to state a rule about an entry of a list of plain values.
+  const rowPath = path === 'item' ? '' : path.replace(/^item\./, '');
+  const tokens = rowPath.match(/[^.[\]]+|\[(\d+)\]/g) || [];
+  let value: unknown = source;
+
+  for (const token of tokens) {
+    if (value === undefined || value === null) return undefined;
+
+    if (token.startsWith('[') && token.endsWith(']')) {
+      const index = Number.parseInt(token.slice(1, -1), 10);
+      value = Array.isArray(value) ? value[index] : undefined;
+      continue;
+    }
+
+    value = (value as Record<string, unknown>)?.[token];
+  }
+
+  return value;
+};
+
+/** Reads the rule off a block's properties, tolerating the responsive wrapper. */
+export const readRowVisibility = (
+  properties: Record<string, unknown> | undefined | null,
+  currentBreakpoint = 'desktop'
+): RowVisibilityRule | null => {
+  // `allowNumber` is opt-in per key: the three original keys keep reading
+  // strings only, so a number that somehow landed in one of them still
+  // resolves to '' exactly as it did before.
+  const unwrap = (key: string, allowNumber = false): string => {
+    const entry = properties?.[key];
+    if (entry === undefined || entry === null) return '';
+    if (typeof entry === 'string') return entry;
+    if (allowNumber && typeof entry === 'number') return String(entry);
+    if (typeof entry === 'object') {
+      const responsive = entry as Record<string, unknown>;
+      // The same fall-through the stylesheet emits: a tablet with nothing of
+      // its own reads the mobile bucket, whose query covers its width.
+      const value =
+        currentBreakpoint === 'mobile'
+          ? responsive.mobile ?? responsive.desktop
+          : currentBreakpoint === 'tablet'
+          ? responsive.tablet ?? responsive.mobile ?? responsive.desktop
+          : responsive.desktop;
+      if (typeof value === 'string') return value;
+      if (allowNumber && typeof value === 'number') return String(value);
+      return '';
+    }
+    return '';
+  };
+
+  const mode = unwrap('visibleWhenMode') as RowVisibilityMode;
+  if (!mode || mode === 'always') return null;
+
+  const rule: RowVisibilityRule = {
+    mode,
+    field: unwrap('visibleWhenField'),
+    value: unwrap('visibleWhenValue')
+  };
+
+  // Carried only when actually set. A rule authored before these keys existed
+  // therefore reads back as the same three-key object it always did.
+  if (unwrap('visibleWhenCompareTo') === 'field') rule.compareTo = 'field';
+
+  const threshold = unwrap('visibleWhenThreshold', true).trim();
+  if (threshold) rule.threshold = threshold;
+
+  return rule;
+};
+
+/**
+ * The second operand: the literal the designer typed, or another field on the
+ * same row. "Previous price is higher than the current price" names two fields
+ * and no constant, so a rule that can only hold one path cannot state it.
+ */
+const readOperand = (rule: RowVisibilityRule, item: unknown): unknown => {
+  if (rule.compareTo !== 'field') return rule.value;
+
+  const path = (rule.value || '').trim();
+  return path ? readPath(item, path) : undefined;
+};
+
+/**
+ * Ordering and percentage forms. Both sides go through the shared money parser
+ * so the fields these rules actually name work: a listing row publishes
+ * `price` / `previousPrice` already formatted ("1.299,90 TL"), which `Number()`
+ * reads as NaN.
+ *
+ * A side that is not a number refuses the comparison and hides the element.
+ * Coercing instead would turn '' and `false` into 0 and switch rows *on* —
+ * a caption claiming a discount nobody has is worse than a missing caption.
+ */
+const compareNumbers = (
+  mode: RowVisibilityMode,
+  left: unknown,
+  right: unknown,
+  threshold: number
+): boolean => {
+  const a = parseAmount(left);
+  const b = parseAmount(right);
+
+  if (a === null || b === null) return false;
+
+  switch (mode) {
+    case 'greater-than':
+      return a > b;
+    case 'greater-or-equal':
+      return a >= b;
+    case 'less-than':
+      return a < b;
+    case 'less-or-equal':
+      return a <= b;
+    default:
+      break;
+  }
+
+  // Percent forms: "at least N% above/below the other side", measured against
+  // that other side. Nothing is a percentage of zero.
+  if (b === 0) return false;
+
+  // The gap signed in the direction the mode names, so `percent-below` reads
+  // its own axis rather than a negated one.
+  const direction = mode === 'percent-above' ? 1 : -1;
+  const gap = ((a - b) / Math.abs(b)) * 100 * direction;
+
+  // `> 0` is what makes "by any amount" mean a real gap. Without it equality —
+  // the full-price row commerce sends as retail_price === price — produces a
+  // gap of 0, which clears an empty (0) threshold in *both* directions at once
+  // and prints a discount caption on a product that has no discount. A gap of
+  // zero is neither above nor below, so both directions must refuse it.
+  return gap > 0 && gap >= threshold;
+};
+
+/**
+ * True when the element should render for this item. An unset or unparseable
+ * rule always returns true: a misconfigured condition must never silently
+ * empty a page.
+ */
+export const isVisibleForItem = (
+  rule: RowVisibilityRule | null,
+  // `unknown` because a repeat can be drawn over a list of plain values, where
+  // the row is a string or a number rather than a record.
+  item: unknown
+): boolean => {
+  if (!rule || !rule.mode || rule.mode === 'always') return true;
+
+  const field = (rule.field || '').trim();
+  if (!field) return true;
+
+  const resolved = readPath(item, field);
+
+  switch (rule.mode) {
+    case 'not-empty':
+      return !isEmptyValue(resolved);
+    case 'empty':
+      return isEmptyValue(resolved);
+    case 'truthy':
+      return Boolean(resolved) && resolved !== 'false' && resolved !== '0';
+    case 'falsy':
+      return !resolved || resolved === 'false' || resolved === '0';
+    // `readOperand` returns `rule.value` untouched unless the rule opted into
+    // a field operand, so the string coercion these two rely on is unchanged.
+    case 'equals':
+      return String(resolved ?? '') === String(readOperand(rule, item) ?? '');
+    case 'not-equals':
+      return String(resolved ?? '') !== String(readOperand(rule, item) ?? '');
+    case 'greater-than':
+    case 'greater-or-equal':
+    case 'less-than':
+    case 'less-or-equal':
+    case 'percent-above':
+    case 'percent-below': {
+      // No second operand yet is a half-authored rule, not a failing item:
+      // treated like any other unusable rule, it shows the element.
+      if (!(rule.value || '').trim()) return true;
+
+      // The threshold belongs to the percent forms alone. The panel stops
+      // rendering the box when the mode is switched away from one, but the
+      // stored property survives the switch, so an ordering rule can still be
+      // carrying a stale one — reading it here would let that stale value
+      // decide a comparison that never uses it.
+      const isPercent =
+        rule.mode === 'percent-above' || rule.mode === 'percent-below';
+      const parsedThreshold = isPercent
+        ? parseAmount((rule.threshold || '').trim())
+        : null;
+
+      // An unreadable box means "any difference", not "every row". Showing the
+      // element instead would hand the percent forms a second door onto the
+      // row the `> 0` floor exists to refuse: a full-price product would print
+      // a discount caption in both directions at once, which is exactly what a
+      // threshold nobody can read must not be able to buy. Rows with a real
+      // gap still show, so a mistyped box never empties the page.
+      const threshold = parsedThreshold ?? 0;
+
+      return compareNumbers(
+        rule.mode,
+        resolved,
+        readOperand(rule, item),
+        threshold
+      );
+    }
+    default:
+      return true;
+  }
+};