@ikas/code-components-mcp 1.4.0-beta.210 → 1.4.0-beta.213

package/data/framework.json

@@ -645,7 +645,7 @@
     "theme-globals": {
       "title": "Theme Global Settings & Design Tokens",
       "description": "Read and create the theme's global variables and design tokens (colors, typography, breakpoints, keyframes, color schemes) from code components",
-      "content": "The theme developer defines global settings in the editor's \"Styles\" panel. Code components can READ these at runtime and an AI agent can CREATE/LIST them via MCP tools. Prefer reusing the theme's existing tokens (colors, typography) over hardcoding values — it keeps components consistent with the store's design.\n\n### Read at runtime (in your .tsx)\n\nImport from `@ikas/bp-storefront`. These work in SSR, client hydration, and the editor canvas:\n\n```tsx\nimport {\n  getThemeSetting, getThemeSettings,        // global variables (Theme Settings)\n  getThemeColors, getThemeTypography,        // design tokens\n  getThemeBreakpoints, getThemeKeyframes, getThemeColorSchemes,\n} from \"@ikas/bp-storefront\";\n\nconst brand = getThemeSetting(\"_AbC123XyZ\")?.value;   // key = variableName, from list_theme_globals\nconst colors = getThemeColors();                       // [{ id, name, resolved, cssVar }]\n// resolved = concrete value (e.g. \"#ff0000\"); cssVar = \"var(--<id>)\" (scheme-aware).\n// e.g. style={{ color: colors[0].cssVar }} or className={getThemeTypography()[0].className}\n```\n\nShapes: colors → `{ id, name, resolved, cssVar }`; typography → `{ id, name, resolved, className, breakpoints? }`; breakpoints → `{ id, name, width }`; keyframes → `{ id, name, type, ref }`; color schemes → `{ schemes, values }`. Global variables → `{ name, displayName, type, value }` where `name` is the stable runtime key (`variableName`).\n\n### Responsive breakpoints in CSS\n\n`getThemeBreakpoints()` gives you each breakpoint's `width` in JS, but a CSS media query CANNOT use `var()` in its condition (it parses as valid-looking CSS and then fails SILENTLY). So to make a `@media` query follow a theme breakpoint, write the `min-width`/`max-width` yourself and use a `bp(<breakpointId>)` token for the value — the platform rewrites it to the breakpoint's concrete `<width>px` at render time (in BOTH the editor canvas and the published storefront), against the destination store's LIVE breakpoint width:\n\n```css\n/* styles.css — <breakpointId> from list_theme_globals (theme.breakpoints[].id) */\n.grid { grid-template-columns: repeat(3, 1fr); }\n\n/* applies at <= the breakpoint's width */\n@media (max-width: bp(<breakpointId>)) { .grid { grid-template-columns: 1fr; } }\n\n/* applies at > the breakpoint's width */\n@media (min-width: bp(<breakpointId>)) { .grid { grid-template-columns: repeat(4, 1fr); } }\n```\n\n- `bp(<id>)` resolves to `<width>px`. YOU pick the direction by writing `max-width` or `min-width`.\n- Use the breakpoint **id** (stable across renames), NEVER its name. Get ids from `list_theme_globals` (or the runtime `getThemeBreakpoints()` list).\n- Works anywhere in the condition, including `calc()` — e.g. for a non-overlapping upper bound use `@media (min-width: calc(bp(<id>) + 1px))` so it doesn't collide with a `max-width: bp(<id>)` block at the exact width. Inside `calc()` use PX ARITHMETIC ONLY (`+ 1px`, `* 2`, `- bp(<other>)`): the platform folds it to a concrete px value at render time, and a calc mixing other units (rem/em/vw/%) cannot fold — the whole media block is then silently dropped in production builds.\n- Portable: the token resolves to the destination store's own width, and the breakpoint ships automatically as a dependency when you reference it in CSS. Need one that might not exist everywhere? `create_theme_global` (kind `breakpoint`) it first.\n\n### Using a color scheme\n\nColor schemes have two parts: **slots** (the named color keys, e.g. Background/Text/Primary) and **palettes** (sets of colors for those slots). `getThemeColorSchemes()` returns:\n- `schemes`: the slots — `[{ id, name }]`.\n- `values`: the palettes — `[{ id, name, isDefault, className, colorsByScheme }]`, where `colorsByScheme` maps each **slot id** → `{ resolved, cssVar }`.\n\nA scheme color's `cssVar` is `var(--<slotId>)` and is **palette-scoped**: it only resolves inside an element carrying that palette's `className`. So apply the palette to a wrapper, then reference its slots inside:\n\n```tsx\nconst { values } = getThemeColorSchemes();\nconst palette = values.find((v) => v.isDefault) ?? values[0];\n// Reference slots by their id (from list_theme_globals → colorSchemes.schemes), resolving each\n// slot NAME → id ONCE here. NEVER match a slot by .name at runtime: slot names are NOT unique\n// (installing two design assets can create two \"Background\" slots), so\n// schemes.find(x => x.name === \"Background\") may silently pick the WRONG slot. A slot id is stable,\n// so referencing a slot by id is both correct AND portable.\nconst BACKGROUND = \"aB3xY7kLmN\", TEXT = \"pQ4rS2tUvW\", PRIMARY = \"zX8cV1bN0m\"; // real ids from list_theme_globals\nconst slot = (id: string) => palette?.colorsByScheme[id];\n\n// the palette className makes the slot vars resolve in this subtree\nreturn (\n  <section\n    className={palette?.className}\n    style={{ background: slot(BACKGROUND)?.cssVar, color: slot(TEXT)?.cssVar }}\n  >\n    <button style={{ background: slot(PRIMARY)?.cssVar }}>Buy</button>\n  </section>\n);\n```\n\nUse `colorsByScheme[slotId].resolved` if you need the concrete value instead of the live `var()`. Switching palettes at runtime is just swapping the wrapper's `className`.\n\n### Forcing a palette vs. inheriting the section's scheme\n\nSlot vars (`var(--<slotId>)`) resolve against whichever palette `className` sits on an **ancestor**, so you get two modes:\n\n- **Inherit the section's scheme (default, recommended):** do NOT add a palette `className` — just use the slot `cssVar`s. They resolve to the palette the section is set to. A section's color scheme is chosen in the editor (right panel → \"Color Scheme\"), which renders the section wrapper with that palette's class (`_<schemeId>`); leaving your slots unwrapped lets the merchant re-skin the component by switching the section's scheme, with no code change. The var NAMES are identical across palettes (only the value changes with the active ancestor class), so read the `{slotId → cssVar}` map from any palette and stay unwrapped:\n\n```tsx\nconst { values } = getThemeColorSchemes();\nconst palette = values.find((v) => v.isDefault) ?? values[0]; // any palette; var names match across all\n// slot ids from list_theme_globals → colorSchemes.schemes (resolve name → id once; NEVER match a\n// slot by .name at runtime — names are not unique, so a name lookup can pick the wrong slot).\nconst BACKGROUND = \"aB3xY7kLmN\", TEXT = \"pQ4rS2tUvW\", PRIMARY = \"zX8cV1bN0m\";\nconst slot = (id: string) => palette?.colorsByScheme[id]?.cssVar;\n\n// No palette className here → these inherit the SECTION's active scheme.\nreturn (\n  <div style={{ background: slot(BACKGROUND), color: slot(TEXT) }}>\n    <button style={{ background: slot(PRIMARY) }}>Buy</button>\n  </div>\n);\n```\n\n- **Force a specific palette:** wrap the subtree in that palette's `className` (the example above). Use this only for a region that must always use one fixed palette regardless of the section's scheme.\n\n### Create / list via MCP (requires `ikas theme dev` + connected editor)\n\n- `list_theme_globals` — list every global variable and design token in the project (including ones created manually in the editor). **Call this FIRST** so you reuse existing tokens instead of duplicating them.\n- `create_theme_global` — create one, selected by `kind`:\n  - `globalVariable` — `display_name` + `type` (TEXT|RICH_TEXT|IMAGE|COLOR|NUMBER|BOOLEAN|BORDER|SHADOW|ENUM); `value` optional. Value shapes — TEXT/COLOR: string; RICH_TEXT: HTML string; NUMBER: number; BOOLEAN: boolean; IMAGE: `{ url }`; BORDER: `{ width: { value, unit }, style, color }`; SHADOW: `{ x, y, blur, spread, color, position: \"outside\"|\"inside\" }`; ENUM: `enum_type_id` (a project enum id from `list_theme_globals` → `enumTypes[]`) + `value` = one of that enum's option VALUES (not a label). An ENUM setting reads back as `{ type: \"ENUM\", value, enumTypeId, options }`, an ENUM prop of the same enum can be bound to it with `bind_global`, and `themeValue(\"_<id>\")` from `./global-types` narrows to the enum's union type.\n  - `color` — `name` + `value` (hex).\n  - `typography` — `name` + any of `font_family`/`font_size`/`font_weight`/`line_height`/`letter_spacing`.\n  - `breakpoint` — `name` + `width`.\n  - `keyframe` — `name` + `points` (`[{ point, styles? }]`); each style is `{ property, value }` with a CSS property name (opacity, transform, filter, background, color, …). Apply the keyframe's `ref` as a CSS `animation-name` and set timing (duration/iteration) where you apply it.\n  - `colorScheme` — `name` + `colors` (`[{ slotId? | newSlotName?, value }]`); target an existing slot by `slotId` (its id from list_theme_globals → colorSchemes.schemes / colorsByScheme keys), or create/reuse one by `newSlotName` (use the standard slot names like \"Background\"/\"Text\"/\"PrimaryButton/Background\"). Exactly one per entry.\n\n**CLI equivalents** (if you call the ikas-component CLI directly instead of the MCP tools): read with `list-theme-globals`; create with — globalVariable→`create-global-variable`, color→`create-color`, typography→`create-text-style`, breakpoint→`create-breakpoint`, keyframe→`create-keyframe`, colorScheme→`create-color-scheme`. CLI flags are kebab-case (`--display-name`, `--font-size`, `--colors`, …) and the CLI must be run from the project root.\n\n**Update / delete:** `update_theme_global` (fix a global variable's value/type — identify by `name`) and `delete_theme_global` (`kind` globalVariable→`name`, or a design-token kind→`id`). CLI equivalents: `update-global-variable`, `delete-global-variable`, `delete-design-token`.\n\n**Responsive text styles:** `update_text_style` with `breakpoint_id` (an existing breakpoint id from `list_theme_globals`) sets that breakpoint's overrides instead of the desktop values — only `font_size`, `font_weight`, `line_height`, `letter_spacing`; pass `\"\"` to remove an override. CLI: `update-text-style --id <id> --breakpoint <breakpointId> --font-size 32px`. The editor rejects invalid writes (unknown breakpoint, other properties, italic weight, a property without a desktop value, malformed values, weights the font lacks) — fix the input and retry; breakpoints are not created by this call (use `create_theme_global` kind `breakpoint`).\n\nAfter creating, the new item is readable via the runtime getters above (its key/id comes back in the create result and from `list_theme_globals`).\n\n### Live updates vs snapshots (important)\n\nTheme settings reach your component through two channels — pick the right one or edits won't reflect live:\n\n- **Live (CSS):** use `cssVar` (colors, and color-scheme colors) and `className` (typography text styles). These update **instantly** when the value is edited in the editor, because they map to CSS the editor regenerates live. Prefer these for anything visual.\n  - Colors: `style={{ color: token.cssVar }}` (or `background`).\n  - Typography: apply the text style's class — `className={t.className}` — do NOT spread `t.resolved` into an inline `style` if you want live updates.\n    Text styles can be responsive (per-breakpoint font size, line height, letter spacing and font weight). Apply them with `className` (or the literal `_<id>` class) to get per-breakpoint values automatically. `resolved` contains desktop values only; a responsive style also has `breakpoints: [{ id, width, overrides, resolved }]` (widest first, only breakpoints with own overrides; `overrides` = that breakpoint's own values, `resolved` = full effective style there, inherited from wider breakpoints/desktop). The field is absent when the style has no overrides. When a component is published to another store, the breakpoints its text style overrides use are shipped with it.\n  - Color-scheme colors are scoped to the palette: a `var(--<key>)` only resolves inside an element carrying that palette's `className`, so wrap the row: `<div className={paletteValue.className}>…<span style={{background: colorsByScheme[keyId].cssVar}}/>…</div>`.\n- **Snapshot (JS):** `resolved` values, breakpoint `width`, keyframe metadata, and global-variable `value`s are read from JS at render time. They reflect editor edits only when the component **re-renders/remounts** (e.g. its props change, or another action refreshes the canvas) — NOT instantly on a theme-token edit. This is expected, not a bug. Global-variable value edits do trigger a canvas refresh, so they reflect; design-token `resolved` values lag until the next refresh.\n\nRule of thumb: for visuals that must track editor edits live, reference `cssVar` / apply `className`; treat `resolved` and `value` as point-in-time reads.\n\n### Portability (shipping as a partner design asset)\n\nWhen this component is published as a partner design asset and installed into another store, the theme globals it uses are detected at publish time and travel with it. Publish scans the component's compiled output AND the shared chunks it imports; each detected global is added to the asset and created in the destination store on install (unless it is already there), so the references in your code keep resolving there.\n\n- **Global variables travel — hardcoded keys included.** A `themeValue(\"_xyz\")` / `getThemeSetting(\"_xyz\")` / `getThemeSettingValue(\"_xyz\")` call with a literal key ships exactly those variables — default value, groups and types included — also when the call lives in a shared helper file. If no literal key is visible (the key is computed or passed in as a value), or the component calls the iterate-all `getThemeSettings()`, ALL global variables ship. A prop bound to a global variable (via its `privateVarMap`) ships too. You do NOT need to turn a setting into a prop just to make it portable.\n- **Don't mix literal and runtime-built keys.** As soon as ANY literal key is visible in the component's compiled code or the shared chunks it imports, only the literal keys ship — a key built at runtime (`\"_\" + id`, a key read from a prop or another value) is then NOT shipped and resolves to nothing in the destination store. Keep every key literal, or read through `getThemeSettings()`.\n- **Colors, typography, keyframes and breakpoints travel too.** A literal reference in your CSS/JS — a color's `cssVar`, a typography `className` (`_<id>`), a keyframe `ref` (`_<id>`), a `bp(<id>)` token — is detected and ships; the iterate-all accessors (`getThemeColors()`, `getThemeTypography()`, `getThemeKeyframes()`, `getThemeBreakpoints()`) ship the whole category. Iterate the runtime lists when the component should adapt to whatever tokens the destination theme has, rather than to the ones it was built against.\n- **Color schemes always travel in full.** Every scheme slot and palette ships with the asset and is matched by id on install, never by name — so referencing a slot by `var(--<slotId>)` / `colorsByScheme[slotId]` stays valid across stores; resolving it by `.name` does not.\n- **Also travels automatically:** types referenced by your props, nested code components, and shared modules.\n\nRule of thumb: reference globals by the ids/keys `list_theme_globals` returns (never by display name) and they ship with the asset — do not tell the user they must recreate them in the destination store.",
+      "content": "The theme developer defines global settings in the editor's \"Styles\" panel. Code components can READ these at runtime and an AI agent can CREATE/LIST them via MCP tools. Prefer reusing the theme's existing tokens (colors, typography) over hardcoding values — it keeps components consistent with the store's design.\n\n### Read at runtime (in your .tsx)\n\nImport from `@ikas/bp-storefront`. These work in SSR, client hydration, and the editor canvas:\n\n```tsx\nimport {\n  getThemeSetting, getThemeSettings,        // global variables (Theme Settings)\n  getThemeColors, getThemeTypography,        // design tokens\n  getThemeBreakpoints, getThemeKeyframes, getThemeColorSchemes,\n} from \"@ikas/bp-storefront\";\n\nconst brand = getThemeSetting(\"_AbC123XyZ\")?.value;   // key = variableName, from list_theme_globals\nconst colors = getThemeColors();                       // [{ id, name, resolved, cssVar }]\n// resolved = concrete value (e.g. \"#ff0000\"); cssVar = \"var(--<id>)\" (scheme-aware).\n// e.g. style={{ color: colors[0].cssVar }} or className={getThemeTypography()[0].className}\n```\n\nShapes: colors → `{ id, name, resolved, cssVar }`; typography → `{ id, name, resolved, className, breakpoints? }`; breakpoints → `{ id, name, width }` (widest first); keyframes → `{ id, name, type, ref }`; color schemes → `{ schemes, values }`. Global variables → `{ name, displayName, type, value }` where `name` is the stable runtime key (`variableName`).\n\n### Responsive breakpoints in CSS\n\n`getThemeBreakpoints()` gives you each breakpoint's `width` in JS, but a CSS media query CANNOT use `var()` in its condition (it parses as valid-looking CSS and then fails SILENTLY). So to make a `@media` query follow a theme breakpoint, write the `min-width`/`max-width` yourself and use a `bp(<breakpointId>)` token for the value — the platform rewrites it to the breakpoint's concrete `<width>px` at render time (in BOTH the editor canvas and the published storefront), against the destination store's LIVE breakpoint width:\n\n```css\n/* styles.css — <breakpointId> from list_theme_globals (theme.breakpoints[].id) */\n.grid { grid-template-columns: repeat(3, 1fr); }\n\n/* applies at <= the breakpoint's width */\n@media (max-width: bp(<breakpointId>)) { .grid { grid-template-columns: 1fr; } }\n\n/* applies at > the breakpoint's width */\n@media (min-width: bp(<breakpointId>)) { .grid { grid-template-columns: repeat(4, 1fr); } }\n```\n\n- `bp(<id>)` resolves to `<width>px`. YOU pick the direction by writing `max-width` or `min-width`.\n- Use the breakpoint **id** (stable across renames), NEVER its name. Get ids from `list_theme_globals` (or the runtime `getThemeBreakpoints()` list).\n- Works anywhere in the condition, including `calc()` — e.g. for a non-overlapping upper bound use `@media (min-width: calc(bp(<id>) + 1px))` so it doesn't collide with a `max-width: bp(<id>)` block at the exact width. Inside `calc()` use PX ARITHMETIC ONLY (`+ 1px`, `* 2`, `- bp(<other>)`): the platform folds it to a concrete px value at render time, and a calc mixing other units (rem/em/vw/%) cannot fold — the whole media block is then silently dropped in production builds.\n- Portable: the token resolves to the destination store's own width, and the breakpoint ships automatically as a dependency when you reference it in CSS. Need one that might not exist everywhere? `create_theme_global` (kind `breakpoint`) it first.\n\n### Using a color scheme\n\nColor schemes have two parts: **slots** (the named color keys, e.g. Background/Text/Primary) and **palettes** (sets of colors for those slots). `getThemeColorSchemes()` returns:\n- `schemes`: the slots — `[{ id, name }]`.\n- `values`: the palettes — `[{ id, name, isDefault, className, colorsByScheme }]`, where `colorsByScheme` maps each **slot id** → `{ resolved, cssVar }`.\n\nA scheme color's `cssVar` is `var(--<slotId>)` and is **palette-scoped**: it only resolves inside an element carrying that palette's `className`. So apply the palette to a wrapper, then reference its slots inside:\n\n```tsx\nconst { values } = getThemeColorSchemes();\nconst palette = values.find((v) => v.isDefault) ?? values[0];\n// Reference slots by their id (from list_theme_globals → colorSchemes.schemes), resolving each\n// slot NAME → id ONCE here. NEVER match a slot by .name at runtime: slot names are NOT unique\n// (installing two design assets can create two \"Background\" slots), so\n// schemes.find(x => x.name === \"Background\") may silently pick the WRONG slot. A slot id is stable,\n// so referencing a slot by id is both correct AND portable.\nconst BACKGROUND = \"aB3xY7kLmN\", TEXT = \"pQ4rS2tUvW\", PRIMARY = \"zX8cV1bN0m\"; // real ids from list_theme_globals\nconst slot = (id: string) => palette?.colorsByScheme[id];\n\n// the palette className makes the slot vars resolve in this subtree\nreturn (\n  <section\n    className={palette?.className}\n    style={{ background: slot(BACKGROUND)?.cssVar, color: slot(TEXT)?.cssVar }}\n  >\n    <button style={{ background: slot(PRIMARY)?.cssVar }}>Buy</button>\n  </section>\n);\n```\n\nUse `colorsByScheme[slotId].resolved` if you need the concrete value instead of the live `var()`. Switching palettes at runtime is just swapping the wrapper's `className`.\n\n### Forcing a palette vs. inheriting the section's scheme\n\nSlot vars (`var(--<slotId>)`) resolve against whichever palette `className` sits on an **ancestor**, so you get two modes:\n\n- **Inherit the section's scheme (default, recommended):** do NOT add a palette `className` — just use the slot `cssVar`s. They resolve to the palette the section is set to. A section's color scheme is chosen in the editor (right panel → \"Color Scheme\"), which renders the section wrapper with that palette's class (`_<schemeId>`); leaving your slots unwrapped lets the merchant re-skin the component by switching the section's scheme, with no code change. The var NAMES are identical across palettes (only the value changes with the active ancestor class), so read the `{slotId → cssVar}` map from any palette and stay unwrapped:\n\n```tsx\nconst { values } = getThemeColorSchemes();\nconst palette = values.find((v) => v.isDefault) ?? values[0]; // any palette; var names match across all\n// slot ids from list_theme_globals → colorSchemes.schemes (resolve name → id once; NEVER match a\n// slot by .name at runtime — names are not unique, so a name lookup can pick the wrong slot).\nconst BACKGROUND = \"aB3xY7kLmN\", TEXT = \"pQ4rS2tUvW\", PRIMARY = \"zX8cV1bN0m\";\nconst slot = (id: string) => palette?.colorsByScheme[id]?.cssVar;\n\n// No palette className here → these inherit the SECTION's active scheme.\nreturn (\n  <div style={{ background: slot(BACKGROUND), color: slot(TEXT) }}>\n    <button style={{ background: slot(PRIMARY) }}>Buy</button>\n  </div>\n);\n```\n\n- **Force a specific palette:** wrap the subtree in that palette's `className` (the example above). Use this only for a region that must always use one fixed palette regardless of the section's scheme.\n\n### Create / list via MCP (requires `ikas theme dev` + connected editor)\n\n- `list_theme_globals` — list every global variable and design token in the project (including ones created manually in the editor). **Call this FIRST** so you reuse existing tokens instead of duplicating them.\n- `create_theme_global` — create one, selected by `kind`:\n  - `globalVariable` — `display_name` + `type` (TEXT|RICH_TEXT|IMAGE|COLOR|NUMBER|BOOLEAN|BORDER|SHADOW|ENUM); `value` optional. Value shapes — TEXT/COLOR: string; RICH_TEXT: HTML string; NUMBER: number; BOOLEAN: boolean; IMAGE: `{ url }`; BORDER: `{ width: { value, unit }, style, color }`; SHADOW: `{ x, y, blur, spread, color, position: \"outside\"|\"inside\" }`; ENUM: `enum_type_id` (a project enum id from `list_theme_globals` → `enumTypes[]`) + `value` = one of that enum's option VALUES (not a label). An ENUM setting reads back as `{ type: \"ENUM\", value, enumTypeId, options }`, an ENUM prop of the same enum can be bound to it with `bind_global`, and `themeValue(\"_<id>\")` from `./global-types` narrows to the enum's union type.\n  - `color` — `name` + `value` (hex).\n  - `typography` — `name` + any of `font_family`/`font_size`/`font_weight`/`line_height`/`letter_spacing`.\n  - `breakpoint` — `name` + `width`.\n  - `keyframe` — `name` + `points` (`[{ point, styles? }]`); each style is `{ property, value }` with a CSS property name (opacity, transform, filter, background, color, …). Apply the keyframe's `ref` as a CSS `animation-name` and set timing (duration/iteration) where you apply it.\n  - `colorScheme` — `name` + `colors` (`[{ slotId? | newSlotName?, value }]`); target an existing slot by `slotId` (its id from list_theme_globals → colorSchemes.schemes / colorsByScheme keys), or create/reuse one by `newSlotName` (use the standard slot names like \"Background\"/\"Text\"/\"PrimaryButton/Background\"). Exactly one per entry.\n\n**CLI equivalents** (if you call the ikas-component CLI directly instead of the MCP tools): read with `list-theme-globals`; create with — globalVariable→`create-global-variable`, color→`create-color`, typography→`create-text-style`, breakpoint→`create-breakpoint`, keyframe→`create-keyframe`, colorScheme→`create-color-scheme`. CLI flags are kebab-case (`--display-name`, `--font-size`, `--colors`, …) and the CLI must be run from the project root.\n\n**Update / delete:** `update_theme_global` (fix a global variable's value/type — identify by `name`) and `delete_theme_global` (`kind` globalVariable→`name`, or a design-token kind→`id`). CLI equivalents: `update-global-variable`, `delete-global-variable`, `delete-design-token`.\n\n**Responsive text styles:** `update_text_style` with `breakpoint_id` (an existing breakpoint id from `list_theme_globals`) sets that breakpoint's overrides instead of the desktop values — only `font_size`, `font_weight`, `line_height`, `letter_spacing`; pass `\"\"` to remove an override. CLI: `update-text-style --id <id> --breakpoint <breakpointId> --font-size 32px`. For several breakpoints in ONE call pass `breakpoints: [{ breakpoint_id, font_size?, font_weight?, line_height?, letter_spacing? }]` to `update_text_style` or to `create_theme_global` (kind `typography`, together with the desktop values) — CLI `--breakpoints '[{\"breakpointId\":\"<id>\",\"fontSize\":\"32px\"}]'` on `create-text-style` / `update-text-style`; the whole batch is validated and one invalid entry writes nothing. The editor rejects invalid writes (unknown breakpoint, other properties, italic weight, a property without a desktop value, malformed values, weights the font lacks) — fix the input and retry; breakpoints are not created by this call (use `create_theme_global` kind `breakpoint`).\n\nAfter creating, the new item is readable via the runtime getters above (its key/id comes back in the create result and from `list_theme_globals`).\n\n### Live updates vs snapshots (important)\n\nTheme settings reach your component through two channels — pick the right one or edits won't reflect live:\n\n- **Live (CSS):** use `cssVar` (colors, and color-scheme colors) and `className` (typography text styles). These update **instantly** when the value is edited in the editor, because they map to CSS the editor regenerates live. Prefer these for anything visual.\n  - Colors: `style={{ color: token.cssVar }}` (or `background`).\n  - Typography: apply the text style's class — `className={t.className}` — do NOT spread `t.resolved` into an inline `style` if you want live updates.\n    Text styles can be responsive (per-breakpoint font size, line height, letter spacing and font weight). Apply them with `className` (or the literal `_<id>` class) to get per-breakpoint values automatically. `resolved` contains desktop values only; a responsive style also has `breakpoints: [{ id, width, overrides, resolved }]` (widest first, only breakpoints with own overrides; `overrides` = that breakpoint's own values, `resolved` = full effective style there). Inheritance is chained: a property a breakpoint does not override comes from the nearest WIDER breakpoint that overrides it, else from desktop. Overriding font weight keeps the style's italic (italic is not per breakpoint). `text_overflow: ellipsis` only truncates together with `white_space: nowrap` (a text style property) and `overflow: hidden` (component CSS — not a text style property). The field is absent when the style has no overrides. When a component is published to another store, the breakpoints its text style overrides use are shipped with it.\n  - Color-scheme colors are scoped to the palette: a `var(--<key>)` only resolves inside an element carrying that palette's `className`, so wrap the row: `<div className={paletteValue.className}>…<span style={{background: colorsByScheme[keyId].cssVar}}/>…</div>`.\n- **Snapshot (JS):** `resolved` values, breakpoint `width`, keyframe metadata, and global-variable `value`s are read from JS at render time. They reflect editor edits only when the component **re-renders/remounts** (e.g. its props change, or another action refreshes the canvas) — NOT instantly on a theme-token edit. This is expected, not a bug. Global-variable value edits do trigger a canvas refresh, so they reflect; design-token `resolved` values lag until the next refresh.\n\nRule of thumb: for visuals that must track editor edits live, reference `cssVar` / apply `className`; treat `resolved` and `value` as point-in-time reads.\n\n### Portability (shipping as a partner design asset)\n\nWhen this component is published as a partner design asset and installed into another store, the theme globals it uses are detected at publish time and travel with it. Publish scans the component's compiled output AND the shared chunks it imports; each detected global is added to the asset and created in the destination store on install (unless it is already there), so the references in your code keep resolving there.\n\n- **Global variables travel — hardcoded keys included.** A `themeValue(\"_xyz\")` / `getThemeSetting(\"_xyz\")` / `getThemeSettingValue(\"_xyz\")` call with a literal key ships exactly those variables — default value, groups and types included — also when the call lives in a shared helper file. If no literal key is visible (the key is computed or passed in as a value), or the component calls the iterate-all `getThemeSettings()`, ALL global variables ship. A prop bound to a global variable (via its `privateVarMap`) ships too. You do NOT need to turn a setting into a prop just to make it portable.\n- **Don't mix literal and runtime-built keys.** As soon as ANY literal key is visible in the component's compiled code or the shared chunks it imports, only the literal keys ship — a key built at runtime (`\"_\" + id`, a key read from a prop or another value) is then NOT shipped and resolves to nothing in the destination store. Keep every key literal, or read through `getThemeSettings()`.\n- **Colors, typography, keyframes and breakpoints travel too.** A literal reference in your CSS/JS — a color's `cssVar`, a typography `className` (`_<id>`), a keyframe `ref` (`_<id>`), a `bp(<id>)` token — is detected and ships; the iterate-all accessors (`getThemeColors()`, `getThemeTypography()`, `getThemeKeyframes()`, `getThemeBreakpoints()`) ship the whole category. Iterate the runtime lists when the component should adapt to whatever tokens the destination theme has, rather than to the ones it was built against.\n- **Color schemes always travel in full.** Every scheme slot and palette ships with the asset and is matched by id on install, never by name — so referencing a slot by `var(--<slotId>)` / `colorsByScheme[slotId]` stays valid across stores; resolving it by `.name` does not.\n- **Also travels automatically:** types referenced by your props, nested code components, and shared modules.\n\nRule of thumb: reference globals by the ids/keys `list_theme_globals` returns (never by display name) and they ship with the asset — do not tell the user they must recreate them in the destination store.",
       "tags": [
         "theme",
         "global variables",

package/data/storefront-api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-10-07T08:06:49.018Z",
+  "generatedAt": "2026-10-07T09:44:31.465Z",
   "functions": [
     {
       "name": "apiListProductBrand",
@@ -3220,14 +3220,14 @@
       "name": "getIkasOrderRefundableItems",
       "displayName": "getRefundableItems",
       "signature": "function getIkasOrderRefundableItems(order: IkasOrder): IkasOrderLineItem[]",
-      "description": "Returns order line items that are eligible for refund based on item status and the merchant's refund day limit settings.",
+      "description": "Returns order line items that are eligible for refund, based on the refundable lines returned by the API for the order.",
       "params": [
         {
           "name": "order",
           "description": "- The IkasOrder to retrieve refundable items from"
         }
       ],
-      "returns": "An array of order line items eligible for refund, or an empty array if refunds are disabled",
+      "returns": "An array of order line items eligible for refund, or an empty array if refundable lines are not loaded",
       "returnType": "IkasOrderLineItem[]",
       "example": "```typescript\nimport { getIkasOrderRefundableItems } from \"@ikas/bp-storefront\";\nconst refundableItems = getIkasOrderRefundableItems(order);\n```",
       "categories": [
@@ -3236,7 +3236,8 @@
       ],
       "related": [
         "isIkasOrderRefundable",
-        "getIkasOrderRefundedItems"
+        "getIkasOrderRefundedItems",
+        "getIkasOrderRefundReasons"
       ],
       "isAsync": false,
       "isClass": false,
@@ -3246,6 +3247,189 @@
         "IkasOrderLineItem"
       ]
     },
+    {
+      "name": "getIkasOrderRefundReasonId",
+      "displayName": "getRefundReasonId",
+      "signature": "function getIkasOrderRefundReasonId(order: IkasOrder): string | null",
+      "description": "Returns the selected refund reason id for the order's refund request.",
+      "params": [
+        {
+          "name": "order",
+          "description": "- The IkasOrder to read the selected refund reason id from"
+        }
+      ],
+      "returns": "The selected refund reason id, or null if none is selected",
+      "returnType": "string | null",
+      "example": "```typescript\nimport { getIkasOrderRefundReasonId } from \"@ikas/bp-storefront\";\nconst refundReasonId = getIkasOrderRefundReasonId(order);\n```",
+      "categories": [
+        "Order",
+        "Payment"
+      ],
+      "related": [
+        "setIkasOrderRefundReasonId",
+        "getIkasOrderRefundReasons"
+      ],
+      "isAsync": false,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasOrderRefundReasonId",
+        "IkasOrder"
+      ]
+    },
+    {
+      "name": "setIkasOrderRefundReasonId",
+      "displayName": "setRefundReasonId",
+      "signature": "function setIkasOrderRefundReasonId(order: IkasOrder, value: string | null): void",
+      "description": "Sets the selected refund reason id that will be sent with the order's refund request.",
+      "params": [
+        {
+          "name": "order",
+          "description": "- The IkasOrder to set the refund reason id on"
+        },
+        {
+          "name": "value",
+          "description": "- The id of one of the reasons returned by getIkasOrderRefundReasons, or null to clear it"
+        }
+      ],
+      "returnType": "void",
+      "example": "```typescript\nimport { setIkasOrderRefundReasonId, getIkasOrderRefundReasons } from \"@ikas/bp-storefront\";\nconst [firstReason] = getIkasOrderRefundReasons(order);\nsetIkasOrderRefundReasonId(order, firstReason?.id || null);\n```",
+      "categories": [
+        "Order",
+        "Payment"
+      ],
+      "related": [
+        "getIkasOrderRefundReasonId",
+        "getIkasOrderRefundReasons",
+        "refundOrder"
+      ],
+      "isAsync": false,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasOrderRefundReasonId",
+        "IkasOrder"
+      ]
+    },
+    {
+      "name": "getIkasOrderRefundReason",
+      "displayName": "getRefundReason",
+      "signature": "function getIkasOrderRefundReason(order: IkasOrder): string | null",
+      "description": "Returns the free-text refund reason written by the customer for the order's refund request.",
+      "params": [
+        {
+          "name": "order",
+          "description": "- The IkasOrder to read the refund reason note from"
+        }
+      ],
+      "returns": "The refund reason note, or null if none is set",
+      "returnType": "string | null",
+      "example": "```typescript\nimport { getIkasOrderRefundReason } from \"@ikas/bp-storefront\";\nconst reason = getIkasOrderRefundReason(order);\n```",
+      "categories": [
+        "Order",
+        "Payment"
+      ],
+      "related": [
+        "setIkasOrderRefundReason",
+        "getIkasOrderRefundReasonId"
+      ],
+      "isAsync": false,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasOrderRefundReason",
+        "IkasOrder"
+      ]
+    },
+    {
+      "name": "setIkasOrderRefundReason",
+      "displayName": "setRefundReason",
+      "signature": "function setIkasOrderRefundReason(order: IkasOrder, value: string | null): void",
+      "description": "Sets the free-text refund reason that will be sent with the order's refund request.",
+      "params": [
+        {
+          "name": "order",
+          "description": "- The IkasOrder to set the refund reason note on"
+        },
+        {
+          "name": "value",
+          "description": "- The refund reason note, or null to clear it"
+        }
+      ],
+      "returnType": "void",
+      "example": "```typescript\nimport { setIkasOrderRefundReason } from \"@ikas/bp-storefront\";\nsetIkasOrderRefundReason(order, \"The product arrived damaged\");\n```",
+      "categories": [
+        "Order",
+        "Payment"
+      ],
+      "related": [
+        "getIkasOrderRefundReason",
+        "setIkasOrderRefundReasonId",
+        "refundOrder"
+      ],
+      "isAsync": false,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasOrderRefundReason",
+        "IkasOrder"
+      ]
+    },
+    {
+      "name": "getIkasOrderRefundReasons",
+      "displayName": "getRefundReasons",
+      "signature": "function getIkasOrderRefundReasons(order: IkasOrder): IkasOrderRefundReason[]",
+      "description": "Returns the refund reasons the customer can choose from, with titles translated to the current locale.",
+      "params": [
+        {
+          "name": "order",
+          "description": "- The IkasOrder to get refund reasons for"
+        }
+      ],
+      "returns": "An array of refund reasons with localized titles, or an empty array if refundable lines are not loaded",
+      "returnType": "IkasOrderRefundReason[]",
+      "example": "```typescript\nimport { getIkasOrderRefundReasons } from \"@ikas/bp-storefront\";\nconst reasons = getIkasOrderRefundReasons(order);\nreasons.forEach(reason => console.log(reason.id, reason.title));\n```",
+      "categories": [
+        "Order",
+        "Payment"
+      ],
+      "related": [
+        "setIkasOrderRefundReasonId",
+        "getIkasOrderRefundableItems"
+      ],
+      "isAsync": false,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasOrderRefundReasons",
+        "IkasOrder",
+        "IkasOrderRefundReason"
+      ]
+    },
+    {
+      "name": "getIkasOrderReturnMethodDescription",
+      "displayName": "getReturnMethodDescription",
+      "signature": "function getIkasOrderReturnMethodDescription(order: IkasOrder): string | null",
+      "description": "Returns the merchant's return method description for the current locale.",
+      "params": [
+        {
+          "name": "order",
+          "description": "- The IkasOrder to get the return method description for"
+        }
+      ],
+      "returns": "The return method description for the current locale, or null if none exists",
+      "returnType": "string | null",
+      "example": "```typescript\nimport { getIkasOrderReturnMethodDescription } from \"@ikas/bp-storefront\";\nconst description = getIkasOrderReturnMethodDescription(order);\n```",
+      "categories": [
+        "Order",
+        "Payment"
+      ],
+      "related": [
+        "getIkasOrderRefundReasons",
+        "getIkasOrderRefundableItems"
+      ],
+      "isAsync": false,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasOrderReturnMethodDescription",
+        "IkasOrder"
+      ]
+    },
     {
       "name": "isIkasOrderRefundable",
       "displayName": "isRefundable",
@@ -13718,6 +13902,44 @@
         "IkasCustomerAddress"
       ]
     },
+    {
+      "name": "createRefundRequest",
+      "signature": "async function createRefundRequest(customerStore: IkasCustomerStore, order: IkasOrder, email?: string | null): Promise<IkasRefundRequestResult>",
+      "description": "Submit a refund request for an order based on the refund quantities set on each line item,\nalong with the selected refund reason id and refund reason note set on the order.",
+      "params": [
+        {
+          "name": "customerStore",
+          "description": "- The customer store instance"
+        },
+        {
+          "name": "order",
+          "description": "- The order to request a refund for"
+        },
+        {
+          "name": "email",
+          "description": "- Optional email address for guest order refunds"
+        }
+      ],
+      "returns": "Object with isSuccess flag, errorCode on failure and the not allowed lines for REFUND_NOT_ALLOWED",
+      "returnType": "Promise<IkasRefundRequestResult>",
+      "example": "```typescript\nimport { customerStore, createRefundRequest, getOrder } from \"@ikas/bp-storefront\";\n\nasync function handleRefundRequest(orderId: string) {\n  const order = await getOrder(customerStore, orderId);\n  if (!order) return;\n\n  const result = await createRefundRequest(customerStore, order);\n  if (result.isSuccess) {\n    showToast(\"Refund request submitted\");\n  } else if (result.errorCode === \"REFUND_REASON_REQUIRED\") {\n    showToast(\"Please select a refund reason\");\n  } else {\n    showToast(\"Refund request failed\");\n  }\n}\n```",
+      "categories": [
+        "Customer"
+      ],
+      "related": [
+        "refundOrder",
+        "getOrder",
+        "setIkasOrderRefundReasonId",
+        "setIkasOrderRefundReason"
+      ],
+      "isAsync": true,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasCustomerStore",
+        "IkasOrder",
+        "IkasRefundRequestResult"
+      ]
+    },
     {
       "name": "refundOrder",
       "signature": "async function refundOrder(customerStore: IkasCustomerStore, order: IkasOrder, email?: string | null): Promise<boolean>",
@@ -13743,6 +13965,7 @@
         "Customer"
       ],
       "related": [
+        "createRefundRequest",
         "getOrder",
         "getOrders",
         "getOrderRefundSettings"

package/data/storefront-types.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-10-07T08:06:49.044Z",
+  "generatedAt": "2026-10-07T09:44:31.494Z",
   "types": [
     {
       "name": "TextElementTagTypes",
@@ -6625,6 +6625,31 @@
           "name": "transactions",
           "type": "IkasOrderTransaction[]",
           "optional": true
+        },
+        {
+          "name": "_refundableLines",
+          "type": "IkasRefundableLine[] | null",
+          "optional": true
+        },
+        {
+          "name": "_refundReasons",
+          "type": "IkasOrderRefundReason[] | null",
+          "optional": true
+        },
+        {
+          "name": "_refundTranslations",
+          "type": "IkasOrderRefundSettingsTranslation[] | null",
+          "optional": true
+        },
+        {
+          "name": "_refundReasonId",
+          "type": "string | null",
+          "optional": true
+        },
+        {
+          "name": "_refundReason",
+          "type": "string | null",
+          "optional": true
         }
       ],
       "filePath": "order/index.ts",
@@ -6634,6 +6659,12 @@
         "getIkasOrderTotalItemCount",
         "getIkasOrderDisplayedPackages",
         "getIkasOrderRefundableItems",
+        "getIkasOrderRefundReasonId",
+        "setIkasOrderRefundReasonId",
+        "getIkasOrderRefundReason",
+        "setIkasOrderRefundReason",
+        "getIkasOrderRefundReasons",
+        "getIkasOrderReturnMethodDescription",
         "isIkasOrderRefundable",
         "getIkasOrderUnfullfilledItems",
         "getIkasOrderRefundedItems",
@@ -6656,6 +6687,7 @@
         "getIkasOrderHref",
         "getIkasOrderVariantNames",
         "submitOrderTrackingForm",
+        "createRefundRequest",
         "refundOrder",
         "getOrders",
         "getOrder",
@@ -7036,6 +7068,26 @@
           "type": "number",
           "optional": false
         },
+        {
+          "name": "flow",
+          "type": "IkasOrderRefundFlow | null",
+          "optional": true
+        },
+        {
+          "name": "autoApprove",
+          "type": "boolean",
+          "optional": true
+        },
+        {
+          "name": "isCancellable",
+          "type": "boolean",
+          "optional": true
+        },
+        {
+          "name": "isRefundable",
+          "type": "boolean",
+          "optional": true
+        },
         {
           "name": "_refundQuantity",
           "type": "number | null",
@@ -7886,6 +7938,118 @@
       ],
       "filePath": "order/refund/line-item/index.ts"
     },
+    {
+      "name": "IkasOrderRefundReason",
+      "kind": "type",
+      "domain": "order",
+      "properties": [
+        {
+          "name": "id",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "title",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "translations",
+          "type": "IkasOrderRefundReasonTranslation[] | null",
+          "optional": false
+        }
+      ],
+      "filePath": "order/refund/reason/index.ts",
+      "relatedFunctions": [
+        "getIkasOrderRefundReason",
+        "setIkasOrderRefundReason",
+        "getIkasOrderRefundReasons"
+      ]
+    },
+    {
+      "name": "IkasOrderRefundReasonTranslation",
+      "kind": "type",
+      "domain": "order",
+      "properties": [
+        {
+          "name": "locale",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "title",
+          "type": "string | null",
+          "optional": false
+        }
+      ],
+      "filePath": "order/refund/reason/translation/index.ts"
+    },
+    {
+      "name": "IkasOrderRefundFlow",
+      "kind": "type",
+      "domain": "order",
+      "unionValues": [
+        "CANCEL",
+        "RETURN"
+      ],
+      "filePath": "order/refund/refundable-line/index.ts"
+    },
+    {
+      "name": "IkasRefundableLine",
+      "kind": "type",
+      "domain": "order",
+      "properties": [
+        {
+          "name": "autoApprove",
+          "type": "boolean",
+          "optional": false
+        },
+        {
+          "name": "flow",
+          "type": "IkasOrderRefundFlow | null",
+          "optional": false
+        },
+        {
+          "name": "isCancellable",
+          "type": "boolean",
+          "optional": false
+        },
+        {
+          "name": "isRefundable",
+          "type": "boolean",
+          "optional": false
+        },
+        {
+          "name": "orderLineItemId",
+          "type": "string",
+          "optional": false
+        }
+      ],
+      "filePath": "order/refund/refundable-line/index.ts"
+    },
+    {
+      "name": "IkasRefundableLines",
+      "kind": "type",
+      "domain": "order",
+      "properties": [
+        {
+          "name": "orderLineItems",
+          "type": "IkasRefundableLine[]",
+          "optional": false
+        },
+        {
+          "name": "refundReasons",
+          "type": "IkasOrderRefundReason[]",
+          "optional": false
+        },
+        {
+          "name": "translations",
+          "type": "IkasOrderRefundSettingsTranslation[]",
+          "optional": false
+        }
+      ],
+      "filePath": "order/refund/refundable-lines/index.ts"
+    },
     {
       "name": "IkasOrderRefundSettings",
       "kind": "type",
@@ -7909,6 +8073,24 @@
       ],
       "filePath": "order/refund/settings/index.ts"
     },
+    {
+      "name": "IkasOrderRefundSettingsTranslation",
+      "kind": "type",
+      "domain": "order",
+      "properties": [
+        {
+          "name": "locale",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "returnMethodDescription",
+          "type": "string | null",
+          "optional": false
+        }
+      ],
+      "filePath": "order/refund/settings/translation/index.ts"
+    },
     {
       "name": "IkasOrderShippingLine",
       "kind": "type",
@@ -15175,7 +15357,7 @@
         },
         {
           "name": "width",
-          "type": "number",
+          "type": "number | string",
           "optional": true
         }
       ],