@3fn/core 14.0.0 → 15.0.0

package/src/components/core/Badge-Label-Base/platforms/web/BadgeLabelBase.web.ts

@@ -1,340 +0,0 @@
-/**
- * Badge-Label-Base Component for Web Platform
- * 
- * Stemma System: Badge Family
- * Component Type: Type Primitive (Label)
- * Naming Convention: [Family]-[Type]-[Variant] = Badge-Label-Base
- * 
- * A read-only, non-interactive visual indicator for displaying categorization,
- * status, or metadata text. Follows True Native Architecture with build-time
- * platform separation.
- * 
- * Key Characteristics:
- * - Read-only: Display-only, no click/tap behavior
- * - Non-interactive: Not focusable, not in tab order
- * - Compact: Small footprint, designed for inline use
- * - Informational: Conveys status or metadata at a glance
- * 
- * Uses <icon-base> web component for icon rendering, following the same component
- * composition pattern as iOS and Android platforms.
- * 
- * @module Badge-Label-Base/platforms/web
- * @see Requirements: 1.1-1.10, 4.1, 4.2, 4.4, 4.5, 4.6, 4.8, 5.1
- * @see .kiro/specs/044-badge-base/design.md for design specification
- */
-
-/// <reference lib="dom" />
-
-import { BadgeLabelSize, BADGE_LABEL_DEFAULTS, BADGE_LABEL_SIZE_TOKENS } from '../../types';
-import { IconBaseName, IconBaseSize } from '../../../Icon-Base/types';
-// Import Icon-Base to ensure it's registered before BadgeLabelBase uses it
-import '../../../Icon-Base/platforms/web/IconBase.web';
-// Import component token for max-width
-import { getBadgeLabelMaxWidth } from '../../tokens';
-
-// Import CSS as string for browser bundle compatibility
-// The esbuild CSS-as-string plugin transforms this import into a JS string export
-import badgeStyles from './BadgeLabelBase.styles.css';
-
-/**
- * Badge-Label-Base Web Component
- * 
- * A native web component that renders a label badge with optional leading icon.
- * Uses Shadow DOM for style encapsulation and token-based styling via CSS
- * custom properties.
- * 
- * @remarks
- * - Uses Shadow DOM for style encapsulation
- * - Token-based styling via CSS custom properties
- * - Supports three size variants (sm, md, lg)
- * - Optional leading icon via Icon-Base integration
- * - Truncation with title attribute for full text access
- * - Non-interactive: no tabindex, no click handlers
- * - WCAG 2.1 AA compliant:
- *   - Color contrast 4.5:1 minimum
- *   - Text scaling support
- *   - Screen reader accessible
- * 
- * @example
- * ```html
- * <!-- Basic usage -->
- * <badge-label-base label="Draft"></badge-label-base>
- * 
- * <!-- With size variant -->
- * <badge-label-base label="Status" size="sm"></badge-label-base>
- * 
- * <!-- With icon -->
- * <badge-label-base label="Approved" icon="check" size="md"></badge-label-base>
- * 
- * <!-- With truncation -->
- * <badge-label-base label="Very long category name" truncate="true"></badge-label-base>
- * 
- * <!-- With test ID -->
- * <badge-label-base label="Draft" test-id="status-badge"></badge-label-base>
- * ```
- * 
- * @example
- * ```typescript
- * // Programmatic usage
- * const badge = document.createElement('badge-label-base') as BadgeLabelBase;
- * badge.label = 'Draft';
- * badge.size = 'md';
- * badge.icon = 'check';
- * document.body.appendChild(badge);
- * ```
- * 
- * @see Requirements: 1.1-1.10, 4.1, 4.2, 4.4, 4.5, 4.6, 4.8, 5.1
- */
-export class BadgeLabelBase extends HTMLElement {
-  private _shadowRoot: ShadowRoot;
-  
-  /**
-   * Observed attributes for automatic re-rendering on change.
-   * 
-   * When these attributes change, attributeChangedCallback is invoked.
-   */
-  static get observedAttributes(): string[] {
-    return ['label', 'size', 'icon', 'truncate', 'test-id'];
-  }
-  
-  constructor() {
-    super();
-    
-    // Attach shadow DOM for style encapsulation
-    // @see Requirement 5.1 - Web component with Shadow DOM
-    this._shadowRoot = this.attachShadow({ mode: 'open' });
-  }
-  
-  /**
-   * Called when the element is added to the DOM.
-   * 
-   * Performs initial render of the badge component.
-   */
-  connectedCallback(): void {
-    this.render();
-  }
-  
-  /**
-   * Called when an observed attribute changes.
-   * 
-   * Triggers re-render to reflect the new attribute value.
-   * Only re-renders if the element is connected to the DOM.
-   * 
-   * @param _name - Attribute name (unused, prefixed with underscore)
-   * @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 element is connected to the DOM
-    if (oldValue !== newValue && this.isConnected) {
-      this.render();
-    }
-  }
-  
-  // ============================================================================
-  // Property Getters/Setters
-  // ============================================================================
-  
-  /**
-   * Get the badge label text.
-   * 
-   * @returns Label text or empty string
-   * @see Requirement 1.1 - label prop renders text content
-   */
-  get label(): string {
-    return this.getAttribute('label') || '';
-  }
-  
-  /**
-   * Set the badge label text.
-   */
-  set label(value: string) {
-    this.setAttribute('label', value);
-  }
-  
-  /**
-   * Get the badge size variant.
-   * 
-   * @returns Size variant (defaults to 'md')
-   * @see Requirements 1.2, 1.3 - size prop with default
-   */
-  get size(): BadgeLabelSize {
-    const size = this.getAttribute('size');
-    return (size === 'sm' || size === 'md' || size === 'lg') ? size : BADGE_LABEL_DEFAULTS.size;
-  }
-  
-  /**
-   * Set the badge size variant.
-   */
-  set size(value: BadgeLabelSize) {
-    this.setAttribute('size', value);
-  }
-  
-  /**
-   * Get the icon name.
-   * 
-   * @returns Icon name or null
-   * @see Requirement 1.4 - optional leading icon
-   */
-  get icon(): IconBaseName | null {
-    return this.getAttribute('icon') as IconBaseName | null;
-  }
-  
-  /**
-   * Set the icon name.
-   */
-  set icon(value: IconBaseName | null) {
-    if (value) {
-      this.setAttribute('icon', value);
-    } else {
-      this.removeAttribute('icon');
-    }
-  }
-  
-  /**
-   * Get the truncation state.
-   * 
-   * @returns true if truncation enabled, false otherwise
-   * @see Requirements 1.5, 1.7 - truncate prop with default
-   */
-  get truncate(): boolean {
-    return this.getAttribute('truncate') === 'true';
-  }
-  
-  /**
-   * Set the truncation state.
-   */
-  set truncate(value: boolean) {
-    if (value) {
-      this.setAttribute('truncate', 'true');
-    } else {
-      this.removeAttribute('truncate');
-    }
-  }
-  
-  /**
-   * Get the test ID.
-   * 
-   * @returns Test ID or null
-   */
-  get testID(): string | null {
-    return this.getAttribute('test-id');
-  }
-  
-  /**
-   * Set the test ID.
-   */
-  set testID(value: string | null) {
-    if (value) {
-      this.setAttribute('test-id', value);
-    } else {
-      this.removeAttribute('test-id');
-    }
-  }
-  
-  // ============================================================================
-  // Rendering
-  // ============================================================================
-  
-  /**
-   * Render the component into shadow DOM.
-   * 
-   * Generates the badge structure with appropriate size, icon, and truncation.
-   * Uses external CSS file for token-based styling.
-   * 
-   * @see Requirements: 1.1-1.10, 4.1, 4.2, 4.4, 4.5, 4.6, 4.8, 5.1
-   */
-  private render(): void {
-    const label = this.label;
-    const size = this.size;
-    const icon = this.icon;
-    const truncate = this.truncate;
-    const testID = this.testID;
-    
-    // Get token values for this size
-    const sizeTokens = BADGE_LABEL_SIZE_TOKENS[size];
-    const iconSize = sizeTokens.iconSize as IconBaseSize;
-    
-    // Generate CSS classes
-    const badgeClasses = [
-      'badge-label',
-      `badge-label--${size}`,
-    ].join(' ');
-    
-    // Generate text classes
-    const textClasses = [
-      'badge-label__text',
-      truncate ? 'badge-label__text--truncate' : '',
-    ].filter(Boolean).join(' ');
-    
-    // Generate test ID attribute
-    const testIDAttr = testID ? ` data-testid="${this.escapeHtml(testID)}"` : '';
-    
-    // Generate title attribute for truncated text
-    // @see Requirement 1.6 - title attribute when truncated
-    const titleAttr = truncate ? ` title="${this.escapeHtml(label)}"` : '';
-    
-    // Generate icon HTML if icon is provided
-    // @see Requirement 1.4 - optional leading icon via Icon-Base
-    // @see Requirement 6.2 - icon marked as decorative (aria-hidden in Icon-Base)
-    const iconHTML = icon ? `
-      <span class="badge-label__icon" aria-hidden="true">
-        <icon-base name="${icon}" size="${iconSize}" color="inherit"></icon-base>
-      </span>
-    ` : '';
-    
-    // Get max-width from component token
-    const maxWidth = getBadgeLabelMaxWidth();
-    
-    // Render shadow DOM content
-    // @see Requirement 1.8 - non-interactive (no tabindex, no click handlers)
-    this._shadowRoot.innerHTML = `
-      <style>
-        :host {
-          display: inline-block;
-        }
-        /* Override max-width with component token value */
-        .badge-label__text--truncate {
-          max-width: ${maxWidth}px;
-        }
-        ${badgeStyles}
-      </style>
-      <span class="${badgeClasses}"${testIDAttr}${titleAttr}>
-        ${iconHTML}
-        <span class="${textClasses}">${this.escapeHtml(label)}</span>
-      </span>
-    `;
-  }
-  
-  /**
-   * Escape HTML entities to prevent XSS attacks.
-   * 
-   * @param str - String to escape
-   * @returns Escaped string safe for HTML insertion
-   */
-  private escapeHtml(str: string): string {
-    const htmlEntities: Record<string, string> = {
-      '&': '&amp;',
-      '<': '&lt;',
-      '>': '&gt;',
-      '"': '&quot;',
-      "'": '&#39;',
-    };
-    return str.replace(/[&<>"']/g, (char) => htmlEntities[char]);
-  }
-}
-
-/**
- * Register the custom element.
- * 
- * Makes <badge-label-base> available as a custom HTML element.
- */
-if (!customElements.get('badge-label-base')) {
-  customElements.define('badge-label-base', BadgeLabelBase);
-}
-
-/**
- * Default export for convenience.
- */
-export default BadgeLabelBase;
-

package/src/components/core/Badge-Label-Base/tokens.ts

@@ -1,80 +0,0 @@
-/**
- * Badge-Label-Base Component Token Definitions
- * 
- * Stemma System naming: [Family]-[Type]-[Variant] = Badge-Label-Base
- * Type: Primitive (foundational component)
- * 
- * Platform-agnostic token definitions for the Badge-Label-Base component.
- * Uses the defineComponentTokens() API to register tokens with the global
- * ComponentTokenRegistry for pipeline integration.
- * 
- * The build system generates platform-specific values from these definitions:
- * - Web: CSS custom properties (var(--badge-label-base-maxwidth))
- * - iOS: Swift constants (BadgeLabelBaseTokens.maxWidth)
- * - Android: Kotlin constants (BadgeLabelBaseTokens.maxWidth)
- * 
- * Token Relationships:
- * - badge-label-base.maxWidth (120px) uses family-conformant value (8 × 15)
- * 
- * @see .kiro/specs/044-badge-base/design.md for token consumption strategy
- * @see .kiro/specs/034-component-architecture-system for Stemma System details
- * @see .kiro/specs/037-component-token-generation-pipeline for pipeline integration
- * @see Requirements 4.8, 9.3, 9.4, 9.5 in .kiro/specs/044-badge-base/requirements.md
- */
-
-import { defineComponentTokens } from '../../../build/tokens';
-import { SPACING_BASE_VALUE } from '../../../tokens/SpacingTokens';
-
-/**
- * Badge-Label-Base component tokens defined using the hybrid authoring API.
- * 
- * Each token includes reasoning explaining why the token exists and its purpose
- * in the component.
- * 
- * Max-width token value:
- * - maxWidth: 120px (15 × base, family-conformant value)
- *   No primitive token exists at this scale, so we use a family-conformant value
- *   that follows the spacing family's mathematical pattern (BASE_VALUE × multiplier).
- * 
- * @see Requirements 4.8, 9.3, 9.4, 9.5 in .kiro/specs/044-badge-base/requirements.md
- */
-export const BadgeLabelBaseTokens = defineComponentTokens({
-  component: 'BadgeLabelBase',
-  family: 'spacing',
-  tokens: {
-    'maxWidth': {
-      value: SPACING_BASE_VALUE * 15, // 8 × 15 = 120px
-      reasoning: 'Maximum width for truncated badges; allows ~12-15 characters before ellipsis while maintaining compact badge appearance. Value follows spacing family pattern (8 × 15 = 120px) but exceeds standard spacing scale, requiring component-level definition.',
-    },
-  },
-});
-
-/**
- * Get Badge-Label-Base max-width value
- * 
- * @returns Max-width value in pixels (120)
- * 
- * @example
- * ```typescript
- * getBadgeLabelMaxWidth() // Returns 120
- * ```
- */
-export function getBadgeLabelMaxWidth(): number {
-  return BadgeLabelBaseTokens['maxWidth'];
-}
-
-/**
- * Token reference documentation for Badge-Label-Base max-width
- * 
- * Documents the mathematical derivation and family conformance.
- * Used for documentation and cross-referencing with the token system.
- */
-export const BadgeLabelBaseTokenReferences = {
-  /** Max-width uses family-conformant value: 8 × 15 = 120px */
-  maxWidth: {
-    value: 120,
-    derivation: 'SPACING_BASE_VALUE × 15 = 8 × 15 = 120',
-    familyConformant: true,
-    primitiveReference: null, // No primitive token at this scale
-  },
-} as const;

package/src/components/core/Badge-Label-Base/types.ts

@@ -1,148 +0,0 @@
-/**
- * Badge-Label-Base Type Definitions
- * 
- * Stemma System: Badge Family
- * Component Type: Type Primitive (Label)
- * Naming Convention: [Family]-[Type]-[Variant] = Badge-Label-Base
- * 
- * Provides type-safe props for the Badge-Label-Base component across all platforms.
- * Badge-Label-Base is a read-only, non-interactive visual indicator for displaying
- * categorization, status, or metadata text.
- * 
- * @module Badge-Label-Base/types
- * @see .kiro/specs/044-badge-base/design.md for design specification
- * @see Requirements 1.1-1.10 in .kiro/specs/044-badge-base/requirements.md
- */
-
-import { IconBaseName } from '../Icon-Base/types';
-
-/**
- * Badge size variants.
- * 
- * Each size maps to specific typography and spacing tokens:
- * - sm: typography.labelXs, space.inset.none (v), space.inset.050 (h), icon.size050
- * - md: typography.labelSm, space.inset.050 (v), space.inset.100 (h), icon.size075
- * - lg: typography.labelMd, space.inset.100 (v), space.inset.150 (h), icon.size100
- * 
- * @see Requirements 1.2, 1.3 in .kiro/specs/044-badge-base/requirements.md
- */
-export type BadgeLabelSize = 'sm' | 'md' | 'lg';
-
-/**
- * Default values for Badge-Label-Base props.
- * 
- * @see Requirements 1.3, 1.7 in .kiro/specs/044-badge-base/requirements.md
- */
-export const BADGE_LABEL_DEFAULTS = {
-  /** Default size variant */
-  size: 'md' as BadgeLabelSize,
-  /** Default truncation behavior */
-  truncate: false,
-} as const;
-
-/**
- * Token mappings for Badge-Label-Base sizes.
- * 
- * Maps size variants to their corresponding design tokens for typography,
- * spacing, and icon sizing.
- * 
- * @see Requirements 4.1, 4.4, 4.5, 4.6 in .kiro/specs/044-badge-base/requirements.md
- */
-export const BADGE_LABEL_SIZE_TOKENS = {
-  sm: {
-    typography: 'typography.labelXs',
-    paddingVertical: 'space.inset.none',
-    paddingHorizontal: 'space.inset.050',
-    iconSize: 13, // icon.size050
-    iconGap: 'space.grouped.minimal',
-  },
-  md: {
-    typography: 'typography.labelSm',
-    paddingVertical: 'space.inset.050',
-    paddingHorizontal: 'space.inset.100',
-    iconSize: 20, // icon.size075
-    iconGap: 'space.grouped.tight',
-  },
-  lg: {
-    typography: 'typography.labelMd',
-    paddingVertical: 'space.inset.100',
-    paddingHorizontal: 'space.inset.150',
-    iconSize: 24, // icon.size100
-    iconGap: 'space.grouped.tight',
-  },
-} as const;
-
-/**
- * Props interface for Badge-Label-Base component (platform-agnostic).
- * 
- * This interface defines the common API across all platforms (web, iOS, Android).
- * Platform-specific implementations may extend this interface with additional
- * platform-specific properties.
- * 
- * @see Requirements 1.1-1.10 in .kiro/specs/044-badge-base/requirements.md
- * 
- * @example
- * ```typescript
- * // Web usage
- * <badge-label-base label="Draft" size="md"></badge-label-base>
- * 
- * // With icon
- * <badge-label-base label="Status" icon="check" size="sm"></badge-label-base>
- * 
- * // With truncation
- * <badge-label-base label="Very long category name" truncate="true"></badge-label-base>
- * ```
- */
-export interface BadgeLabelBaseProps {
-  /**
-   * Badge text content (required).
-   * 
-   * The label text to display inside the badge.
-   * 
-   * @see Requirement 1.1 in .kiro/specs/044-badge-base/requirements.md
-   */
-  label: string;
-  
-  /**
-   * Size variant.
-   * 
-   * Determines typography, spacing, and icon size tokens applied.
-   * 
-   * @default 'md'
-   * @see Requirements 1.2, 1.3 in .kiro/specs/044-badge-base/requirements.md
-   */
-  size?: BadgeLabelSize;
-  
-  /**
-   * Optional leading icon.
-   * 
-   * When provided, renders an icon before the label text using Icon-Base.
-   * Icon size is automatically determined by badge size.
-   * Icon is marked as decorative (aria-hidden="true").
-   * 
-   * @see Requirements 1.4, 6.2 in .kiro/specs/044-badge-base/requirements.md
-   */
-  icon?: IconBaseName;
-  
-  /**
-   * Enable truncation at component-defined max-width.
-   * 
-   * When true, text is truncated with ellipsis at badge.label.maxWidth (120px).
-   * Full text is accessible via title attribute (web) or accessibility label (native).
-   * 
-   * @default false
-   * @see Requirements 1.5, 1.6, 1.7, 4.8 in .kiro/specs/044-badge-base/requirements.md
-   */
-  truncate?: boolean;
-  
-  /**
-   * Optional test ID for automated testing.
-   * 
-   * Used to identify badges in automated tests across all platforms:
-   * - Web: data-testid attribute
-   * - iOS: accessibilityIdentifier
-   * - Android: testTag
-   */
-  testID?: string;
-}
-

package/src/components/core/Button-CTA/Button-CTA.tokens.ts

@@ -1,79 +0,0 @@
-/**
- * Button-CTA Component Tokens
- * 
- * Component-specific tokens for Button-CTA that don't fit into the general
- * semantic token system. These tokens are specific to button sizing and layout.
- * 
- * Token Naming Pattern: buttonCTA.[property].[variant]
- * 
- * Stemma System Naming: [Family]-[Type] = Button-CTA
- * Component Type: Standalone (no behavioral variants)
- * 
- * Related Requirements:
- * - Requirement 6.1-6.3: Minimum width requirements for button sizes
- * - Design Decision H3: Component-specific tokens with semantic naming
- */
-
-/**
- * Minimum Width Tokens
- * 
- * These tokens define the minimum width for each button size variant.
- * Values are chosen to ensure buttons have adequate touch targets and
- * visual presence while maintaining compositional architecture principles.
- * 
- * Design Rationale (from H3):
- * - Component-specific tokens provide clarity for button sizing
- * - Semantic naming (small/medium/large) balances component needs with system conventions
- * - Values don't need to align with existing primitive tokens (space700, space900, space1000)
- * - Compositional architecture maintained through mathematical relationships
- * 
- * Values:
- * - Small: 56px (7 × 8px baseline grid)
- * - Medium: 72px (9 × 8px baseline grid)
- * - Large: 80px (10 × 8px baseline grid, aligns with space1000)
- */
-export const ButtonCTATokens = {
-  /**
-   * Minimum width for small buttons
-   * 
-   * Usage: Small buttons in compact layouts, secondary actions
-   * Value: 56px (7 × 8px baseline grid)
-   * Platforms: Web, iOS, Android
-   */
-  minWidth: {
-    small: 56,
-    
-    /**
-     * Minimum width for medium buttons
-     * 
-     * Usage: Standard buttons, primary actions
-     * Value: 72px (9 × 8px baseline grid)
-     * Platforms: Web, iOS, Android
-     */
-    medium: 72,
-    
-    /**
-     * Minimum width for large buttons
-     * 
-     * Usage: Prominent buttons, hero actions
-     * Value: 80px (10 × 8px baseline grid, aligns with space1000)
-     * Platforms: Web, iOS, Android
-     */
-    large: 80,
-  },
-} as const;
-
-/**
- * Type definitions for Button-CTA tokens
- */
-export type ButtonCTAMinWidthVariant = keyof typeof ButtonCTATokens.minWidth;
-
-/**
- * Helper function to get minWidth token value
- * 
- * @param variant - The button size variant (small, medium, large)
- * @returns The minimum width value in pixels
- */
-export function getButtonCTAMinWidth(variant: ButtonCTAMinWidthVariant): number {
-  return ButtonCTATokens.minWidth[variant];
-}