@usequeek/theme-kit 0.1.25 → 0.1.27

package/README.md

@@ -480,7 +480,7 @@ store's languages.
 | Prop | Default | |
 | --- | --- | --- |
 | `className` | | Extra class on the root, to position or restyle it. |
-| `variant` | `'select'` | `'menu'`: a trigger button and a list of language links (below). `'inline-list'`: a link per language that wraps on narrow screens. `'select'`: one native dropdown, **legacy** — it works and is unchanged, but its open list is the operating system's menu and cannot be styled; prefer `menu`. |
+| `variant` | `'select'` | `'menu'`: a trigger button and a list of language links (below). `'inline-list'`: a link per language that wraps on narrow screens. `'select'`: one native dropdown, **legacy** — it works, but its open list is the operating system's menu and cannot be styled; prefer `menu`. |
 | `side` | `'bottom'` | `menu` only. `'top'` opens above the trigger, for footers. Flips by itself when the preferred side does not fit. |
 | `align` | `'end'` | `menu` only. Line the popover up with the trigger's inline `'end'` or `'start'` edge (mirrors in right-to-left). Flips and shifts to stay inside the viewport. |
 | `showNativeName` | `true` | Label languages in their own language (`Français`) instead of English (`French`). |
@@ -684,8 +684,8 @@ fails here instead of after publishing.
 ## Versioning
 
 The kit is pre-1.0 (`0.x`). A change to the surface the barrels declare that can
-break a theme ships in a minor version and is listed in
-[CHANGELOG.md](./CHANGELOG.md); patch versions are fixes and additions. Pin a
+break a theme ships in a minor version; patch versions are fixes and
+additions. Pin a
 minor version (`~0.1.23`) if a theme must not move on its own.
 
 ## Release
@@ -694,7 +694,7 @@ Publishing runs on tags via `.github/workflows/publish.yml`, through npm
 trusted publishing (no stored token), with provenance:
 
 ```bash
-# 1. Bump version in package.json, add the CHANGELOG entry, commit
+# 1. Bump version in package.json, commit
 # 2. Tag and push the tag. The workflow typechecks, tests, runs verify-package,
 #    then `npm publish --provenance --access public`:
 git tag vX.Y.Z
@@ -706,8 +706,7 @@ git push origin main --tags
 Open an issue or a pull request at
 [usequeek/theme-kit](https://github.com/usequeek/theme-kit). Run `npm run typecheck`
 and `npm test` before you push; CI runs both plus `verify-package`. Keep a change
-to the public surface small, documented with a JSDoc `@example`, and recorded in
-the CHANGELOG.
+to the public surface small and documented with a JSDoc `@example`.
 
 ## Security
 

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.27",
   "private": false,
   "license": "MIT",
   "description": "The runtime a Queek storefront theme is built on: hooks, stores, page renderer, navigation, shared blocks and locale strings.",
@@ -41,7 +41,6 @@
     "locales/*.json",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md",
     "!tests",
     "!scripts"
   ],

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;
+}

package/CHANGELOG.md

@@ -1,45 +0,0 @@
-# Changelog
-
-All notable changes to `@usequeek/theme-kit`. See the README for the versioning
-policy. Versions before this file started are in the git tags.
-
-## 0.1.25 - 2026-10-14
-
-### Packaging
-
-- The customer SDK moved to the Queek scope: the peer dependency is now
-  `@usequeek/client-sdk` `^0.4.0` (was `@queekai/client-sdk`, which is deprecated).
-  Install `@usequeek/client-sdk` alongside the kit and remove `@queekai/client-sdk`.
-
-## 0.1.24 - 2026-10-12
-
-### Added
-
-- `ApiRequestError` and `ApiTimeoutError` carry a stable `code` (`unauthenticated`,
-  `forbidden`, `not_found`, `rate_limited`, `client_error`, `server_error`,
-  `timeout`) and a `retryable` flag. `ApiRequestError` also carries `requestId`,
-  `retryAfterSeconds` and `detail`. Their messages say what happened and what to do
-  next, and never include the query string.
-- The fetching hooks (`useProducts`, `useProductBySlug`, `useShop`, `usePosts`,
-  `useReviews`, `useProductQuestions`, `useCategories`, `useRelatedProducts`,
-  `useProductDetail`) return an `error` field (`Error | null`).
-- One warning, in production builds only, when `QUEEK_API_URL` is not set.
-- JSDoc with examples on the hooks, providers, clients, stores and the main
-  components.
-
-### Fixed
-
-- `useProducts` and `useShop` no longer leave an unhandled promise rejection when
-  the request fails.
-- Slugs and ids are URL-encoded when they are placed in a request path
-  (products, collections, related products, questions, orders).
-- Google sign-in no longer logs the sign-in URL or the response body.
-- Hook errors raised outside a provider name the missing provider and the fix.
-
-### Packaging
-
-- The published package no longer contains `tests/` or `scripts/`.
-- Peer dependency `@queekai/client-sdk` is `^0.3.1 || ^0.4.0` (was `*`); `engines.node` is
-  `>=22`; `bugs`, `homepage`, `author` and `keywords` are set; releases publish
-  with npm provenance.
-- The licence names the legal entity, Queekx Technology LTD.