@usequeek/theme-kit 0.1.25 → 0.1.26

package/client.ts

@@ -57,6 +57,7 @@ export * from './stores/location-store';
 export * from './stores/address-modal-store';
 export * from './stores/auth-modal-store';
 export * from './stores/cart-store';
+export * from './stores/line-text-store';
 
 // Mounting a theme — the piece a theme developer cannot build without.
 export * from './theme-mount';

package/components/cart/default-cart-shell.tsx

@@ -11,6 +11,7 @@ import { useRelatedProducts } from '../../hooks/use-related-products';
 import { useCart } from '../../hooks/use-cart';
 import { formatMoney } from '../../utils/format';
 import { productRequiresVariant } from '../../utils/match-variant';
+import { visibleLineProperties } from '../../utils/line-properties';
 import { Image } from '../image';
 
 /**
@@ -76,6 +77,9 @@ export function DefaultCartShell({
                   )}
                   <div className="core-cart-page__item-info">
                     <span className="core-cart-page__item-title">{item.title}</span>
+                    {visibleLineProperties(item).map((row) => (
+                      <span key={row.key} className="core-cart-page__item-price">{`${row.label}: ${row.value}`}</span>
+                    ))}
                     <span className="core-cart-page__item-price">{t('cart.item.each', { price: formatMoney(item.unit_price, currency) })}</span>
                   </div>
                   <div className="core-cart-page__item-qty">

package/index.ts

@@ -42,6 +42,7 @@ export * from './utils/contact-location';
 export * from './utils/benefit-icon';
 export * from './utils/video-embed';
 export * from './utils/match-variant';
+export * from './utils/line-properties';
 export * from './utils/announcement';
 export * from './utils/locale';
 export * from './utils/locale-switch';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "private": false,
   "license": "MIT",
   "description": "The runtime a Queek storefront theme is built on: hooks, stores, page renderer, navigation, shared blocks and locale strings.",

package/stores/cart-store.ts

@@ -9,6 +9,8 @@ import { normalizeCurrencyCode, PLATFORM_DEFAULT_CURRENCY } from '../utils/forma
 import { pushAddToCart } from '../apps/analytics-events';
 import { getActivePlatform, platformScopedStorage } from '../sdk/platform';
 import { productRequiresVariant } from '../utils/match-variant';
+import { readLineText } from './line-text-store';
+import { isBlankText } from '../utils/blank-text';
 
 interface CartState {
   items: CartItem[];
@@ -38,14 +40,57 @@ interface CartState {
  * unchanged (existing localStorage carts, in-flight server carts) rather than
  * reshaping ids for products that were never affected by this gap.
  */
-export function makeItemId(productId: string, addons: CartAddon[], variantId?: string | null): string {
+export function makeItemId(
+  productId: string,
+  addons: CartAddon[],
+  variantId?: string | null,
+  properties?: Record<string, unknown> | null,
+): string {
   const base = variantId ? `${productId}::${variantId}` : productId;
+  const withAddons = addons.length === 0 ? base : `${base}-${addons.map((addon) => addon.item_id).sort().join(',')}`;
+  const suffix = propertiesSuffix(properties);
 
-  if (addons.length === 0) {
-    return base;
+  return suffix === '' ? withAddons : `${withAddons}${suffix}`;
+}
+
+/** FNV-1a (32 bit) over the UTF-8 bytes of `text`, as 8 hex digits. */
+function fnv1a(text: string, seed: number): string {
+  let hash = seed >>> 0;
+
+  for (const byte of new TextEncoder().encode(text)) {
+    hash = Math.imul(hash ^ byte, 0x01000193) >>> 0;
   }
 
-  return `${base}-${addons.map((addon) => addon.item_id).sort().join(',')}`;
+  return hash.toString(16).padStart(8, '0');
+}
+
+/**
+ * `~p-` plus 12 hex digits over the canonical JSON (keys sorted) of the
+ * non-blank string values, or an empty string when there are none, so a line
+ * without text keeps the id it has always had. Callers pass labelled keys only.
+ */
+function propertiesSuffix(properties?: Record<string, unknown> | null): string {
+  if (!properties) {
+    return '';
+  }
+
+  const canonical: Record<string, string> = {};
+
+  for (const key of Object.keys(properties).sort()) {
+    const value = properties[key];
+
+    if (typeof value === 'string' && !isBlankText(value)) {
+      canonical[key] = value;
+    }
+  }
+
+  if (Object.keys(canonical).length === 0) {
+    return '';
+  }
+
+  const json = JSON.stringify(canonical);
+
+  return `~p-${(fnv1a(json, 0x811c9dc5) + fnv1a(json, 0x9e3779b9)).slice(0, 12)}`;
 }
 
 /**
@@ -77,7 +122,20 @@ export const useCartStore = create<CartState>()(
           return;
         }
 
-        const itemId = makeItemId(product.id, addons, variant?.id);
+        // Text an app asked for on this product. A product with nothing
+        // registered reads as empty, which is the behaviour of a kit without line text.
+        const lineText = readLineText(product.shop_id, product.id);
+
+        if (lineText.missingRequired.length > 0) {
+          const missing = lineText.missingRequired[0];
+
+          toast({ title: `Add your ${missing.label} before adding to cart` });
+          console.error('[cart] refused a product added without its required line text:', product.id, missing.key);
+          return;
+        }
+
+        const hasLineText = Object.keys(lineText.properties).length > 0;
+        const itemId = makeItemId(product.id, addons, variant?.id, hasLineText ? lineText.properties : null);
         const addonTotal = addons.reduce((sum, addon) => sum + addon.price, 0);
         // A variant's own price/stock override the base product's — the same
         // precedence the quick-add flow uses.
@@ -133,6 +191,7 @@ export const useCartStore = create<CartState>()(
                 addons,
                 variant_id: variant?.id ?? null,
                 variant_title: variant?.title ?? null,
+                ...(hasLineText ? { properties: lineText.properties, property_labels: lineText.labels } : {}),
               },
             ],
           };

package/stores/line-text-store.ts

@@ -0,0 +1,230 @@
+'use client';
+
+import { create } from 'zustand';
+import { isBlankText } from '../utils/blank-text';
+
+/** The longest text a line field may carry. Mirrors the platform limit. */
+export const LINE_TEXT_MAX_LENGTH = 500;
+/** Used when a registered field declares no usable `maxLength`. */
+export const LINE_TEXT_DEFAULT_MAX_LENGTH = 100;
+
+/** One text field an app asks the shopper to fill for a product line. */
+export interface LineTextField {
+  /** The full line property key, e.g. `app.engraving.text`. */
+  key: string;
+  /** The label the shopper sees, e.g. `Engraving text`. */
+  label: string;
+  required: boolean;
+  maxLength: number;
+}
+
+/** One live registration: what one block or app declared for a product. */
+interface LineTextRegistration {
+  /** Identity of this registration; its unregister removes exactly this one. */
+  id: object;
+  /** Optional caller-chosen name: registering again under it replaces its earlier registration. */
+  owner: string | null;
+  fields: LineTextField[];
+}
+
+interface LineTextEntry {
+  /** Every live registration for the product, oldest first. */
+  registrations: LineTextRegistration[];
+  /** What the shopper typed, by field key. */
+  values: Record<string, string>;
+}
+
+interface LineTextState {
+  /** Keyed by `lineTextKey(shopId, productId)`. Never persisted. */
+  entries: Record<string, LineTextEntry>;
+  /**
+   * Declares the fields a product page renders. Call it only from an effect and
+   * only for fields that are on screen; the returned function removes this
+   * registration only and is meant as the effect cleanup. Several registrations
+   * can be live for one product (two apps, or one block in two places): the
+   * product's fields are their union, and when two declare the same key the most
+   * recent declaration wins. Typed values are kept for every key that is still
+   * declared. Pass `owner` to make a later call with the same name replace this
+   * registration instead of adding another.
+   */
+  registerLineText: (shopId: string, productId: string, fields: LineTextField[], owner?: string) => () => void;
+  /** Stores what the shopper typed. The text is cleaned when it is read, not here. */
+  setLineText: (shopId: string, productId: string, key: string, value: string) => void;
+  /** Empties the typed values of a product and keeps every live registration. */
+  clearLineText: (shopId: string, productId: string) => void;
+}
+
+/** The text a line carries once cleaned, ready to write on a cart line. */
+export interface ReadLineText {
+  /** Non-blank cleaned values, keys sorted ascending. */
+  properties: Record<string, string>;
+  /** `{ key: label }` for exactly the keys in `properties`. */
+  labels: Record<string, string>;
+  /** Required fields whose cleaned value is blank, in key order. */
+  missingRequired: LineTextField[];
+}
+
+export function lineTextKey(shopId: string, productId: string): string {
+  return `${shopId}:${productId}`;
+}
+
+// Control characters, line and paragraph separators, and bidirectional overrides.
+const UNSAFE_CHARACTERS = /[\u0000-\u001F\u007F-\u009F\u2028\u2029\u202A-\u202E\u2066-\u2069]/g;
+
+function effectiveMaxLength(maxLength: number): number {
+  if (!Number.isInteger(maxLength) || maxLength <= 0) {
+    return LINE_TEXT_DEFAULT_MAX_LENGTH;
+  }
+
+  return Math.min(maxLength, LINE_TEXT_MAX_LENGTH);
+}
+
+function cleanValue(raw: unknown, maxLength: number): string {
+  if (typeof raw !== 'string') {
+    return '';
+  }
+
+  // Cut before deciding blank, so invisible leading characters cannot hide that
+  // the text kept nothing visible. Ordinary surrounding whitespace is trimmed first
+  // so it does not use up the length budget.
+  const cut = Array.from(raw.replace(UNSAFE_CHARACTERS, '').trim())
+    .slice(0, effectiveMaxLength(maxLength))
+    .join('')
+    .trimEnd();
+
+  return isBlankText(cut) ? '' : cut;
+}
+
+/** The product's fields: the union of its live registrations, the latest declaration of a key winning. */
+function effectiveFields(registrations: LineTextRegistration[]): LineTextField[] {
+  const byKey = new Map<string, LineTextField>();
+
+  for (const registration of registrations) {
+    for (const field of registration.fields) {
+      byKey.set(field.key, field);
+    }
+  }
+
+  return [...byKey.values()];
+}
+
+/** The entry for these registrations, keeping only the values of keys still declared; null when none are live. */
+function entryFor(registrations: LineTextRegistration[], values: Record<string, string>): LineTextEntry | null {
+  if (registrations.length === 0) {
+    return null;
+  }
+
+  const kept: Record<string, string> = {};
+
+  for (const field of effectiveFields(registrations)) {
+    if (typeof values[field.key] === 'string') {
+      kept[field.key] = values[field.key];
+    }
+  }
+
+  return { registrations, values: kept };
+}
+
+function withEntry(
+  entries: Record<string, LineTextEntry>,
+  entryKey: string,
+  entry: LineTextEntry | null,
+): Record<string, LineTextEntry> {
+  const { [entryKey]: removed, ...rest } = entries;
+
+  return entry === null ? rest : { ...rest, [entryKey]: entry };
+}
+
+/**
+ * ONE store for what a shopper typed into app-declared line text fields. It is
+ * deliberately not persisted: a reload starts empty, and only the cart lines
+ * (which already carry the text) are kept.
+ */
+export const useLineTextStore = create<LineTextState>()((set, get) => ({
+  entries: {},
+  registerLineText: (shopId, productId, fields, owner) => {
+    const entryKey = lineTextKey(shopId, productId);
+    const registration: LineTextRegistration = {
+      id: {},
+      owner: owner ?? null,
+      fields: fields.filter((field) => typeof field.key === 'string' && field.key.trim() !== ''),
+    };
+
+    set((state) => {
+      const previous = state.entries[entryKey];
+      const live = (previous?.registrations ?? []).filter((entry) => owner == null || entry.owner !== owner);
+
+      return { entries: withEntry(state.entries, entryKey, entryFor([...live, registration], previous?.values ?? {})) };
+    });
+
+    return () => {
+      set((state) => {
+        const previous = state.entries[entryKey];
+
+        if (!previous || !previous.registrations.some((entry) => entry.id === registration.id)) {
+          return state;
+        }
+
+        const live = previous.registrations.filter((entry) => entry.id !== registration.id);
+
+        return { entries: withEntry(state.entries, entryKey, entryFor(live, previous.values)) };
+      });
+    };
+  },
+  setLineText: (shopId, productId, key, value) => {
+    const entryKey = lineTextKey(shopId, productId);
+    const entry = get().entries[entryKey];
+
+    if (!entry || !effectiveFields(entry.registrations).some((field) => field.key === key)) {
+      return;
+    }
+
+    set((state) => ({
+      entries: { ...state.entries, [entryKey]: { ...entry, values: { ...entry.values, [key]: value } } },
+    }));
+  },
+  clearLineText: (shopId, productId) => {
+    const entryKey = lineTextKey(shopId, productId);
+    const entry = get().entries[entryKey];
+
+    if (!entry || Object.keys(entry.values).length === 0) {
+      return;
+    }
+
+    set((state) => ({ entries: { ...state.entries, [entryKey]: { ...entry, values: {} } } }));
+  },
+}));
+
+/**
+ * The cleaned text for a product line: trimmed, control characters stripped and
+ * cut to each field's `maxLength` in code points. A product with nothing
+ * registered gives empty results, which is the behaviour of a kit with no line
+ * text at all.
+ */
+export function readLineText(shopId: string, productId: string): ReadLineText {
+  const entry = useLineTextStore.getState().entries[lineTextKey(shopId, productId)];
+  const result: ReadLineText = { properties: {}, labels: {}, missingRequired: [] };
+
+  if (!entry) {
+    return result;
+  }
+
+  const fields = effectiveFields(entry.registrations).sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+
+  for (const field of fields) {
+    const value = cleanValue(entry.values[field.key], field.maxLength);
+
+    if (value === '') {
+      if (field.required) {
+        result.missingRequired.push(field);
+      }
+
+      continue;
+    }
+
+    result.properties[field.key] = value;
+    result.labels[field.key] = field.label;
+  }
+
+  return result;
+}

package/types/cart.ts

@@ -18,4 +18,15 @@ export interface CartItem {
   variant_id?: string | null;
   /** e.g. "Denim" — the selected variant's display name, when this line has one. */
   variant_title?: string | null;
+  /**
+   * Text the shopper typed for an app-declared line field, `{ key: text }` with
+   * keys in ascending order. Absent on a line with no such text.
+   */
+  properties?: Record<string, unknown>;
+  /**
+   * `{ key: label }` for the declared keys in `properties`. A key without a label
+   * is never shown to the shopper. Kept on the line only; the kit never sends it
+   * to a server.
+   */
+  property_labels?: Record<string, string>;
 }

package/utils/blank-text.ts

@@ -0,0 +1,14 @@
+/**
+ * Whether text is blank: empty, or made only of whitespace, separator and format
+ * characters (zero-width spaces and joiners, directional marks, the word joiner,
+ * the byte order mark, the soft hyphen, tag characters). Matches the server's
+ * whitespace, separator and format-character rule. Internal: not part of the
+ * public barrels. It only classifies text and never edits it: any character
+ * outside that class (letters, digits, punctuation, emoji) makes the text
+ * non-blank, and emoji sequences that use a zero-width joiner stay intact.
+ */
+const BLANK_CHARACTERS = new RegExp('[\\s\\p{Cf}]', 'gu');
+
+export function isBlankText(text: unknown): boolean {
+  return typeof text !== 'string' || text.replace(BLANK_CHARACTERS, '') === '';
+}

package/utils/line-properties.ts

@@ -0,0 +1,62 @@
+import { isBlankText } from './blank-text';
+
+/**
+ * Key endings that carry a bearer link or token, dot-prefixed so a derived key
+ * `app.<ns>.<field key>` ends in one only when the field key is exactly `claim`,
+ * `reschedule_url` or `cancel_url`. Parity constant: keep it equal to the
+ * platform list. Internal: not part of the public barrels.
+ */
+const BEARER_PROPERTY_SUFFIXES = ['.claim', '.reschedule_url', '.cancel_url'] as const;
+
+export interface LineProperty {
+  key: string;
+  label: string;
+  value: string;
+}
+
+interface LinePropertiesSource {
+  properties?: Record<string, unknown> | null;
+  property_labels?: Record<string, unknown> | null;
+}
+
+/**
+ * The text a shopper typed on a line, as rows ready to render: only keys that
+ * carry a declared label, with a non-blank string value, sorted by key. A key
+ * without a label, a bearer key, a blank value and a non-string value never
+ * appear, so a line from any source shows nothing it was not declared to show.
+ * Render `label` and `value` as text.
+ *
+ * @example
+ * visibleLineProperties(item).map(({ key, label, value }) => <p key={key}>{label}: {value}</p>)
+ */
+export function visibleLineProperties(source: LinePropertiesSource): LineProperty[] {
+  const properties = source.properties;
+  const labels = source.property_labels;
+
+  if (!properties || !labels) {
+    return [];
+  }
+
+  const rows: LineProperty[] = [];
+
+  for (const key of Object.keys(properties).sort()) {
+    const value = properties[key];
+    const label = labels[key];
+
+    if (typeof value !== 'string' || isBlankText(value)) {
+      continue;
+    }
+
+    if (typeof label !== 'string' || isBlankText(label)) {
+      continue;
+    }
+
+    if (BEARER_PROPERTY_SUFFIXES.some((suffix) => key.endsWith(suffix))) {
+      continue;
+    }
+
+    rows.push({ key, label, value });
+  }
+
+  return rows;
+}