@wix/web5-core 1.61.0 → 1.62.0

package/dist/types/theme/tokenContract.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The theme-token contract (DL #193).
+ *
+ * One home for the answer to "who is allowed to set this token, and who wins
+ * when more than one of them does". Three things need that answer and must not
+ * each keep their own copy:
+ *
+ *   - **`applyThemeOverrides`** decides, per key, whether to write the real
+ *     token or its `--web5-host-*` alias.
+ *   - **the seed's `validate-templates`** fails a template that sets a brand
+ *     token.
+ *   - **the shop owner's panel** renders a control per `editable` entry.
+ *
+ * A leaf module beside `hostScope.ts`, and for the same reason: both are data
+ * that several packages must agree on, and both have to be readable from plain
+ * Node tooling. Requiring this package's ENTRY from Node fails — the CSS import
+ * in it is a syntax error to the CJS loader, which is what `scope-css.ts`
+ * documents — but a deep import of a leaf like this one works, so the seed's
+ * validator can read it without loading a component library.
+ *
+ * It was briefly its own package. That was justified by `embed-loader` needing
+ * the list without taking core's eleven dependencies — and the loader turned
+ * out not to need it at all, because `applyThemeOverrides` has owned runtime
+ * token injection here since DL #131.
+ *
+ * ## The two buckets
+ *
+ * The split is about who WINS, not about what may be imported. A platform
+ * adapter is free to read anything the store states; the bucket decides what
+ * happens when a template has an opinion about the same token.
+ *
+ * - `brand` — the store's identity: colour roles and font families. The
+ *   imported value is written as the real token, last, so it wins
+ *   unconditionally. A template is not permitted to set these.
+ * - `host`  — the store's shape: corner radius today. The imported value is
+ *   written as `--web5-host-<name>` and consumed by core as a `var()`
+ *   fallback, so a template stating the real token beats it and a template
+ *   that stays silent inherits the store's.
+ *
+ * A token absent from this map is treated as `host`. That is deliberate and
+ * safe: an alias nothing consumes renders nothing, so an adapter that learns
+ * to read a token core has never heard of cannot override a template by
+ * accident. The wiring line in core is the real gate for a host token, not the
+ * entry here.
+ *
+ * ## Why all but one are brand
+ *
+ * This is not a new taxonomy. Twenty of these are the set
+ * `web50-shopify-adapter` already emits, with a bucket attached; the
+ * twenty-first, `--heading`, has been in core's catalogue since DL #131 and is
+ * consumed by the seed, but no adapter fills it yet. Exactly one token changes
+ * hands relative to the behaviour before DL #193 — `--radius`, which used to
+ * win against the template that had chosen a different one. That single
+ * misfiling is the whole of the bug this contract exists to fix.
+ */
+/** How a value is spelled, which is what makes validation possible. */
+export type TokenType = 
+/** An HSL triplet with no `hsl()` wrapper — `0 0% 9%`. The core bridge wraps it. */
+'color-hsl'
+/** A CSS font stack — `'Poppins', ui-sans-serif, sans-serif`. */
+ | 'font-stack'
+/** A CSS length. MUST carry a unit: a bare `0` turns `calc(var(--radius) - 4px)`
+ *  into a type error and takes the derived radius scale out entirely. */
+ | 'length';
+/** Which layer wins when both a store and a template state this token. */
+export type TokenBucket = 'brand' | 'host';
+export interface TokenContractEntry {
+    bucket: TokenBucket;
+    type: TokenType;
+    /** May the shop owner set this from the panel? */
+    editable: boolean;
+    /** Shown in the owner's panel. Absent for entries that are not editable. */
+    label?: string;
+}
+/**
+ * Every token a platform adapter may meaningfully emit today.
+ *
+ * Growth is adapter-driven on purpose: a token joins when an adapter can
+ * actually read it, not on spec. `theme_overrides` is capped at 32 entries by
+ * its proto, so there are twelve slots left and no reason to spend them on
+ * speculation. `--spacing` is the tempting next one and should be resisted —
+ * it scales every `p-*`, `m-*` and `gap-*` in the bundle from one number.
+ */
+export declare const THEME_TOKEN_CONTRACT: Readonly<Record<string, TokenContractEntry>>;
+/**
+ * The tokens written directly, which is the only question the loader has to
+ * answer per key — everything else takes the alias path.
+ */
+export declare const BRAND_TOKENS: ReadonlySet<string>;
+/**
+ * A token name we are willing to compose into a CSS declaration.
+ *
+ * The keys reaching the loader came out of a backend map, which came out of an
+ * adapter reading a merchant's theme file. A key carrying `:` or `;` would
+ * write arbitrary declarations onto the mount, so the shape is checked where
+ * the declaration is built rather than trusted from the source.
+ */
+export declare const TOKEN_NAME_PATTERN: RegExp;
+/** `--radius` → `--web5-host-radius`. Derived, never stored: one fewer thing to get wrong. */
+export declare function hostAliasFor(token: string): string;
+/** Whether this token is written directly (brand) or as an alias (host, and anything unknown). */
+export declare function bucketOf(token: string): TokenBucket;
+//# sourceMappingURL=tokenContract.d.ts.map

package/dist/types/theme/tokenContract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenContract.d.ts","sourceRoot":"","sources":["../../../src/theme/tokenContract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,uEAAuE;AACvE,MAAM,MAAM,SAAS;AACnB,oFAAoF;AAClF,WAAW;AACb,iEAAiE;GAC/D,YAAY;AACd;yEACyE;GACvE,QAAQ,CAAC;AAEb,0EAA0E;AAC1E,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3C,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AASD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CA8C1E,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,CAMrB,CAAC;AAEzB;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,QAAmB,CAAC;AAEnD,8FAA8F;AAC9F,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,kGAAkG;AAClG,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAEnD"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wix/web5-core",
   "license": "MIT",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "author": {
     "name": "tsachis",
     "email": "tsachis@wix.com"
@@ -100,5 +100,5 @@
   "wallaby": {
     "autoDetect": true
   },
-  "falconPackageHash": "9694f910a3ae343f13fc3432bb04b42ad38df91bfab9b5288fddc2e6"
+  "falconPackageHash": "6796550854d3a51bfecb2ebb957ef475051e33aae7c4e8f71812d718"
 }

package/src/styles/base-tokens.css

@@ -36,7 +36,14 @@
   --font-display: var(--font-sans);
 
   /* Spacing & shape tokens */
-  --radius: 0.5rem;
+  /* Shape follows the host page unless a template states its own (DL #193).
+   * `embed-loader` writes `--web5-host-radius` from the store's imported theme;
+   * a template declaring `--radius` outright beats this fallback, and with
+   * neither present the seed default applies exactly as before. The whole
+   * derived scale rides on it — `--radius-sm/md/lg/xl` in tailwind-theme.css
+   * are live `var()`/`calc()` references, so one value reaches all 48
+   * `rounded-*` call sites. */
+  --radius: var(--web5-host-radius, 0.5rem);
   --tracking-normal: -0.02em;
   --spacing: 0.25rem;