@3fn/core 14.1.0 → 15.0.0

package/dist/components/core/Container-Base/Container-Base.refs.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Container-Base Component Token References
+ *
+ * Stemma System naming: [Family]-[Type] = Container-Base
+ * Type: Primitive (foundational component)
+ *
+ * Platform-agnostic token reference mappings for the Container-Base component.
+ * These mappings define which design system tokens the component uses,
+ * not how they're implemented per platform.
+ *
+ * The build system generates platform-specific values from these references:
+ * - Web: CSS custom properties (var(--space-inset-200))
+ * - iOS: Swift constants (spaceInset200)
+ * - Android: Kotlin constants (spaceInset200.dp)
+ *
+ * @see .kiro/specs/010-container-component/design.md for token consumption strategy
+ * @see .kiro/specs/034-component-architecture-system for Stemma System details
+ */
+import type { PaddingValue, BorderValue, BorderRadiusValue, LayeringValue } from './types';
+/**
+ * Platform identifier for token mapping
+ */
+export type Platform = 'web' | 'ios' | 'android';
+/**
+ * Padding token mapping
+ *
+ * Maps padding prop values to space.inset token names.
+ * These tokens follow the 8px baseline grid with mathematical relationships.
+ *
+ * Token values:
+ * - inset.050: 4px (0.5 × base)
+ * - inset.100: 8px (1 × base)
+ * - inset.150: 12px (1.5 × base)
+ * - inset.200: 16px (2 × base)
+ * - inset.300: 24px (3 × base)
+ * - inset.400: 32px (4 × base)
+ *
+ * @see Requirements 2.1, 3.1-3.7
+ */
+export declare const paddingTokenMap: Record<PaddingValue, string>;
+/**
+ * Border token mapping
+ *
+ * Maps border prop values to border width token names.
+ * Border color defaults to the color.structure.border token (BORDER_COLOR_TOKEN).
+ *
+ * Token values:
+ * - border.default: 1px
+ * - border.emphasis: 2px
+ * - border.heavy: 4px
+ *
+ * Values are canonical semantic token names (as registered in the token index), so
+ * `tokenToCssVar` resolves them to generated custom properties: border.default ->
+ * --border-default. (These were previously 'border.border.*', which assumed a
+ * category-prefix strip that tokenToCssVar never performed and emitted the
+ * nonexistent --border-border-*.)
+ *
+ * @see Requirements 2.4, 6.1-6.5
+ */
+export declare const borderTokenMap: Record<BorderValue, string>;
+/**
+ * Border radius token mapping
+ *
+ * Maps borderRadius prop values to radius token names.
+ *
+ * Token values:
+ * - radius-050: 4px
+ * - radius-100: 8px
+ * - radius-200: 16px
+ *
+ * @see Requirements 2.5, 7.1-7.4
+ */
+export declare const borderRadiusTokenMap: Record<BorderRadiusValue, string>;
+/**
+ * Platform-specific token mapping structure
+ *
+ * Allows different token references per platform.
+ * Used for layering tokens where web/iOS use z-index and Android uses elevation.
+ */
+export interface PlatformTokenMap {
+    web: Record<string, string>;
+    ios: Record<string, string>;
+    android: Record<string, string>;
+}
+/**
+ * Layering token mapping (platform-specific)
+ *
+ * Maps layering prop values to platform-specific stacking tokens:
+ * - Web/iOS: z-index tokens (control stacking order only)
+ * - Android: elevation tokens (control both stacking order and shadow rendering)
+ *
+ * Z-Index token values (web/iOS):
+ * - zIndex.container: 100
+ * - zIndex.navigation: 200
+ * - zIndex.dropdown: 300
+ * - zIndex.modal: 400
+ * - zIndex.toast: 500
+ * - zIndex.tooltip: 600
+ *
+ * Elevation token values (Android):
+ * - elevation.container: 8dp
+ * - elevation.navigation: 4dp
+ * - elevation.dropdown: 8dp
+ * - elevation.modal: 16dp
+ * - elevation.toast: 24dp
+ * - elevation.tooltip: 24dp
+ *
+ * Note: Android elevation tokens couple stacking order with shadow rendering,
+ * following Material Design guidelines. If both layering and shadow props are
+ * provided on Android, layering takes precedence.
+ *
+ * @see Requirements 9.1-9.9, 16.2-16.3
+ */
+export declare const layeringTokenMap: PlatformTokenMap;
+/**
+ * Get padding token name for a given padding value
+ *
+ * @param padding - Padding prop value
+ * @returns Token name or empty string for 'none'
+ *
+ * @example
+ * ```typescript
+ * getPaddingToken('200') // Returns 'space.inset.200'
+ * getPaddingToken('none') // Returns ''
+ * ```
+ */
+export declare function getPaddingToken(padding: PaddingValue): string;
+/**
+ * Get border token name for a given border value
+ *
+ * @param border - Border prop value
+ * @returns Token name or empty string for 'none'
+ *
+ * @example
+ * ```typescript
+ * getBorderToken('default') // Returns 'border.default'
+ * getBorderToken('none') // Returns ''
+ * ```
+ */
+export declare function getBorderToken(border: BorderValue): string;
+/**
+ * Get border radius token name for a given border radius value
+ *
+ * @param borderRadius - Border radius prop value
+ * @returns Token name or empty string for 'none'
+ *
+ * @example
+ * ```typescript
+ * getBorderRadiusToken('normal') // Returns 'radius-100'
+ * getBorderRadiusToken('none') // Returns ''
+ * ```
+ */
+export declare function getBorderRadiusToken(borderRadius: BorderRadiusValue): string;
+/**
+ * Get layering token name for a given layering value and platform
+ *
+ * Returns platform-specific token name:
+ * - Web/iOS: z-index token
+ * - Android: elevation token
+ *
+ * @param layering - Layering prop value
+ * @param platform - Target platform
+ * @returns Token name for the specified platform
+ *
+ * @example
+ * ```typescript
+ * getLayeringToken('modal', 'web') // Returns 'zIndex.modal'
+ * getLayeringToken('modal', 'android') // Returns 'elevation.modal'
+ * ```
+ */
+export declare function getLayeringToken(layering: LayeringValue, platform: Platform): string;
+/**
+ * Border color token constant
+ *
+ * All borders use the same semantic color token for consistency.
+ * This ensures borders have consistent appearance across the design system.
+ *
+ * @see Requirements 6.5
+ */
+export declare const BORDER_COLOR_TOKEN = "color.structure.border";
+//# sourceMappingURL=Container-Base.refs.d.ts.map

package/dist/components/core/Container-Base/Container-Base.refs.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * Container-Base Component Token References
+ *
+ * Stemma System naming: [Family]-[Type] = Container-Base
+ * Type: Primitive (foundational component)
+ *
+ * Platform-agnostic token reference mappings for the Container-Base component.
+ * These mappings define which design system tokens the component uses,
+ * not how they're implemented per platform.
+ *
+ * The build system generates platform-specific values from these references:
+ * - Web: CSS custom properties (var(--space-inset-200))
+ * - iOS: Swift constants (spaceInset200)
+ * - Android: Kotlin constants (spaceInset200.dp)
+ *
+ * @see .kiro/specs/010-container-component/design.md for token consumption strategy
+ * @see .kiro/specs/034-component-architecture-system for Stemma System details
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BORDER_COLOR_TOKEN = exports.layeringTokenMap = exports.borderRadiusTokenMap = exports.borderTokenMap = exports.paddingTokenMap = void 0;
+exports.getPaddingToken = getPaddingToken;
+exports.getBorderToken = getBorderToken;
+exports.getBorderRadiusToken = getBorderRadiusToken;
+exports.getLayeringToken = getLayeringToken;
+/**
+ * Padding token mapping
+ *
+ * Maps padding prop values to space.inset token names.
+ * These tokens follow the 8px baseline grid with mathematical relationships.
+ *
+ * Token values:
+ * - inset.050: 4px (0.5 × base)
+ * - inset.100: 8px (1 × base)
+ * - inset.150: 12px (1.5 × base)
+ * - inset.200: 16px (2 × base)
+ * - inset.300: 24px (3 × base)
+ * - inset.400: 32px (4 × base)
+ *
+ * @see Requirements 2.1, 3.1-3.7
+ */
+exports.paddingTokenMap = {
+    'none': '',
+    '050': 'space.inset.050',
+    '100': 'space.inset.100',
+    '150': 'space.inset.150',
+    '200': 'space.inset.200',
+    '300': 'space.inset.300',
+    '400': 'space.inset.400'
+};
+/**
+ * Border token mapping
+ *
+ * Maps border prop values to border width token names.
+ * Border color defaults to the color.structure.border token (BORDER_COLOR_TOKEN).
+ *
+ * Token values:
+ * - border.default: 1px
+ * - border.emphasis: 2px
+ * - border.heavy: 4px
+ *
+ * Values are canonical semantic token names (as registered in the token index), so
+ * `tokenToCssVar` resolves them to generated custom properties: border.default ->
+ * --border-default. (These were previously 'border.border.*', which assumed a
+ * category-prefix strip that tokenToCssVar never performed and emitted the
+ * nonexistent --border-border-*.)
+ *
+ * @see Requirements 2.4, 6.1-6.5
+ */
+exports.borderTokenMap = {
+    'none': '',
+    'default': 'border.default',
+    'emphasis': 'border.emphasis',
+    'heavy': 'border.heavy'
+};
+/**
+ * Border radius token mapping
+ *
+ * Maps borderRadius prop values to radius token names.
+ *
+ * Token values:
+ * - radius-050: 4px
+ * - radius-100: 8px
+ * - radius-200: 16px
+ *
+ * @see Requirements 2.5, 7.1-7.4
+ */
+exports.borderRadiusTokenMap = {
+    'none': '',
+    'tight': 'radius-050',
+    'normal': 'radius-100',
+    'loose': 'radius-200'
+};
+/**
+ * Layering token mapping (platform-specific)
+ *
+ * Maps layering prop values to platform-specific stacking tokens:
+ * - Web/iOS: z-index tokens (control stacking order only)
+ * - Android: elevation tokens (control both stacking order and shadow rendering)
+ *
+ * Z-Index token values (web/iOS):
+ * - zIndex.container: 100
+ * - zIndex.navigation: 200
+ * - zIndex.dropdown: 300
+ * - zIndex.modal: 400
+ * - zIndex.toast: 500
+ * - zIndex.tooltip: 600
+ *
+ * Elevation token values (Android):
+ * - elevation.container: 8dp
+ * - elevation.navigation: 4dp
+ * - elevation.dropdown: 8dp
+ * - elevation.modal: 16dp
+ * - elevation.toast: 24dp
+ * - elevation.tooltip: 24dp
+ *
+ * Note: Android elevation tokens couple stacking order with shadow rendering,
+ * following Material Design guidelines. If both layering and shadow props are
+ * provided on Android, layering takes precedence.
+ *
+ * @see Requirements 9.1-9.9, 16.2-16.3
+ */
+exports.layeringTokenMap = {
+    web: {
+        'container': 'zIndex.container',
+        'navigation': 'zIndex.navigation',
+        'dropdown': 'zIndex.dropdown',
+        'modal': 'zIndex.modal',
+        'toast': 'zIndex.toast',
+        'tooltip': 'zIndex.tooltip'
+    },
+    ios: {
+        'container': 'zIndex.container',
+        'navigation': 'zIndex.navigation',
+        'dropdown': 'zIndex.dropdown',
+        'modal': 'zIndex.modal',
+        'toast': 'zIndex.toast',
+        'tooltip': 'zIndex.tooltip'
+    },
+    android: {
+        'container': 'elevation.container',
+        'navigation': 'elevation.navigation',
+        'dropdown': 'elevation.dropdown',
+        'modal': 'elevation.modal',
+        'toast': 'elevation.toast',
+        'tooltip': 'elevation.tooltip'
+    }
+};
+/**
+ * Get padding token name for a given padding value
+ *
+ * @param padding - Padding prop value
+ * @returns Token name or empty string for 'none'
+ *
+ * @example
+ * ```typescript
+ * getPaddingToken('200') // Returns 'space.inset.200'
+ * getPaddingToken('none') // Returns ''
+ * ```
+ */
+function getPaddingToken(padding) {
+    return exports.paddingTokenMap[padding];
+}
+/**
+ * Get border token name for a given border value
+ *
+ * @param border - Border prop value
+ * @returns Token name or empty string for 'none'
+ *
+ * @example
+ * ```typescript
+ * getBorderToken('default') // Returns 'border.default'
+ * getBorderToken('none') // Returns ''
+ * ```
+ */
+function getBorderToken(border) {
+    return exports.borderTokenMap[border];
+}
+/**
+ * Get border radius token name for a given border radius value
+ *
+ * @param borderRadius - Border radius prop value
+ * @returns Token name or empty string for 'none'
+ *
+ * @example
+ * ```typescript
+ * getBorderRadiusToken('normal') // Returns 'radius-100'
+ * getBorderRadiusToken('none') // Returns ''
+ * ```
+ */
+function getBorderRadiusToken(borderRadius) {
+    return exports.borderRadiusTokenMap[borderRadius];
+}
+/**
+ * Get layering token name for a given layering value and platform
+ *
+ * Returns platform-specific token name:
+ * - Web/iOS: z-index token
+ * - Android: elevation token
+ *
+ * @param layering - Layering prop value
+ * @param platform - Target platform
+ * @returns Token name for the specified platform
+ *
+ * @example
+ * ```typescript
+ * getLayeringToken('modal', 'web') // Returns 'zIndex.modal'
+ * getLayeringToken('modal', 'android') // Returns 'elevation.modal'
+ * ```
+ */
+function getLayeringToken(layering, platform) {
+    return exports.layeringTokenMap[platform][layering];
+}
+/**
+ * Border color token constant
+ *
+ * All borders use the same semantic color token for consistency.
+ * This ensures borders have consistent appearance across the design system.
+ *
+ * @see Requirements 6.5
+ */
+exports.BORDER_COLOR_TOKEN = 'color.structure.border';
+//# sourceMappingURL=Container-Base.refs.js.map

package/dist/components/core/Container-Base/index.d.ts

@@ -14,6 +14,6 @@
  */
 export type { PaddingValue, BorderValue, BorderRadiusValue, LayeringValue, SemanticHTMLElement, ContainerBaseProps } from './types';
 export { isPaddingValue, isBorderValue, isBorderRadiusValue, isLayeringValue, isSemanticHTMLElement } from './types';
-export type { Platform, PlatformTokenMap } from './tokens';
-export { paddingTokenMap, borderTokenMap, borderRadiusTokenMap, layeringTokenMap, getPaddingToken, getBorderToken, getBorderRadiusToken, getLayeringToken, BORDER_COLOR_TOKEN } from './tokens';
+export type { Platform, PlatformTokenMap } from './Container-Base.refs';
+export { paddingTokenMap, borderTokenMap, borderRadiusTokenMap, layeringTokenMap, getPaddingToken, getBorderToken, getBorderRadiusToken, getLayeringToken, BORDER_COLOR_TOKEN } from './Container-Base.refs';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/core/Container-Base/index.js

@@ -21,14 +21,14 @@ Object.defineProperty(exports, "isBorderValue", { enumerable: true, get: functio
 Object.defineProperty(exports, "isBorderRadiusValue", { enumerable: true, get: function () { return types_1.isBorderRadiusValue; } });
 Object.defineProperty(exports, "isLayeringValue", { enumerable: true, get: function () { return types_1.isLayeringValue; } });
 Object.defineProperty(exports, "isSemanticHTMLElement", { enumerable: true, get: function () { return types_1.isSemanticHTMLElement; } });
-var tokens_1 = require("./tokens");
-Object.defineProperty(exports, "paddingTokenMap", { enumerable: true, get: function () { return tokens_1.paddingTokenMap; } });
-Object.defineProperty(exports, "borderTokenMap", { enumerable: true, get: function () { return tokens_1.borderTokenMap; } });
-Object.defineProperty(exports, "borderRadiusTokenMap", { enumerable: true, get: function () { return tokens_1.borderRadiusTokenMap; } });
-Object.defineProperty(exports, "layeringTokenMap", { enumerable: true, get: function () { return tokens_1.layeringTokenMap; } });
-Object.defineProperty(exports, "getPaddingToken", { enumerable: true, get: function () { return tokens_1.getPaddingToken; } });
-Object.defineProperty(exports, "getBorderToken", { enumerable: true, get: function () { return tokens_1.getBorderToken; } });
-Object.defineProperty(exports, "getBorderRadiusToken", { enumerable: true, get: function () { return tokens_1.getBorderRadiusToken; } });
-Object.defineProperty(exports, "getLayeringToken", { enumerable: true, get: function () { return tokens_1.getLayeringToken; } });
-Object.defineProperty(exports, "BORDER_COLOR_TOKEN", { enumerable: true, get: function () { return tokens_1.BORDER_COLOR_TOKEN; } });
+var Container_Base_refs_1 = require("./Container-Base.refs");
+Object.defineProperty(exports, "paddingTokenMap", { enumerable: true, get: function () { return Container_Base_refs_1.paddingTokenMap; } });
+Object.defineProperty(exports, "borderTokenMap", { enumerable: true, get: function () { return Container_Base_refs_1.borderTokenMap; } });
+Object.defineProperty(exports, "borderRadiusTokenMap", { enumerable: true, get: function () { return Container_Base_refs_1.borderRadiusTokenMap; } });
+Object.defineProperty(exports, "layeringTokenMap", { enumerable: true, get: function () { return Container_Base_refs_1.layeringTokenMap; } });
+Object.defineProperty(exports, "getPaddingToken", { enumerable: true, get: function () { return Container_Base_refs_1.getPaddingToken; } });
+Object.defineProperty(exports, "getBorderToken", { enumerable: true, get: function () { return Container_Base_refs_1.getBorderToken; } });
+Object.defineProperty(exports, "getBorderRadiusToken", { enumerable: true, get: function () { return Container_Base_refs_1.getBorderRadiusToken; } });
+Object.defineProperty(exports, "getLayeringToken", { enumerable: true, get: function () { return Container_Base_refs_1.getLayeringToken; } });
+Object.defineProperty(exports, "BORDER_COLOR_TOKEN", { enumerable: true, get: function () { return Container_Base_refs_1.BORDER_COLOR_TOKEN; } });
 //# sourceMappingURL=index.js.map

package/dist/components/core/Container-Base/platforms/web/ContainerBase.web.js

@@ -195,7 +195,7 @@ class ContainerBaseWeb extends HTMLElement {
         let baseColor = '';
         if (background) {
             // Convert token name to CSS custom property format
-            const cssVarName = `--${background.replace(/\./g, '-')}`;
+            const cssVarName = (0, token_mapping_1.tokenToCssCustomProperty)(background);
             baseColor = computedStyle.getPropertyValue(cssVarName).trim();
         }
         // Fallback to surface color if no background or couldn't resolve

package/dist/components/core/Container-Base/platforms/web/token-mapping.d.ts

@@ -32,11 +32,29 @@
 import type { PaddingValue, BorderValue, BorderRadiusValue, LayeringValue } from '../../types';
 import type { ColorTokenName, ShadowTokenName, OpacityTokenName } from '@3fn/core/types';
 /**
- * Convert token name to CSS custom property format
+ * Convert a token name to its generated CSS custom property name (`--…`).
+ *
+ * Mirrors the web generator's naming (the `platforms.web` names in token-index/,
+ * i.e. what DesignTokens.web.css emits): split on dots, kebab-case camelCase
+ * boundaries, hyphenate letter→digit boundaries, lowercase, join with '-':
+ * - 'space.inset.200'          -> '--space-inset-200'
+ * - 'zIndex.container'         -> '--z-index-container'
+ * - 'color.select.notSelected' -> '--color-select-not-selected'
+ * - 'icon.size100'             -> '--icon-size-100'
+ * - 'radius-050' (legacy form) -> '--radius-050'
+ *
+ * Parity with the generator is guarded: ContainerBase.token-resolution.test.ts
+ * asserts this function reproduces every token-index web name exactly.
+ *
+ * @param tokenName - Token name (dot notation)
+ * @returns The CSS custom property name, including the leading `--`
+ */
+export declare function tokenToCssCustomProperty(tokenName: string): string;
+/**
+ * Convert token name to a CSS `var()` reference.
  *
- * Transforms dot-notation token names to CSS variable format with var() wrapper:
- * - 'space.inset.200' -> 'var(--space-inset-200)'
- * - 'color.primary' -> 'var(--color-primary)'
+ * - 'space.inset.200'  -> 'var(--space-inset-200)'
+ * - 'zIndex.modal'     -> 'var(--z-index-modal)'
  * - 'shadow.container' -> 'var(--shadow-container)'
  *
  * @param tokenName - Token name in dot notation
@@ -45,7 +63,7 @@ import type { ColorTokenName, ShadowTokenName, OpacityTokenName } from '@3fn/cor
  * @example
  * ```typescript
  * tokenToCssVar('space.inset.200') // Returns 'var(--space-inset-200)'
- * tokenToCssVar('color.primary') // Returns 'var(--color-primary)'
+ * tokenToCssVar('zIndex.modal') // Returns 'var(--z-index-modal)'
  * ```
  */
 export declare function tokenToCssVar(tokenName: string): string;
@@ -194,7 +212,7 @@ export declare function mapPaddingInlineEndToCSS(paddingInlineEnd: PaddingValue
  *
  * @example
  * ```typescript
- * mapBorderToCSS('default') // Returns 'border: var(--border-default) solid var(--color-border)'
+ * mapBorderToCSS('default') // Returns 'border: var(--border-default) solid var(--color-structure-border)'
  * mapBorderToCSS('default', 'color.structure.border.subtle') // Returns 'border: var(--border-default) solid var(--color-structure-border-subtle)'
  * mapBorderToCSS('none') // Returns ''
  * ```
@@ -231,7 +249,7 @@ export declare function mapBorderRadiusToCSS(borderRadius: BorderRadiusValue | n
  *
  * @example
  * ```typescript
- * mapColorToCSS('color.primary') // Returns 'background: var(--color-primary)'
+ * mapColorToCSS('color.structure.surface') // Returns 'background: var(--color-structure-surface)'
  * mapColorToCSS('color.structure.surface') // Returns 'background: var(--color-structure-surface)'
  * ```
  *
@@ -323,7 +341,7 @@ export declare function mapLayeringToCSS(layering: LayeringValue | null): string
  *   padding: '200',
  *   paddingVertical: '100',
  *   paddingBlockStart: '050',
- *   background: 'color.surface',
+ *   background: 'color.structure.surface',
  *   shadow: 'shadow.container',
  *   borderRadius: 'normal'
  * })
@@ -331,7 +349,7 @@ export declare function mapLayeringToCSS(layering: LayeringValue | null): string
  * // padding: var(--space-inset-200);
  * // padding-block: var(--space-inset-100);
  * // padding-block-start: var(--space-inset-050);
- * // background: var(--color-surface);
+ * // background: var(--color-structure-surface);
  * // box-shadow: var(--shadow-container);
  * // border-radius: var(--radius-100)
  * ```