npm - @3fn/core - Versions diffs - 14.1.0 → 15.0.0 - Mend

@3fn/core 14.1.0 → 15.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1380) hide show

package/src/components/core/Button-CTA/README.md DELETED Viewed

@@ -1,293 +0,0 @@
-# Button-CTA Component
-**Stemma System**: Buttons Family
-**Component Type**: Standalone (no behavioral variants)
-**Readiness**: 🟢 Production Ready
-**Version**: 1.1.0
----
-## Overview
-The Button-CTA (Call-to-Action Button) component is a cross-platform button following True Native Architecture with build-time platform separation. It provides three size variants, three visual variants (via `variant` prop), and comprehensive interaction states while maintaining WCAG 2.1 AA accessibility compliance.
-**Stemma System Naming**: This component follows the `[Family]-[Type]` naming convention for standalone components:
-- **Family**: Button
-- **Type**: CTA (Call-to-Action)
-**Why No Variant Suffix?**: Button-CTA has no behavioral variants - only styling variations handled via the `variant` prop (primary/secondary/tertiary). The `-Primary` suffix was removed as it implied other behavioral variants exist when they don't.
----
-## Key Features
-- ✅ Token-based styling (zero hard-coded values)
-- ✅ Three size variants (small, medium, large)
-- ✅ Three visual variants via `variant` prop (primary, secondary, tertiary)
-- ✅ Optional leading icons with optical weight compensation
-- ✅ Platform-specific interaction patterns
-- ✅ WCAG 2.1 AA accessibility compliance
-- ✅ True Native Architecture (separate implementations per platform)
----
-## Behavioral Contracts
-This component guarantees 7 behavioral contracts across all platforms:
-| Contract | Description | Platforms | WCAG |
-|----------|-------------|-----------|------|
-| `focusable` | Can receive keyboard focus | web, ios, android | 2.1.1, 2.4.7 |
-| `pressable` | Responds to press/click events | web, ios, android | 2.1.1 |
-| `hover_state` | Visual feedback on hover | web | 1.4.13 |
-| `pressed_state` | Visual feedback when pressed | web, ios, android | 2.4.7 |
-| `loading_state` | Shows loading indicator | web, ios, android | 4.1.3 |
-| `focus_ring` | WCAG 2.4.7 focus visible indicator | web, ios, android | 2.4.7 |
-**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).
----
-## Usage
-### HTML Custom Element
-```html
-<!-- Basic usage -->
-<button-cta label="Click me"></button-cta>
-<!-- With all attributes -->
-<button-cta
-  label="Submit Form"
-  size="large"
-  variant="primary"
-  icon="arrow-right"
-  no-wrap="false"
-  test-id="submit-button"
-></button-cta>
-```
-### JavaScript/TypeScript
-```typescript
-import { ButtonCTA } from './platforms/web/ButtonCTA.web';
-// Programmatic usage
-const button = document.createElement('button-cta') as ButtonCTA;
-button.label = 'Click me';
-button.size = 'large';
-button.addEventListener('press', () => console.log('Clicked'));
-document.body.appendChild(button);
-```
-### iOS (SwiftUI)
-```swift
-import DesignerPunk
-ButtonCTA(
-    label: "Submit",
-    size: .large,
-    variant: .primary,
-    icon: "arrow-right"
-) {
-    handleSubmit()
-}
-```
-### Android (Jetpack Compose)
-```kotlin
-import com.designerpunk.components
-ButtonCTA(
-    label = "Submit",
-    size = ButtonSize.Large,
-    variant = ButtonVariant.Primary,
-    icon = "arrow-right",
-    onPress = { handleSubmit() }
-)
-```
----
-## API Reference
-### Properties
-| Property | Type | Required | Default | Description |
-|----------|------|----------|---------|-------------|
-| `label` | `string` | ✅ Yes | - | Button text label |
-| `size` | `'small' \| 'medium' \| 'large'` | No | `'medium'` | Button size variant |
-| `variant` | `'primary' \| 'secondary' \| 'tertiary'` | No | `'primary'` | Button visual variant |
-| `icon` | `IconName` | No | - | Optional leading icon |
-| `noWrap` | `boolean` | No | `false` | Prevent text wrapping |
-| `onPress` | `() => void` | ✅ Yes | - | Press/click handler |
-| `testID` | `string` | No | - | Test identifier |
-### Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `press` | `{ originalEvent: Event }` | Fired when button is clicked or activated via keyboard |
----
-## Size Variants
-| Size | Height | Touch Target | Min Width | Typography | Icon Size |
-|------|--------|--------------|-----------|------------|-----------|
-| `small` | 40px | 44px | 56px | labelMd | 24px |
-| `medium` | 48px | 48px | 72px | labelMd | 24px |
-| `large` | 56px | 56px | 80px | labelLg | 32px |
----
-## Visual Variants
-| Variant | Background | Text | Border | Emphasis |
-|---------|------------|------|--------|----------|
-| `primary` | color.primary | color.contrast.onPrimary | none | Highest |
-| `secondary` | color.background | color.primary | 1px color.primary | Medium |
-| `tertiary` | transparent | color.primary | none | Lowest |
----
-## Token Dependencies
-### Typography
-- `typography.labelMd` - Small/medium button text
-- `typography.labelLg` - Large button text
-### Color
-- `color.primary` - Primary variant background, secondary/tertiary text
-- `color.contrast.onPrimary` - Primary variant text/icons
-- `color.background` - Secondary variant background
-- `color.border` - Secondary variant border
-### Spacing
-- `space.inset.*` - Internal padding
-- `space.inline.100` - Icon-to-label spacing
-### Motion
-- `motion.button.press` - Press animation timing
-- `motion.button.hover` - Hover transition timing
-### Blend
-- `blend.hoverDarker` - Hover state (8% darker)
-- `blend.pressedDarker` - Pressed state (12% darker)
-- `blend.iconLighter` - Icon optical balance (8% lighter)
-### Accessibility
-- `accessibility.tapArea.recommended` - 44px minimum touch target
-- `accessibility.focus.width` - 2px focus ring width
-- `accessibility.focus.offset` - 2px focus ring offset
-- `accessibility.focus.color` - Focus ring color
-### Component-Specific
-- `buttonCTA.minWidth.small` - 56px
-- `buttonCTA.minWidth.medium` - 72px
-- `buttonCTA.minWidth.large` - 80px
----
-## Accessibility
-### WCAG 2.1 AA Compliance
-| Criterion | Status | Implementation |
-|-----------|--------|----------------|
-| 1.4.1 Use of Color | ✅ | Visual variants use shape/border, not just color |
-| 1.4.3 Contrast | ✅ | All text meets 4.5:1 contrast ratio |
-| 1.4.11 Non-text Contrast | ✅ | Focus ring meets 3:1 contrast ratio |
-| 2.1.1 Keyboard | ✅ | Fully keyboard accessible (Tab, Enter, Space) |
-| 2.4.7 Focus Visible | ✅ | Clear focus indicator with :focus-visible |
-| 2.5.5 Target Size | ✅ | Touch targets meet 44px minimum |
-| 4.1.2 Name, Role, Value | ✅ | Proper ARIA attributes |
-### Keyboard Navigation
-| Key | Action |
-|-----|--------|
-| Tab | Move focus to/from button |
-| Enter | Activate button |
-| Space | Activate button |
-### Screen Reader Support
-- Semantic `<button>` element provides implicit role
-- `aria-label` set from label prop
-- State changes announced to assistive technology
----
-## Platform-Specific Behavior
-### Web
-- Hover state with color transition
-- :focus-visible for keyboard-only focus ring
-- Shadow DOM for style encapsulation
-### iOS
-- Scale animation on press (0.95 scale)
-- Haptic feedback via UIImpactFeedbackGenerator
-- Safe area handling for edge-to-edge layouts
-### Android
-- Ripple effect on press
-- Haptic feedback via HapticFeedback
-- Material Design integration
----
-## File Structure
-```
-src/components/core/Button-CTA/
-├── Button-CTA.schema.yaml        # Component schema definition
-├── Button-CTA.tokens.ts          # Component-specific tokens
-├── types.ts                      # Shared type definitions
-├── index.ts                      # Module exports
-├── README.md                     # This documentation
-├── platforms/
-│   ├── web/
-│   │   ├── ButtonCTA.web.ts      # Web Component implementation
-│   │   └── ButtonCTA.web.css     # Web styles
-│   ├── ios/
-│   │   └── ButtonCTA.ios.swift   # SwiftUI implementation
-│   └── android/
-│       └── ButtonCTA.android.kt  # Compose implementation
-└── __tests__/
-    ├── ButtonCTA.test.ts         # Unit tests
-    └── test-utils.ts             # Test utilities
-```
----
-## Related Documentation
-- [Stemma System Principles](/.kiro/steering/stemma-system-principles.md)
-- [Component Quick Reference](/.kiro/steering/Component-Quick-Reference.md)
-- [Component Schema Format](/.kiro/steering/Component-Schema-Format.md)
----
-## Migration from Button-CTA-Primary
-If migrating from the `Button-CTA-Primary` component:
-1. **Update imports**: Change `ButtonCTAPrimary` to `ButtonCTA`
-2. **Update HTML tags**: Change `<button-cta-primary>` to `<button-cta>`
-3. **No API changes**: All props and events remain the same
-```typescript
-// Before
-import { ButtonCTAPrimary } from './components/core/Button-CTA-Primary';
-// After
-import { ButtonCTA } from './components/core/Button-CTA';
-```
----
-*This component is part of the DesignerPunk Design System, following Stemma System principles for cross-platform consistency and AI-optimal discoverability.*

package/src/components/core/Button-CTA/__tests__/ButtonCTA.alignment.test.ts DELETED Viewed

@@ -1,355 +0,0 @@
-/**
- * @category evergreen
- * @purpose Alignment tests for Button-CTA component (Spec 040)
- * @jest-environment jsdom
- */
-/**
- * Button-CTA Alignment Tests (Spec 040 - Component Alignment)
- *
- * Tests verifying Button-CTA alignment to consistent architectural patterns:
- * - Incremental DOM update pattern for CSS transitions
- * - Semantic motion token usage
- *
- * These tests validate the architectural patterns established in Spec 040
- * to ensure consistency across the component library.
- *
- * Stemma System Naming: [Family]-[Type] = Button-CTA
- * Component Type: Standalone (no behavioral variants)
- *
- * @module Button-CTA/__tests__/ButtonCTA.alignment
- * @see Requirements: 2.2, 2.3, 3.1 (Spec 040)
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import {
-  registerButtonCTA,
-  createButtonCTA,
-  cleanupButtonCTA,
-  getShadowButton,
-  cleanupBlendColorProperties
-} from './test-utils';
-// ============================================================================
-// Helper Functions
-// ============================================================================
-/**
- * Read the actual CSS file content for CSS validation tests.
- */
-function readCSSFileContent(): string {
-  const cssPath = path.resolve(process.cwd(), 'src/components/core/Button-CTA/platforms/web/ButtonCTA.web.css');
-  if (fs.existsSync(cssPath)) {
-    return fs.readFileSync(cssPath, 'utf-8');
-  }
-  return '';
-}
-/**
- * Read the TypeScript source file for implementation validation.
- */
-function readTSFileContent(): string {
-  const tsPath = path.resolve(process.cwd(), 'src/components/core/Button-CTA/platforms/web/ButtonCTA.web.ts');
-  if (fs.existsSync(tsPath)) {
-    return fs.readFileSync(tsPath, 'utf-8');
-  }
-  return '';
-}
-// Cache file contents to avoid repeated reads
-let cachedCSSContent: string | null = null;
-let cachedTSContent: string | null = null;
-function getCSSContent(): string {
-  if (cachedCSSContent === null) {
-    cachedCSSContent = readCSSFileContent();
-  }
-  return cachedCSSContent;
-}
-function getTSContent(): string {
-  if (cachedTSContent === null) {
-    cachedTSContent = readTSFileContent();
-  }
-  return cachedTSContent;
-}
-// ============================================================================
-// Test Suite
-// ============================================================================
-describe('Button-CTA Alignment Tests (Spec 040)', () => {
-  // Register component before all tests
-  beforeAll(() => {
-    registerButtonCTA();
-  });
-  // Clean up tokens after all tests
-  afterAll(() => {
-    cleanupBlendColorProperties();
-  });
-  // ============================================================================
-  // Evergreen Tests: DOM Element Identity Preservation
-  // ============================================================================
-  describe('DOM Element Identity Preservation (Evergreen)', () => {
-    /**
-     * Evergreen tests for incremental DOM update pattern.
-     *
-     * These tests verify that Button-CTA preserves DOM element identity
-     * across attribute changes, enabling CSS transitions to work correctly.
-     *
-     * **Validates: Requirements 2.2, 2.3 (Spec 040)**
-     */
-    it('should have _domCreated flag for incremental updates', () => {
-      const tsContent = getTSContent();
-      // Verify _domCreated flag exists
-      expect(tsContent).toContain('private _domCreated: boolean = false');
-    });
-    it('should have _createDOM method for initial render', () => {
-      const tsContent = getTSContent();
-      // Verify _createDOM method exists
-      expect(tsContent).toContain('private _createDOM()');
-      expect(tsContent).toContain('this._shadowRoot.innerHTML');
-    });
-    it('should have _updateDOM method for attribute changes', () => {
-      const tsContent = getTSContent();
-      // Verify _updateDOM method exists
-      expect(tsContent).toContain('private _updateDOM()');
-    });
-    it('should NOT use innerHTML in _updateDOM method', () => {
-      const tsContent = getTSContent();
-      // Find the _updateDOM method and verify it doesn't use innerHTML
-      // The method should use direct DOM APIs instead
-      const updateDOMMatch = tsContent.match(/private _updateDOM\(\)[^{]*\{([\s\S]*?)(?=\n  \/\*\*|\n  private |\n  public |\n\})/);
-      if (updateDOMMatch) {
-        const updateDOMBody = updateDOMMatch[1];
-        // _updateDOM should NOT contain innerHTML assignment
-        expect(updateDOMBody).not.toContain('.innerHTML =');
-        expect(updateDOMBody).not.toContain('.innerHTML=');
-      }
-    });
-    it('should cache DOM element references', () => {
-      const tsContent = getTSContent();
-      // Verify cached element references
-      expect(tsContent).toContain('private _button: HTMLButtonElement | null');
-      expect(tsContent).toContain('private _labelEl: HTMLSpanElement | null');
-      expect(tsContent).toContain('private _iconEl: HTMLElement | null');
-    });
-    it('should preserve button element identity across attribute changes', async () => {
-      const button = await createButtonCTA({
-        label: 'Test Button',
-        size: 'medium'
-      });
-      try {
-        // Get initial button reference
-        const initialButton = getShadowButton(button);
-        expect(initialButton).toBeTruthy();
-        // Change attribute
-        button.size = 'large';
-        // Wait for update
-        await new Promise(resolve => setTimeout(resolve, 50));
-        // Get button reference after change
-        const updatedButton = getShadowButton(button);
-        expect(updatedButton).toBeTruthy();
-        // Verify same element (identity preserved)
-        expect(updatedButton).toBe(initialButton);
-      } finally {
-        cleanupButtonCTA(button);
-      }
-    });
-    it('should preserve button element identity across variant changes', async () => {
-      const button = await createButtonCTA({
-        label: 'Test Button',
-        buttonVariant: 'primary'
-      });
-      try {
-        // Get initial button reference
-        const initialButton = getShadowButton(button);
-        expect(initialButton).toBeTruthy();
-        // Change variant
-        button.buttonVariant = 'secondary';
-        // Wait for update
-        await new Promise(resolve => setTimeout(resolve, 50));
-        // Get button reference after change
-        const updatedButton = getShadowButton(button);
-        expect(updatedButton).toBeTruthy();
-        // Verify same element (identity preserved)
-        expect(updatedButton).toBe(initialButton);
-      } finally {
-        cleanupButtonCTA(button);
-      }
-    });
-    it('should preserve label element identity across label changes', async () => {
-      const button = await createButtonCTA({
-        label: 'Initial Label'
-      });
-      try {
-        // Get initial label reference
-        const initialLabel = button.shadowRoot?.querySelector('.button-cta__label, .button-cta__label--no-wrap');
-        expect(initialLabel).toBeTruthy();
-        // Change label
-        button.label = 'Updated Label';
-        // Wait for update
-        await new Promise(resolve => setTimeout(resolve, 50));
-        // Get label reference after change
-        const updatedLabel = button.shadowRoot?.querySelector('.button-cta__label, .button-cta__label--no-wrap');
-        expect(updatedLabel).toBeTruthy();
-        // Verify same element (identity preserved)
-        expect(updatedLabel).toBe(initialLabel);
-        // Verify label text was updated
-        expect(updatedLabel?.textContent).toBe('Updated Label');
-      } finally {
-        cleanupButtonCTA(button);
-      }
-    });
-    it('should preserve icon container identity across icon changes', async () => {
-      const button = await createButtonCTA({
-        label: 'Test Button',
-        icon: 'arrow-right'
-      });
-      try {
-        // Get initial icon container reference
-        const initialIconContainer = button.shadowRoot?.querySelector('.button-cta__icon');
-        expect(initialIconContainer).toBeTruthy();
-        // Change icon
-        button.icon = 'check';
-        // Wait for update
-        await new Promise(resolve => setTimeout(resolve, 50));
-        // Get icon container reference after change
-        const updatedIconContainer = button.shadowRoot?.querySelector('.button-cta__icon');
-        expect(updatedIconContainer).toBeTruthy();
-        // Verify same element (identity preserved)
-        expect(updatedIconContainer).toBe(initialIconContainer);
-      } finally {
-        cleanupButtonCTA(button);
-      }
-    });
-    it('should call _updateDOM on attribute change after initial render', () => {
-      const tsContent = getTSContent();
-      // Verify attributeChangedCallback routes to _updateDOM
-      expect(tsContent).toContain('attributeChangedCallback');
-      expect(tsContent).toContain('this._updateDOM()');
-    });
-    it('should use direct DOM APIs for updates', () => {
-      const tsContent = getTSContent();
-      // Verify _updateDOM uses direct DOM APIs
-      const updateDOMMatch = tsContent.match(/private _updateDOM\(\)[^{]*\{([\s\S]*?)(?=\n  \/\*\*|\n  private |\n  public |\n\})/);
-      if (updateDOMMatch) {
-        const updateDOMBody = updateDOMMatch[1];
-        // Should use direct DOM manipulation methods
-        expect(updateDOMBody).toContain('.className');
-        expect(updateDOMBody).toContain('.setAttribute');
-        expect(updateDOMBody).toContain('.textContent');
-      }
-    });
-  });
-  // ============================================================================
-  // Evergreen Tests: Motion Token Usage
-  // ============================================================================
-  describe('Motion Token Usage (Evergreen)', () => {
-    /**
-     * Evergreen tests for semantic motion token usage.
-     *
-     * These tests verify that Button-CTA uses semantic motion tokens
-     * (motion.buttonPress) instead of primitive tokens with hard-coded easing.
-     *
-     * **Validates: Requirements 3.1 (Spec 040)**
-     */
-    it('should use semantic motion token for transition duration', () => {
-      const cssContent = getCSSContent();
-      // Verify semantic motion token reference for duration
-      expect(cssContent).toContain('--motion-button-press-duration');
-    });
-    it('should use semantic motion token for transition easing', () => {
-      const cssContent = getCSSContent();
-      // Verify semantic motion token reference for easing
-      expect(cssContent).toContain('--motion-button-press-easing');
-    });
-    it('should use semantic motion tokens in transition property', () => {
-      const cssContent = getCSSContent();
-      // Verify transition uses both duration and easing from semantic tokens
-      expect(cssContent).toContain('var(--motion-button-press-duration) var(--motion-button-press-easing)');
-    });
-    it('should apply transitions to state-changing properties', () => {
-      const cssContent = getCSSContent();
-      // Verify transition is applied to background-color, border-color, color
-      expect(cssContent).toContain('background-color var(--motion-button-press-duration)');
-      expect(cssContent).toContain('border-color var(--motion-button-press-duration)');
-      expect(cssContent).toContain('color var(--motion-button-press-duration)');
-    });
-    it('should NOT use primitive duration token with hard-coded easing', () => {
-      const cssContent = getCSSContent();
-      // Verify no primitive duration tokens with hard-coded easing
-      // Pattern: --duration-* followed by ease-in-out or similar
-      const primitiveWithHardcodedEasing = /--duration-\d+[^;]*ease-in-out/;
-      expect(cssContent).not.toMatch(primitiveWithHardcodedEasing);
-      // Also check for common hard-coded easing patterns
-      expect(cssContent).not.toMatch(/var\(--duration-\d+\)\s+ease-in-out/);
-      expect(cssContent).not.toMatch(/var\(--duration-\d+\)\s+ease-out/);
-      expect(cssContent).not.toMatch(/var\(--duration-\d+\)\s+ease-in/);
-    });
-    it('should support reduced motion preference', () => {
-      const cssContent = getCSSContent();
-      // Verify reduced motion media query exists
-      expect(cssContent).toContain('@media (prefers-reduced-motion: reduce)');
-      expect(cssContent).toContain('transition: none');
-    });
-  });
-});