@3fn/core 14.1.0 → 15.0.0

package/src/components/core/Input-Text-Base/tokens.ts

@@ -1,210 +0,0 @@
-/**
- * Input-Text-Base Component Token References
- * 
- * Platform-agnostic token references for the Input-Text-Base component.
- * These references will be resolved to platform-specific values by the build system.
- * 
- * Stemma System: Form Inputs Family
- * Component Type: Primitive (Base)
- * Naming Convention: [Family]-[Type]-[Variant] = Input-Text-Base
- * 
- * This file defines WHICH tokens the component uses, not HOW they're implemented per platform.
- * The build system generates platform-specific values (CSS custom properties, Swift constants, Kotlin constants).
- * 
- * Token Selection Rationale:
- * - Typography: Uses labelMd/labelMdFloat for label animation, input for text, caption for helper/error
- * - Color: Uses semantic color tokens for text, borders, and backgrounds with state variations
- * - Spacing: Uses inset tokens for padding, grouped tokens for element spacing
- * - Motion: Uses motion.floatLabel semantic token for label animation timing
- * - Border: Uses borderDefault for standard border, radius150 for rounded corners
- * - Accessibility: Uses focus tokens for keyboard navigation indicators, tapAreaComfortable for touch targets
- * - Blend: Uses focusSaturate for enhanced focus state emphasis
- */
-
-/**
- * Typography token references for Input-Text-Base
- * 
- * All typography tokens reference semantic typography tokens that combine
- * fontSize, lineHeight, fontFamily, fontWeight, and letterSpacing primitives.
- */
-export const typographyTokens = {
-  /** Label typography when inside input (16px) */
-  label: 'typography.labelMd',
-  
-  /** Label typography when floated above input (14px, via scale088 × fontSize100) */
-  labelFloat: 'typography.labelMdFloat',
-  
-  /** Input text typography (16px) */
-  input: 'typography.input',
-  
-  /** Helper text typography (13px) */
-  helper: 'typography.caption',
-  
-  /** Error message typography (13px) */
-  error: 'typography.caption'
-} as const;
-
-/**
- * Color token references for Input-Text-Base
- * 
- * All color tokens reference semantic color tokens that provide contextual meaning
- * and support light/dark mode theming.
- */
-export const colorTokens = {
-  /** Label color when not focused */
-  labelDefault: 'color.text.muted',
-  
-  /** Label color when focused (enhanced with blend.focusSaturate) */
-  labelFocused: 'color.primary',
-  
-  /** Label color in error state */
-  labelError: 'color.error',
-  
-  /** Label color in success state */
-  labelSuccess: 'color.success.strong',
-  
-  /** Input text color */
-  inputText: 'color.text.default',
-  
-  /** Helper text color */
-  helperText: 'color.text.muted',
-  
-  /** Error message color */
-  errorText: 'color.error',
-  
-  /** Border color when not focused */
-  borderDefault: 'color.border',
-  
-  /** Border color when focused (enhanced with blend.focusSaturate) */
-  borderFocused: 'color.primary',
-  
-  /** Border color in error state */
-  borderError: 'color.error',
-  
-  /** Border color in success state */
-  borderSuccess: 'color.success.strong',
-  
-  /** Input background color (supports future tint variations) */
-  background: 'color.background',
-  
-  /** Focus ring color for keyboard navigation */
-  focusRing: 'accessibility.focus.color'
-} as const;
-
-/**
- * Spacing token references for Input-Text-Base
- * 
- * Uses inset tokens for internal padding and grouped tokens for element spacing.
- * Asymmetric vertical padding: larger top padding for floated label clearance,
- * no bottom padding since input text sits at the bottom of the input box.
- */
-export const spacingTokens = {
-  /** Input top padding (16px) - provides clearance for floated label */
-  inputPaddingTop: 'space.inset.200',
-  
-  /** Input bottom padding (0px) - input text sits at bottom */
-  inputPaddingBottom: 'space.inset.none',
-  
-  /** Input horizontal padding (8px) */
-  inputPaddingHorizontal: 'space.inset.100',
-  
-  /** Space between floated label and input - 4px */
-  labelOffset: 'space.grouped.tight',
-  
-  /** Space between input and helper text - 2px */
-  helperOffset: 'space.grouped.minimal',
-  
-  /** Space between helper text and error message - 2px */
-  errorOffset: 'space.grouped.minimal'
-} as const;
-
-/**
- * Motion token references for Input-Text-Base
- * 
- * Uses motion.floatLabel semantic token for label animation timing and scale088 for typography scaling.
- */
-export const motionTokens = {
-  /** Label float animation timing (duration250 + easingStandard) */
-  labelFloat: 'motion.floatLabel',
-  
-  /** Icon fade animation timing (reuses labelFloat for coordination) */
-  iconFade: 'motion.floatLabel',
-  
-  /** Typography scale for label animation (0.88 × fontSize100 = 14px) */
-  scale: 'scale088'
-} as const;
-
-/**
- * Border token references for Input-Text-Base
- * 
- * Uses borderDefault for standard border width and radius150 for rounded corners.
- */
-export const borderTokens = {
-  /** Border width (1px) */
-  width: 'borderDefault',
-  
-  /** Border radius (12px) */
-  radius: 'radius150'
-} as const;
-
-/**
- * Accessibility token references for Input-Text-Base
- * 
- * Uses accessibility.focus tokens for keyboard navigation indicators and tapAreaComfortable for touch targets.
- */
-export const accessibilityTokens = {
-  /** Minimum touch target height (56px) for comfortable interaction */
-  minHeight: 'tapAreaComfortable',
-  
-  /** Focus ring width (2px) */
-  focusWidth: 'accessibility.focus.width',
-  
-  /** Focus ring offset (2px) */
-  focusOffset: 'accessibility.focus.offset',
-  
-  /** Focus ring color (primary) */
-  focusColor: 'accessibility.focus.color'
-} as const;
-
-/**
- * Blend token references for Input-Text-Base
- * 
- * Uses blend.focusSaturate for enhanced focus state emphasis.
- */
-export const blendTokens = {
-  /** Focus state emphasis (8% more saturated) */
-  focusSaturate: 'blend.focusSaturate'
-} as const;
-
-/**
- * Complete Input-Text-Base token references
- * 
- * Exports all token categories for easy import and usage.
- */
-export const inputTextBaseTokens = {
-  typography: typographyTokens,
-  color: colorTokens,
-  spacing: spacingTokens,
-  motion: motionTokens,
-  border: borderTokens,
-  accessibility: accessibilityTokens,
-  blend: blendTokens
-} as const;
-
-/**
- * Type definitions for token references
- */
-export type TypographyTokens = typeof typographyTokens;
-export type ColorTokens = typeof colorTokens;
-export type SpacingTokens = typeof spacingTokens;
-export type MotionTokens = typeof motionTokens;
-export type BorderTokens = typeof borderTokens;
-export type AccessibilityTokens = typeof accessibilityTokens;
-export type BlendTokens = typeof blendTokens;
-export type InputTextBaseTokens = typeof inputTextBaseTokens;
-
-// Legacy exports for backward compatibility during migration
-/** @deprecated Use inputTextBaseTokens instead */
-export const textInputFieldTokens = inputTextBaseTokens;
-/** @deprecated Use InputTextBaseTokens instead */
-export type TextInputFieldTokens = InputTextBaseTokens;

package/src/components/core/Input-Text-Base/types.ts

@@ -1,114 +0,0 @@
-/**
- * Input-Text-Base Component Types
- * 
- * Defines the public API and internal state interfaces for the Input-Text-Base component
- * across all platforms (web, iOS, Android).
- * 
- * Stemma System: Form Inputs Family
- * Component Type: Primitive (Base)
- * Naming Convention: [Family]-[Type]-[Variant] = Input-Text-Base
- */
-
-/**
- * Input-Text-Base Component Props
- * 
- * Defines the public API for the Input-Text-Base component across all platforms.
- */
-export interface InputTextBaseProps {
-  /** Unique identifier for the input element */
-  id: string;
-  
-  /** Label text (floats between placeholder and floated positions) */
-  label: string;
-  
-  /** Current input value */
-  value: string;
-  
-  /** Callback when value changes */
-  onChange: (value: string) => void;
-  
-  /** Callback when input receives focus */
-  onFocus?: () => void;
-  
-  /** Callback when input loses focus */
-  onBlur?: () => void;
-  
-  /** Helper text displayed below input (persistent) */
-  helperText?: string;
-  
-  /** Error message displayed below helper text (conditional) */
-  errorMessage?: string;
-  
-  /** Success state indicator (shows success icon) */
-  isSuccess?: boolean;
-  
-  /** Info icon support (shows info icon, triggers helper text) */
-  showInfoIcon?: boolean;
-  
-  /** Input type (text, email, password, etc.) */
-  type?: 'text' | 'email' | 'password' | 'tel' | 'url';
-  
-  /** Autocomplete attribute for browser autofill */
-  autocomplete?: string;
-  
-  /** Placeholder text (only shown when label is floated and input is empty) */
-  placeholder?: string;
-  
-  /**
-   * Read-only state (state_readonly contract): the value is displayed
-   * non-editably while remaining perceivable, selectable, and copyable —
-   * never rendered with disabled semantics on any platform.
-   *
-   * Platform note: web and Android readOnly fields participate in keyboard
-   * focus order; iOS renders readOnly as selectable static text in the
-   * field chrome and is not in focus order (declared carve-out — see
-   * contracts.yaml interaction_focusable).
-   *
-   * NOT supported by Input-Text-Password: readOnly is contracted out of the
-   * Password variant (see its contracts.yaml excludes) and is ignored there.
-   */
-  readOnly?: boolean;
-  
-  /** Required field indicator */
-  required?: boolean;
-  
-  /** Maximum length for input value */
-  maxLength?: number;
-  
-  /** Test ID for automated testing */
-  testID?: string;
-  
-  /** Additional CSS class names (web only) */
-  className?: string;
-}
-
-/**
- * Input-Text-Base State
- * 
- * Internal state management for component behavior.
- */
-export interface InputTextBaseState {
-  /** Whether input currently has focus */
-  isFocused: boolean;
-  
-  /** Whether input has content (determines label position) */
-  isFilled: boolean;
-  
-  /** Whether input is in error state */
-  hasError: boolean;
-  
-  /** Whether input is in success state */
-  isSuccess: boolean;
-  
-  /** Whether label should be in floated position */
-  isLabelFloated: boolean;
-  
-  /** Whether info icon should be shown (from props) */
-  showInfoIcon?: boolean;
-}
-
-// Legacy type aliases for backward compatibility during migration
-/** @deprecated Use InputTextBaseProps instead */
-export type TextInputFieldProps = InputTextBaseProps;
-/** @deprecated Use InputTextBaseState instead */
-export type TextInputFieldState = InputTextBaseState;

package/src/components/core/Input-Text-Email/README.md

@@ -1,252 +0,0 @@
-# Input-Text-Email Component
-
-**Stemma System**: Form Inputs Family  
-**Component Type**: Semantic (inherits from Input-Text-Base)  
-**Naming Convention**: [Family]-[Type]-[Variant] = Input-Text-Email  
-**Readiness**: Production Ready 🟢
-
-## Overview
-
-Input-Text-Email is a semantic text input component that extends Input-Text-Base with email-specific validation and autocomplete functionality. It validates email format on blur using an RFC 5322 compliant pattern and enables browser/platform email autofill.
-
-## Features
-
-- **Inherits all Input-Text-Base features**: Float label animation, validation states, accessibility, etc.
-- **Email format validation**: RFC 5322 compliant validation on blur
-- **Email autocomplete**: Browser/platform email autofill support
-- **Email keyboard**: Shows email keyboard on mobile platforms
-- **Custom validation**: Support for custom validation functions
-- **Cross-platform**: Consistent behavior across web, iOS, and Android
-
-## Usage
-
-### Web
-
-```html
-<input-text-email
-  id="email-input"
-  label="Email Address"
-  value=""
-  helper-text="Enter your email address"
-  required
-></input-text-email>
-```
-
-```javascript
-// Listen for validation events
-const emailInput = document.querySelector('input-text-email');
-emailInput.addEventListener('validate', (e) => {
-  console.log('Valid:', e.detail.isValid);
-  console.log('Error:', e.detail.errorMessage);
-});
-
-// Programmatic validation
-const result = emailInput.validate();
-console.log(result.isValid, result.errorMessage);
-```
-
-### iOS (SwiftUI)
-
-```swift
-@State private var email = ""
-
-InputTextEmail(
-    id: "email-input",
-    label: "Email Address",
-    value: $email,
-    helperText: "Enter your email address",
-    required: true,
-    onValidate: { isValid, errorMessage in
-        print("Valid: \(isValid), Error: \(errorMessage ?? "none")")
-    }
-)
-```
-
-### Android (Jetpack Compose)
-
-```kotlin
-var email by remember { mutableStateOf("") }
-
-InputTextEmail(
-    id = "email-input",
-    label = "Email Address",
-    value = email,
-    onValueChange = { email = it },
-    helperText = "Enter your email address",
-    required = true,
-    onValidate = { isValid, errorMessage ->
-        println("Valid: $isValid, Error: $errorMessage")
-    }
-)
-```
-
-## Props
-
-### Inherited from Input-Text-Base
-
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `id` | string | Yes | - | Unique identifier for the input |
-| `label` | string | Yes | - | Label text (floats on focus/fill) |
-| `value` | string | Yes | - | Current input value |
-| `onChange` | function | Yes | - | Callback when value changes |
-| `onFocus` | function | No | - | Callback when input receives focus |
-| `onBlur` | function | No | - | Callback when input loses focus |
-| `helperText` | string | No | - | Helper text below input |
-| `errorMessage` | string | No | - | Error message (overrides validation error) |
-| `isSuccess` | boolean | No | false | Success state indicator |
-| `showInfoIcon` | boolean | No | false | Show info icon |
-| `placeholder` | string | No | - | Placeholder text |
-| `readOnly` | boolean | No | false | Read-only display state (`state_readonly` contract): value is non-editable but selectable and copyable; no keyboard raised; iOS renders selectable text in the field chrome |
-| `required` | boolean | No | false | Required field indicator |
-| `maxLength` | number | No | - | Maximum input length |
-| `testID` | string | No | - | Test ID for automation |
-
-### Email-Specific Props
-
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `customValidator` | function | No | - | Custom validation function |
-| `invalidEmailMessage` | string | No | "Please enter a valid email address" | Custom error message |
-| `onValidate` | function | No | - | Callback when validation occurs |
-
-### Fixed Props
-
-| Prop | Value | Description |
-|------|-------|-------------|
-| `type` | "email" | Input type is fixed to email |
-| `autocomplete` | "email" | Autocomplete is fixed to email |
-
-## Behavioral Contracts
-
-### Inherited from Input-Text-Base
-
-1. **focusable**: Can receive keyboard focus
-2. **float_label_animation**: Label animates on focus
-3. **validates_on_blur**: Validation triggers on blur
-4. **error_state_display**: Shows error message and styling
-5. **success_state_display**: Shows success styling
-6. **trailing_icon_display**: Shows contextual trailing icons
-7. **focus_ring**: WCAG 2.4.7 focus visible indicator
-8. **reduced_motion_support**: Respects prefers-reduced-motion
-
-**Excluded**: `state_disabled` — DesignerPunk does not support disabled states for usability and accessibility reasons. If an action is unavailable, the component should not be rendered (adjudicated 2026-07-15).
-
-### Email-Specific Contracts
-
-9. **validates_email_format**: Validates email against RFC 5322 pattern
-10. **provides_email_autocomplete**: Enables browser/platform email autofill
-
-## Validation
-
-### Default Validation
-
-The component uses an RFC 5322 compliant regex pattern for email validation:
-
-```
-^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$
-```
-
-**Valid examples:**
-- `user@example.com`
-- `user.name@example.co.uk`
-- `user+tag@example.org`
-
-**Invalid examples:**
-- `invalid-email`
-- `@example.com`
-- `user@`
-
-### Custom Validation
-
-You can provide a custom validation function:
-
-```javascript
-// Web
-<input-text-email
-  id="email"
-  label="Work Email"
-  custom-validator="validateWorkEmail"
-></input-text-email>
-
-<script>
-function validateWorkEmail(email) {
-  return email.endsWith('@company.com');
-}
-</script>
-```
-
-```swift
-// iOS
-InputTextEmail(
-    id: "email",
-    label: "Work Email",
-    value: $email,
-    customValidator: { email in
-        email.hasSuffix("@company.com")
-    }
-)
-```
-
-```kotlin
-// Android
-InputTextEmail(
-    id = "email",
-    label = "Work Email",
-    value = email,
-    onValueChange = { email = it },
-    customValidator = { it.endsWith("@company.com") }
-)
-```
-
-## Accessibility
-
-- **WCAG 2.1 AA compliant**
-- **1.3.5 Identify Input Purpose**: Email autocomplete enabled
-- **3.3.1 Error Identification**: Clear error messages for invalid emails
-- **Keyboard accessible**: Full keyboard navigation support
-- **Screen reader support**: Proper ARIA attributes and announcements
-
-## Platform-Specific Notes
-
-### Web
-- Uses `<input type="email">` for native email validation hints
-- Sets `autocomplete="email"` for browser autofill
-- Shows email keyboard on mobile browsers
-
-### iOS
-- Uses `UIKeyboardType.emailAddress` for email keyboard
-- Sets `UITextContentType.emailAddress` for autofill
-- Integrates with iOS password/email autofill
-
-### Android
-- Uses `KeyboardType.Email` for email keyboard
-- Integrates with Android Autofill framework
-- Supports Material Design patterns
-
-## Related Components
-
-- **Input-Text-Base**: Parent primitive component
-- **Input-Text-Password**: Sibling semantic component for passwords
-- **Input-Text-PhoneNumber**: Sibling semantic component for phone numbers
-
-## Files
-
-```
-src/components/core/Input-Text-Email/
-├── Input-Text-Email.schema.yaml    # Component schema
-├── README.md                        # This documentation
-├── types.ts                         # TypeScript types
-├── validation.ts                    # Email validation logic
-├── stateManagement.ts               # State management
-├── tokens.ts                        # Token references
-└── platforms/
-    ├── web/
-    │   ├── InputTextEmail.web.ts    # Web component
-    │   └── InputTextEmail.browser.ts # Browser build
-    ├── ios/
-    │   └── InputTextEmail.ios.swift # SwiftUI view
-    └── android/
-        └── InputTextEmail.android.kt # Compose composable
-```
-

package/src/components/core/Input-Text-Email/__tests__/validation.test.ts

@@ -1,127 +0,0 @@
-/**
- * Input-Text-Email Validation Tests
- * 
- * Tests for email validation logic.
- * 
- * Stemma System: Form Inputs Family
- * Component Type: Semantic (inherits from Input-Text-Base)
- */
-
-import { isValidEmail, validateEmail, normalizeEmail, DEFAULT_INVALID_EMAIL_MESSAGE } from '../validation';
-
-describe('Input-Text-Email Validation', () => {
-  describe('isValidEmail', () => {
-    describe('valid emails', () => {
-      const validEmails = [
-        'user@example.com',
-        'user.name@example.com',
-        'user+tag@example.com',
-        'user@example.co.uk',
-        'user@subdomain.example.com',
-        'user123@example.com',
-        'user_name@example.com',
-        'user-name@example.com',
-        'USER@EXAMPLE.COM',
-        'user@123.123.123.123',
-        "user!#$%&'*+/=?^_`{|}~-@example.com",
-      ];
-
-      validEmails.forEach((email) => {
-        it(`should accept valid email: ${email}`, () => {
-          expect(isValidEmail(email)).toBe(true);
-        });
-      });
-    });
-
-    describe('invalid emails', () => {
-      const invalidEmails = [
-        'invalid-email',
-        '@example.com',
-        'user@',
-        'user@.com',
-        'user@example.',
-        'user @example.com',
-        'user@ example.com',
-        'user@example .com',
-        'user@@example.com',
-        '.user@example.com',
-        'user.@example.com',
-        'user..name@example.com',
-      ];
-
-      invalidEmails.forEach((email) => {
-        it(`should reject invalid email: ${email}`, () => {
-          expect(isValidEmail(email)).toBe(false);
-        });
-      });
-    });
-
-    describe('edge cases', () => {
-      it('should accept empty string (use required for empty validation)', () => {
-        expect(isValidEmail('')).toBe(true);
-      });
-
-      it('should accept whitespace-only string (trimmed to empty)', () => {
-        expect(isValidEmail('   ')).toBe(true);
-      });
-
-      it('should trim whitespace before validation', () => {
-        expect(isValidEmail('  user@example.com  ')).toBe(true);
-      });
-    });
-  });
-
-  describe('validateEmail', () => {
-    it('should return valid result for valid email', () => {
-      const result = validateEmail('user@example.com');
-      expect(result.isValid).toBe(true);
-      expect(result.errorMessage).toBeUndefined();
-    });
-
-    it('should return invalid result with default message for invalid email', () => {
-      const result = validateEmail('invalid-email');
-      expect(result.isValid).toBe(false);
-      expect(result.errorMessage).toBe(DEFAULT_INVALID_EMAIL_MESSAGE);
-    });
-
-    it('should return invalid result with custom message', () => {
-      const customMessage = 'Custom error message';
-      const result = validateEmail('invalid-email', undefined, customMessage);
-      expect(result.isValid).toBe(false);
-      expect(result.errorMessage).toBe(customMessage);
-    });
-
-    it('should use custom validator when provided', () => {
-      const customValidator = (email: string) => email.endsWith('@company.com');
-      
-      // Valid with custom validator
-      const validResult = validateEmail('user@company.com', customValidator);
-      expect(validResult.isValid).toBe(true);
-      
-      // Invalid with custom validator (but valid email format)
-      const invalidResult = validateEmail('user@example.com', customValidator);
-      expect(invalidResult.isValid).toBe(false);
-    });
-
-    it('should return valid for empty string', () => {
-      const result = validateEmail('');
-      expect(result.isValid).toBe(true);
-      expect(result.errorMessage).toBeUndefined();
-    });
-  });
-
-  describe('normalizeEmail', () => {
-    it('should trim whitespace', () => {
-      expect(normalizeEmail('  user@example.com  ')).toBe('user@example.com');
-    });
-
-    it('should convert to lowercase', () => {
-      expect(normalizeEmail('USER@EXAMPLE.COM')).toBe('user@example.com');
-    });
-
-    it('should handle mixed case and whitespace', () => {
-      expect(normalizeEmail('  User@Example.COM  ')).toBe('user@example.com');
-    });
-  });
-});
-