@ikas/bp-storefront 1.4.0-beta.61 → 1.4.0-beta.62

package/dist/storefront-config/src/theme-globals.d.ts

@@ -18,7 +18,14 @@ export type ThemeSetting = {
     /** Human-facing label. */
     displayName: string;
     type: GlobalVariableType;
-    /** Concrete value (string/number/boolean for primitives, object/null for IMAGE/BORDER/SHADOW). */
+    /**
+     * Concrete value, discriminated by `type`:
+     * - TEXT/RICH_TEXT → string · NUMBER → number · BOOLEAN → boolean · COLOR → hex string.
+     * - IMAGE → an IkasImage REFERENCE, e.g. `{ id: "theme-images/<uuid>" }`. It has NO
+     *   `.url` field — resolve to a URL with `getDefaultSrc(value)` / `getSrc(value, size)`
+     *   from `@ikas/bp-storefront`, never read `value.url`.
+     * - BORDER/SHADOW → object, or `null` when unset.
+     */
     value: any;
 };
 /** A single-value design token (color). `cssVar` resolves the live, scheme-aware value. */
@@ -54,13 +61,22 @@ export type KeyframeToken = {
         point: string;
     }[];
 };
+/**
+ * A color palette (one entry of `getThemeColorSchemes().values`). Its colors live in
+ * `colorsByScheme` — the top-level `schemes` list holds only slot id→name labels.
+ */
 export type ColorSchemeToken = {
     id: string;
     name: string;
     isDefault: boolean;
     /** Class selector to activate this scheme value, e.g. `_<id>`. */
     className: string;
-    /** Per-scheme color overrides, keyed by color-scheme id. */
+    /**
+     * This palette's colors, keyed by color-SLOT id (the ids in
+     * `getThemeColorSchemes().schemes`). THIS — not the top-level `schemes` array — is
+     * the source of truth for swatch colors; iterate it to render a palette. Prefer
+     * `cssVar` for live, in-editor reactivity; `resolved` is a render-time snapshot.
+     */
     colorsByScheme: Record<string, {
         resolved: string | null;
         cssVar: string;

package/dist/theme/settings/index.d.ts

@@ -11,6 +11,9 @@ export declare function getThemeSettings(): ThemeSetting[];
  * A single global variable by its stable key (`variableName`, e.g. `_6Q0KV7VGGM`).
  * Discover keys via {@link getThemeSettings} (each item carries a human `displayName`).
  * The returned `value` is the live blueprint value when available, else the default.
+ * Its shape is discriminated by `type` (see {@link ThemeSetting.value}); note an
+ * IMAGE setting's value is an image REFERENCE (no `.url`) — resolve with
+ * `getDefaultSrc`/`getSrc`.
  */
 export declare function getThemeSetting(name: string): ThemeSetting | undefined;
 /** Convenience: the resolved value of a global variable, or `undefined` if not found. */
@@ -23,7 +26,26 @@ export declare function getThemeTypography(): TypographyToken[];
 export declare function getThemeBreakpoints(): BreakpointToken[];
 /** Theme keyframe/transition animations. Use `ref` as the CSS animation name. */
 export declare function getThemeKeyframes(): KeyframeToken[];
-/** Theme color schemes — the available schemes plus per-scheme color values. */
+/**
+ * Theme color schemes (palettes). Returns two PARALLEL lists with different jobs:
+ * - `schemes`: the color SLOTS as `{ id, name }` LABELS only — no colors live here.
+ *   Use it to resolve a slot's display name from its id.
+ * - `values`: the actual palettes. A palette's colors live in its `colorsByScheme`
+ *   map, keyed by slot id → `{ resolved, cssVar }`.
+ *
+ * To render swatches, iterate `values[].colorsByScheme` (the source of truth for
+ * colors), NOT the top-level `schemes` array — `schemes` carries labels only, so
+ * iterating it renders empty. Look up each swatch's label from `schemes` by its
+ * slot-id key:
+ *
+ *   const { schemes, values } = getThemeColorSchemes();
+ *   const slotName = (id: string) => schemes.find(s => s.id === id)?.name ?? id;
+ *   values.forEach(palette =>
+ *     Object.entries(palette.colorsByScheme).forEach(([slotId, { resolved, cssVar }]) => {
+ *       // slotName(slotId) → label, cssVar → live var() ref (prefer this), resolved → hex snapshot
+ *     })
+ *   );
+ */
 export declare function getThemeColorSchemes(): {
     schemes: {
         id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikas/bp-storefront",
-  "version": "1.4.0-beta.61",
+  "version": "1.4.0-beta.62",
   "description": "A framework for the ikas blueprint storefronts.",
   "author": "ikas",
   "license": "ISC",