@ikas/bp-storefront 1.4.0-beta.87 → 1.4.0-beta.89

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

@@ -76,6 +76,15 @@ export type KeyframeToken = {
         styles?: StyleEntry[];
     }[];
 };
+/**
+ * A color SLOT — one entry of the top-level `getThemeColorSchemes().schemes` list. It is a
+ * label only (`id` + display `name`); the actual colors for the slot live in each palette's
+ * `colorsByScheme[id]`.
+ */
+export type ColorSchemeSlot = {
+    id: string;
+    name: 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.
@@ -104,13 +113,50 @@ export type ThemeGlobals = {
     breakpoints: BreakpointToken[];
     keyframes: KeyframeToken[];
     colorSchemes: {
-        schemes: {
-            id: string;
-            name: string;
-        }[];
+        schemes: ColorSchemeSlot[];
         values: ColorSchemeToken[];
     };
 };
+/**
+ * Stamps a theme-token type as its RUNTIME view returned by the `@ikas/bp-storefront` getters
+ * (`getThemeColors` / `getThemeTypography` / ...). `name` is removed, then re-added as a
+ * DEPRECATED `never`. Plainly `Omit`-ing it would only ever surface a bare "Property 'name' does
+ * not exist on type" — re-adding it as a documented `@deprecated never` instead means a developer
+ * who reaches for `.name` at runtime sees the strikethrough + the explanation below on hover, and
+ * any actual use of the value is a type error (`never`). The agent is steered the same way.
+ *
+ * The full types above (with a real `name: string`) are still produced in the serialized
+ * {@link ThemeGlobals} payload and surfaced by the CLI/MCP `list-theme-globals` AUTHORING read, so
+ * the agent/editor can still discover and reuse existing tokens by name. `name` is hidden ONLY at
+ * the runtime getter return types (the getters cast the live payload to these views).
+ */
+type RuntimeView<T> = Omit<T, "name"> & {
+    /**
+     * @deprecated `name` is authoring-only and is NOT exposed at runtime. Identify this token by its
+     * STABLE `id` instead — color → `cssVar` (`var(--<id>)`), typography & keyframe → `className` /
+     * `ref` (`_<id>`), color-scheme slot → a `colorsByScheme` key. Token names are non-unique (two
+     * design assets can ship the same name) and renaming one must not break references, so matching
+     * by name is unsafe. Need a human-readable label? Read it from `list_theme_globals` (MCP/CLI) or
+     * the editor's Styles panel — not from the runtime getters.
+     */
+    name?: never;
+};
+export type RuntimeDesignToken = RuntimeView<DesignToken>;
+export type RuntimeTypographyToken = RuntimeView<TypographyToken>;
+export type RuntimeBreakpointToken = RuntimeView<BreakpointToken>;
+export type RuntimeKeyframeToken = RuntimeView<KeyframeToken>;
+export type RuntimeColorSchemeToken = RuntimeView<ColorSchemeToken>;
+export type RuntimeColorSchemeSlot = RuntimeView<ColorSchemeSlot>;
+/**
+ * Runtime view of {@link ThemeGlobals.colorSchemes} (returned by `getThemeColorSchemes`). The
+ * slot list carries only `{ id }`: slot display LABELS (the slot `name`) are authoring-only —
+ * read them via the CLI/MCP `list-theme-globals` or the editor, not at runtime. Render a palette
+ * by iterating each value's `colorsByScheme`, keyed by slot id.
+ */
+export type RuntimeThemeColorSchemes = {
+    schemes: RuntimeColorSchemeSlot[];
+    values: RuntimeColorSchemeToken[];
+};
 export declare const EMPTY_THEME_GLOBALS: ThemeGlobals;
 type StyleValueLike = {
     value?: any;

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

@@ -1,4 +1,4 @@
-import { BreakpointToken, ColorSchemeToken, DesignToken, KeyframeToken, ThemeSetting, TypographyToken } from "../../storefront-config/src";
+import { RuntimeBreakpointToken, RuntimeDesignToken, RuntimeKeyframeToken, RuntimeThemeColorSchemes, RuntimeTypographyToken, ThemeSetting } from "../../storefront-config/src";
 /**
  * Register the live global-variable object (`_g_`) so `getThemeSetting`/`getThemeSettings`
  * return actual runtime values (constants, computed getters, and in-editor edits) instead
@@ -19,37 +19,30 @@ export declare function getThemeSetting(name: string): ThemeSetting | undefined;
 /** Convenience: the resolved value of a global variable, or `undefined` if not found. */
 export declare function getThemeSettingValue(name: string): any;
 /** Theme color tokens. Each carries a resolved value and a `var(--id)` CSS reference. */
-export declare function getThemeColors(): DesignToken[];
+export declare function getThemeColors(): RuntimeDesignToken[];
 /** Theme typography tokens (text styles). Apply `className` or read `resolved` CSS values. */
-export declare function getThemeTypography(): TypographyToken[];
-/** Theme responsive breakpoints (`{ id, name, width }`). */
-export declare function getThemeBreakpoints(): BreakpointToken[];
+export declare function getThemeTypography(): RuntimeTypographyToken[];
+/** Theme responsive breakpoints (`{ id, width }`). */
+export declare function getThemeBreakpoints(): RuntimeBreakpointToken[];
 /** Theme keyframe/transition animations. Use `ref` as the CSS animation name. */
-export declare function getThemeKeyframes(): KeyframeToken[];
+export declare function getThemeKeyframes(): RuntimeKeyframeToken[];
 /**
  * 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.
+ * - `schemes`: the color SLOTS as `{ id }` only — no colors and no display label live here at
+ *   runtime. A slot's human name is authoring-only (read it via the CLI/MCP `list-theme-globals`
+ *   or the editor); at runtime identify a slot solely by 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:
+ * colors), NOT the top-level `schemes` array — `schemes` carries slot ids only, so
+ * iterating it renders empty:
  *
- *   const { schemes, values } = getThemeColorSchemes();
- *   const slotName = (id: string) => schemes.find(s => s.id === id)?.name ?? id;
+ *   const { values } = getThemeColorSchemes();
  *   values.forEach(palette =>
  *     Object.entries(palette.colorsByScheme).forEach(([slotId, { resolved, cssVar }]) => {
- *       // slotName(slotId) → label, cssVar → live var() ref (prefer this), resolved → hex snapshot
+ *       // slotId → stable slot key, cssVar → live var() ref (prefer this), resolved → hex snapshot
  *     })
  *   );
  */
-export declare function getThemeColorSchemes(): {
-    schemes: {
-        id: string;
-        name: string;
-    }[];
-    values: ColorSchemeToken[];
-};
+export declare function getThemeColorSchemes(): RuntimeThemeColorSchemes;

package/package.json

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