@3fn/core 14.1.0 → 15.0.0

package/src/components/core/Container-Base/index.ts

@@ -1,47 +0,0 @@
-/**
- * Container-Base Component Index
- * 
- * Stemma System naming: [Family]-[Type] = Container-Base
- * Type: Primitive (foundational component)
- * 
- * Container-Base is a foundational primitive component that provides structural
- * wrapping with individual styling capabilities. It serves as the building block
- * for semantic components (Card, Panel, Hero) by exposing granular styling props
- * that map to design system tokens.
- * 
- * @see ./README.md for complete documentation
- * @see .kiro/specs/034-component-architecture-system for Stemma System details
- */
-
-// Export types
-export type {
-  PaddingValue,
-  BorderValue,
-  BorderRadiusValue,
-  LayeringValue,
-  SemanticHTMLElement,
-  ContainerBaseProps
-} from './types';
-
-export {
-  isPaddingValue,
-  isBorderValue,
-  isBorderRadiusValue,
-  isLayeringValue,
-  isSemanticHTMLElement
-} from './types';
-
-// Export tokens
-export type { Platform, PlatformTokenMap } from './tokens';
-
-export {
-  paddingTokenMap,
-  borderTokenMap,
-  borderRadiusTokenMap,
-  layeringTokenMap,
-  getPaddingToken,
-  getBorderToken,
-  getBorderRadiusToken,
-  getLayeringToken,
-  BORDER_COLOR_TOKEN
-} from './tokens';

package/src/components/core/Container-Base/platforms/web/ContainerBase.web.ts

@@ -1,405 +0,0 @@
-/**
- * Container-Base Web Component
- * 
- * Stemma System naming: [Family]-[Type] = Container-Base
- * Type: Primitive (foundational component)
- * 
- * Web platform implementation using Custom Elements with Shadow DOM.
- * Provides style encapsulation and semantic HTML support.
- * 
- * Uses blend utilities for hover state colors instead of opacity workarounds.
- * This ensures cross-platform consistency with iOS and Android implementations.
- * 
- * @see ./README.md for complete documentation
- * @see .kiro/specs/010-container-component/design.md for complete design
- * @see .kiro/specs/034-component-architecture-system for Stemma System details
- * @see .kiro/specs/031-blend-infrastructure-implementation for blend utilities
- * @see Requirements 10.1, 11.1, 11.2
- */
-
-import { buildContainerBaseStyles } from './token-mapping';
-import type { 
-  PaddingValue, 
-  BorderValue, 
-  BorderRadiusValue, 
-  LayeringValue,
-  SemanticHTMLElement
-} from '../../types';
-import type { 
-  OpacityTokenName,
-  ColorTokenName,
-  ShadowTokenName
-} from '@3fn/core/types';
-// Import theme-aware blend utilities for hover state color calculations
-// Uses getBlendUtilities() factory for consistent state styling across components
-// @see Requirements: 11.1, 11.2, 11.3 - Theme-aware utilities
-import { getBlendUtilities, BlendUtilitiesResult } from '@3fn/core/blend';
-
-/**
- * Base styles for Container-Base component
- * 
- * These styles provide the foundation for Container-Base's visual appearance.
- * All token-based styling is applied via the buildContainerBaseStyles function.
- * 
- * Hover state uses blend utilities for cross-platform consistency:
- * - darkerBlend(color.surface, blend.hoverDarker) - 8% darker
- * 
- * @see styles.css for detailed documentation of each style rule
- */
-const BASE_STYLES = `
-  :host {
-    display: block;
-    box-sizing: border-box;
-  }
-  
-  .container-base {
-    box-sizing: border-box;
-    display: block;
-    width: 100%;
-    transition: background-color var(--motion-focus-transition-duration) var(--motion-focus-transition-easing);
-  }
-  
-  .container-base--hoverable:hover {
-    background-color: var(--_container-base-hover-bg, inherit);
-  }
-  
-  .container-base:focus {
-    outline: var(--border-emphasis) solid var(--color-action-primary);
-    outline-offset: var(--space-grouped-minimal);
-  }
-  
-  .container-base:focus:not(:focus-visible) {
-    outline: none;
-  }
-  
-  .container-base:focus-visible {
-    outline: var(--border-emphasis) solid var(--color-action-primary);
-    outline-offset: var(--space-grouped-minimal);
-  }
-  
-  @media (prefers-reduced-motion: reduce) {
-    .container-base {
-      transition: none !important;
-      animation: none !important;
-    }
-  }
-  
-  @media (prefers-contrast: high) {
-    .container-base {
-      border-width: var(--border-emphasis);
-    }
-  }
-  
-  @media print {
-    .container-base {
-      box-shadow: none !important;
-      -webkit-print-color-adjust: exact;
-      print-color-adjust: exact;
-    }
-  }
-`;
-
-/**
- * Container-Base web component class
- * 
- * Custom element that renders a container with design system token-based styling.
- * Uses Shadow DOM for style encapsulation and supports semantic HTML elements.
- * 
- * @example
- * ```html
- * <!-- Basic usage -->
- * <container-base padding="200" background="color.surface">
- *   <p>Content</p>
- * </container-base>
- * 
- * <!-- With multiple styling props -->
- * <container-base 
- *   padding="300"
- *   background="color.primary"
- *   shadow="shadow.container"
- *   border-radius="normal"
- *   layering="navigation"
- * >
- *   <p>Content</p>
- * </container-base>
- * 
- * <!-- Semantic HTML -->
- * <container-base semantic="article" accessibility-label="Blog post">
- *   <p>Content</p>
- * </container-base>
- * ```
- */
-export class ContainerBaseWeb extends HTMLElement {
-  private _shadowRoot: ShadowRoot;
-  
-  // Theme-aware blend utilities instance
-  // Uses getBlendUtilities() factory for consistent state styling
-  // @see Requirements: 11.1, 11.2, 11.3 - Theme-aware utilities
-  private _blendUtils: BlendUtilitiesResult;
-  
-  // Cached blend color for hover state
-  private _hoverColor: string = '';
-
-  /**
-   * Observed attributes for the custom element
-   * 
-   * These attributes trigger attributeChangedCallback when modified.
-   * Includes all Container-Base props that can be set via HTML attributes.
-   * 
-   * Directional padding attributes use kebab-case:
-   * - padding-vertical, padding-horizontal (axis props)
-   * - padding-block-start, padding-block-end (individual vertical edges)
-   * - padding-inline-start, padding-inline-end (individual horizontal edges)
-   */
-  static get observedAttributes(): string[] {
-    return [
-      'padding',
-      'padding-vertical',
-      'padding-horizontal',
-      'padding-block-start',
-      'padding-block-end',
-      'padding-inline-start',
-      'padding-inline-end',
-      'background',
-      'shadow',
-      'border',
-      'border-color',
-      'border-radius',
-      'opacity',
-      'layering',
-      'semantic',
-      'accessibility-label',
-      'hoverable'
-    ];
-  }
-
-  constructor() {
-    super();
-    // Attach Shadow DOM with open mode for style encapsulation
-    this._shadowRoot = this.attachShadow({ mode: 'open' });
-    
-    // Initialize theme-aware blend utilities
-    // Uses getBlendUtilities() factory for consistent state styling
-    // @see Requirements: 11.1, 11.2, 11.3 - Theme-aware utilities
-    this._blendUtils = getBlendUtilities();
-  }
-
-  /**
-   * Called when element is inserted into the DOM
-   * 
-   * Lifecycle method that triggers initial render.
-   * Calculates blend colors from CSS custom properties.
-   */
-  connectedCallback(): void {
-    this._calculateBlendColors();
-    this.render();
-  }
-  
-  /**
-   * Calculate blend colors from CSS custom properties.
-   * 
-   * Reads base colors from CSS custom properties and applies theme-aware blend
-   * utilities to generate hover state color.
-   * 
-   * Uses getBlendUtilities() factory functions instead of direct blend calculations
-   * for cross-platform consistency with iOS and Android implementations.
-   * 
-   * State color mappings:
-   * - Hover: darkerBlend(color.surface, blend.hoverDarker) - 8% darker
-   * 
-   * @see Requirements: 9.1 - Container hover state
-   * @see Requirements: 11.1, 11.2, 11.3 - Theme-aware utilities
-   */
-  private _calculateBlendColors(): void {
-    // Get computed styles to read CSS custom properties
-    const computedStyle = getComputedStyle(document.documentElement);
-    
-    // Get surface color from CSS custom properties for hover state
-    // Use background prop if set, otherwise default to surface color
-    const background = this.getAttribute('background');
-    let baseColor = '';
-    
-    if (background) {
-      // Convert token name to CSS custom property format
-      const cssVarName = `--${background.replace(/\./g, '-')}`;
-      baseColor = computedStyle.getPropertyValue(cssVarName).trim();
-    }
-    
-    // Fallback to surface color if no background or couldn't resolve
-    if (!baseColor) {
-      baseColor = computedStyle.getPropertyValue('--color-structure-surface').trim();
-    }
-    
-    // If still no color, use canvas color token (white100)
-    if (!baseColor) {
-      baseColor = computedStyle.getPropertyValue('--color-structure-canvas').trim();
-    }
-    
-    // If no color could be resolved from tokens, skip hover color calculation
-    // This follows the "fail loudly" philosophy - if tokens aren't loaded,
-    // the hover effect won't work, which is visible during development
-    if (!baseColor) {
-      console.warn('ContainerBase: All background color fallbacks failed. Hover effects will not work.');
-      this._hoverColor = '';
-      return;
-    }
-    
-    // Calculate hover color using theme-aware blend utilities
-    // Uses semantic convenience function from getBlendUtilities()
-    // @see Requirements: 9.1 - Hover uses darkerBlend(color.surface, blend.hoverDarker)
-    this._hoverColor = this._blendUtils.hoverColor(baseColor);
-  }
-
-  /**
-   * Called when an observed attribute changes
-   * 
-   * Triggers re-render when any observed attribute is modified.
-   * Recalculates blend colors when background changes.
-   * 
-   * @param name - Attribute name that changed
-   * @param oldValue - Previous attribute value
-   * @param newValue - New attribute value
-   */
-  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void {
-    // Only re-render if the value actually changed
-    if (oldValue !== newValue) {
-      // Recalculate blend colors if background changed
-      if (name === 'background') {
-        this._calculateBlendColors();
-      }
-      this.render();
-    }
-  }
-
-  /**
-   * Render the container with current attributes
-   * 
-   * Builds the Shadow DOM structure with:
-   * - Style element with token-based CSS
-   * - Semantic HTML element (or div by default)
-   * - Slot for child content
-   * - Hover state support via blend utilities
-   * 
-   * Directional padding uses CSS logical properties for RTL support:
-   * - padding-block, padding-inline for axis props
-   * - padding-block-start, padding-block-end, padding-inline-start, padding-inline-end for edges
-   */
-  private render(): void {
-    // Get attribute values - uniform padding
-    const padding = this.getAttribute('padding') as PaddingValue | null;
-    
-    // Get attribute values - directional padding (axis props)
-    const paddingVertical = this.getAttribute('padding-vertical') as PaddingValue | null;
-    const paddingHorizontal = this.getAttribute('padding-horizontal') as PaddingValue | null;
-    
-    // Get attribute values - directional padding (individual edges)
-    const paddingBlockStart = this.getAttribute('padding-block-start') as PaddingValue | null;
-    const paddingBlockEnd = this.getAttribute('padding-block-end') as PaddingValue | null;
-    const paddingInlineStart = this.getAttribute('padding-inline-start') as PaddingValue | null;
-    const paddingInlineEnd = this.getAttribute('padding-inline-end') as PaddingValue | null;
-    
-    // Get attribute values - visual styling
-    const background = this.getAttribute('background') as ColorTokenName | null;
-    const shadow = this.getAttribute('shadow') as ShadowTokenName | null;
-    const border = this.getAttribute('border') as BorderValue | null;
-    const borderColor = this.getAttribute('border-color') as ColorTokenName | null;
-    const borderRadius = this.getAttribute('border-radius') as BorderRadiusValue | null;
-    const opacity = this.getAttribute('opacity') as OpacityTokenName | null;
-    const layering = this.getAttribute('layering') as LayeringValue | null;
-    const semantic = (this.getAttribute('semantic') as SemanticHTMLElement) || 'div';
-    const accessibilityLabel = this.getAttribute('accessibility-label');
-    const hoverable = this.getAttribute('hoverable') === 'true';
-
-    // Build CSS styles from attributes
-    const styles = this.buildStyles({
-      padding,
-      paddingVertical,
-      paddingHorizontal,
-      paddingBlockStart,
-      paddingBlockEnd,
-      paddingInlineStart,
-      paddingInlineEnd,
-      background,
-      shadow,
-      border,
-      borderColor,
-      borderRadius,
-      opacity,
-      layering
-    });
-
-    // Build accessibility attributes
-    // Note: No need to escape - the browser automatically escapes attribute values
-    // when parsing HTML strings. Escaping would result in double-encoding.
-    const accessibilityAttrs = accessibilityLabel 
-      ? `aria-label="${accessibilityLabel.replace(/"/g, '&quot;')}"` 
-      : '';
-    
-    // Build class names including hoverable state
-    const containerClasses = ['container-base'];
-    if (hoverable) {
-      containerClasses.push('container-base--hoverable');
-    }
-    
-    // Generate blend color CSS custom property for hover state
-    // This is a component-specific calculated value (not a design token)
-    // Using _container-base prefix to distinguish from design token references
-    const hoverColorStyle = hoverable ? `--_container-base-hover-bg: ${this._hoverColor};` : '';
-
-    // Render Shadow DOM content
-    this._shadowRoot.innerHTML = `
-      <style>
-        ${BASE_STYLES}
-        
-        .container-base {
-          ${styles}
-        }
-      </style>
-      <${semantic} class="${containerClasses.join(' ')}" ${accessibilityAttrs} style="${hoverColorStyle}">
-        <slot></slot>
-      </${semantic}>
-    `;
-  }
-
-  /**
-   * Build CSS styles from component props
-   * 
-   * Maps prop values to CSS custom properties that reference design system tokens.
-   * Only includes styles for props that are actually set.
-   * 
-   * Uses the token-mapping module for consistent token-to-CSS conversion.
-   * Directional padding uses CSS logical properties for RTL support.
-   * 
-   * @param props - Object containing prop values
-   * @returns CSS string with token-based styles
-   */
-  private buildStyles(props: {
-    padding: PaddingValue | null;
-    paddingVertical: PaddingValue | null;
-    paddingHorizontal: PaddingValue | null;
-    paddingBlockStart: PaddingValue | null;
-    paddingBlockEnd: PaddingValue | null;
-    paddingInlineStart: PaddingValue | null;
-    paddingInlineEnd: PaddingValue | null;
-    background: ColorTokenName | null;
-    shadow: ShadowTokenName | null;
-    border: BorderValue | null;
-    borderColor: ColorTokenName | null;
-    borderRadius: BorderRadiusValue | null;
-    opacity: OpacityTokenName | null;
-    layering: LayeringValue | null;
-  }): string {
-    return buildContainerBaseStyles(props);
-  }
-
-}
-
-/**
- * Register the custom element
- * 
- * Defines the 'container-base' custom element that can be used in HTML.
- * Follows Stemma System naming convention (lowercase with hyphens).
- */
-if (!customElements.get('container-base')) {
-  customElements.define('container-base', ContainerBaseWeb);
-}

package/src/components/core/Container-Base/platforms/web/styles.css

@@ -1,198 +0,0 @@
-/**
- * Container-Base Web Component Styles
- * 
- * Stemma System naming: [Family]-[Type] = Container-Base
- * Type: Primitive (foundational component)
- * 
- * Base styles for the Container-Base web component using CSS custom properties
- * that reference design system tokens. These styles provide the foundation
- * for Container-Base's visual appearance across all web platforms.
- * 
- * @see .kiro/specs/010-container-component/design.md for complete design
- * @see .kiro/specs/034-component-architecture-system for Stemma System details
- * @see Requirements 10.1, 11.1
- */
-
-/**
- * Host element styles
- * 
- * The :host selector targets the custom element itself (container-base).
- * Sets display and box-sizing defaults for the container.
- */
-:host {
-  display: block;
-  box-sizing: border-box;
-}
-
-/**
- * Container-Base element styles
- * 
- * The .container-base class is applied to the semantic HTML element inside
- * the Shadow DOM. This is where all token-based styling is applied.
- * 
- * All styling uses CSS custom properties that reference design system tokens.
- * These custom properties are generated by the build system from semantic tokens.
- */
-.container-base {
-  /* Box model */
-  box-sizing: border-box;
-  
-  /* Default display behavior */
-  display: block;
-  
-  /* Ensure container takes full width by default */
-  width: 100%;
-  
-  /* Padding - Applied via token-mapping when padding prop is set */
-  /* Uses space.inset tokens: var(--space-inset-050) through var(--space-inset-400) */
-  
-  /* Background - Applied via token-mapping when background prop is set */
-  /* Uses color tokens: var(--color-structure-surface), var(--color-structure-canvas), etc. */
-  
-  /* Border - Applied via token-mapping when border prop is set */
-  /* Uses border tokens: var(--border-default), var(--border-emphasis), var(--border-heavy) */
-  /* Border color uses: var(--color-structure-border) */
-  
-  /* Border radius - Applied via token-mapping when borderRadius prop is set */
-  /* Uses radius tokens: var(--radius-050), var(--radius-100), var(--radius-200) */
-  
-  /* Shadow - Applied via token-mapping when shadow prop is set */
-  /* Uses shadow tokens: var(--shadow-container), var(--shadow-navigation), etc. */
-  
-  /* Opacity - Applied via token-mapping when opacity prop is set */
-  /* Uses opacity tokens: var(--opacity-subtle), var(--opacity-medium), etc. */
-  
-  /* Layering - Applied via token-mapping when layering prop is set */
-  /* Uses z-index tokens: var(--z-index-container), var(--z-index-navigation), etc. */
-}
-
-/**
- * Responsive behavior
- * 
- * Container-Base adapts to different viewport sizes while maintaining
- * token-based spacing relationships. The mathematical relationships
- * defined in tokens ensure consistent spacing across breakpoints.
- */
-
-/**
- * Small screens (mobile)
- * 
- * On small screens, containers may need tighter spacing to maximize
- * content area. However, token relationships are maintained.
- */
-@media (max-width: 640px) {
-  .container-base {
-    /* Container maintains token-based spacing */
-    /* Specific adjustments can be made via padding prop values */
-    /* Example: Use padding="100" (8px) instead of padding="200" (16px) on mobile */
-  }
-}
-
-/**
- * Medium screens (tablet)
- * 
- * Tablet screens typically use the default token values without adjustment.
- */
-@media (min-width: 641px) and (max-width: 1024px) {
-  .container-base {
-    /* Default token values work well for tablet screens */
-  }
-}
-
-/**
- * Large screens (desktop)
- * 
- * Desktop screens may benefit from more generous spacing.
- * Token relationships ensure spacing remains harmonious.
- */
-@media (min-width: 1025px) {
-  .container-base {
-    /* Container can use larger padding values on desktop */
-    /* Example: Use padding="300" (24px) or padding="400" (32px) */
-  }
-}
-
-/**
- * Focus styles
- * 
- * When container receives focus (e.g., when used as a focusable element),
- * provide clear visual feedback for accessibility.
- * 
- * Uses accessibility tokens for consistent focus indicators across components.
- * @see src/tokens/semantic/AccessibilityTokens.ts
- */
-.container-base:focus {
-  outline: var(--accessibility-focus-width) solid var(--accessibility-focus-color);
-  outline-offset: var(--accessibility-focus-offset);
-}
-
-/**
- * Focus visible (keyboard navigation)
- * 
- * Only show focus outline when navigating via keyboard, not mouse clicks.
- * This provides better UX while maintaining accessibility.
- */
-.container-base:focus:not(:focus-visible) {
-  outline: none;
-}
-
-.container-base:focus-visible {
-  outline: var(--accessibility-focus-width) solid var(--accessibility-focus-color);
-  outline-offset: var(--accessibility-focus-offset);
-}
-
-/**
- * Print styles
- * 
- * Optimize container appearance for print media.
- * Remove shadows and adjust colors for better print output.
- */
-@media print {
-  .container-base {
-    /* Remove shadows for print (they don't print well) */
-    box-shadow: none !important;
-    
-    /* Ensure backgrounds print if needed */
-    -webkit-print-color-adjust: exact;
-    print-color-adjust: exact;
-  }
-}
-
-/**
- * Reduced motion
- * 
- * Respect user's preference for reduced motion.
- * Disable any transitions or animations when prefers-reduced-motion is set.
- */
-@media (prefers-reduced-motion: reduce) {
-  .container-base {
-    transition: none !important;
-    animation: none !important;
-  }
-}
-
-/**
- * High contrast mode
- * 
- * Ensure container remains visible and usable in high contrast mode.
- * Borders become more prominent to maintain visual structure.
- */
-@media (prefers-contrast: high) {
-  .container-base {
-    /* Ensure borders are visible in high contrast mode */
-    border-width: 2px;
-  }
-}
-
-/**
- * Dark mode support
- * 
- * Container-Base automatically adapts to dark mode through token values.
- * The build system generates appropriate token values for dark mode,
- * so no additional CSS is needed here. Token references like
- * var(--color-structure-surface) automatically resolve to dark mode values.
- */
-@media (prefers-color-scheme: dark) {
-  /* Token values automatically adapt to dark mode */
-  /* No additional styles needed - handled by token system */
-}