@3fn/core 14.1.0 → 15.0.0

package/src/components/core/Badge-Count-Notification/platforms/web/BadgeCountNotification.web.ts

@@ -1,401 +0,0 @@
-/**
- * Badge-Count-Notification Component for Web Platform
- * 
- * Stemma System: Badge Family
- * Component Type: Semantic Variant (inherits from Badge-Count-Base)
- * Naming Convention: [Family]-[Type]-[Variant] = Badge-Count-Notification
- * 
- * A notification count badge with predefined styling and live region announcements
- * for screen readers. Extends Badge-Count-Base behavior with notification-specific
- * colors and accessibility features.
- * 
- * Key Characteristics:
- * - Inherits all Badge-Count-Base behavior (count display, max truncation, showZero)
- * - Fixed notification colors (pink400 background, white100 text)
- * - Live region announcements for accessibility (aria-live="polite")
- * - Pluralized announcement text ("1 notification", "5 notifications")
- * - Optional announceChanges prop (default: true)
- * 
- * COLOR TOKENS (Spec 058):
- * Badge notification color tokens are defined in the component directory at
- * src/components/core/Badge-Count-Notification/tokens.ts following the Rosetta
- * System architecture. The web component uses CSS custom properties generated
- * by the token build pipeline:
- * - --color-badge-notification-background (references pink400)
- * - --color-badge-notification-text (references white100)
- * 
- * @module Badge-Count-Notification/platforms/web
- * @see Requirements: 3.1-3.10, 4.7, 5.1, 6.3
- * @see ../../tokens.ts for component color token definitions
- * @see .kiro/specs/044-badge-base/design.md for design specification
- * @see .kiro/specs/058-component-token-architecture-cleanup for color token migration
- */
-
-/// <reference lib="dom" />
-
-import { BadgeCountSize, BADGE_COUNT_NOTIFICATION_DEFAULTS } from '../../types';
-
-// Import CSS as string for browser bundle compatibility
-import badgeStyles from './BadgeCountNotification.styles.css';
-
-/**
- * Badge-Count-Notification Web Component
- * 
- * A native web component that renders a notification count badge with
- * automatic live region announcements for screen readers.
- * 
- * @remarks
- * - Uses Shadow DOM for style encapsulation
- * - Fixed notification colors (not configurable)
- * - Implements aria-live="polite" and aria-atomic="true" for announcements
- * - Pluralized announcement text for proper grammar
- * - Inherits all Badge-Count-Base behavior
- * - WCAG 2.1 AA compliant:
- *   - Color contrast 6.33:1 (exceeds 4.5:1 minimum)
- *   - Live region announcements for count changes
- *   - Text scaling support
- * 
- * @example
- * ```html
- * <!-- Basic usage -->
- * <badge-count-notification count="5"></badge-count-notification>
- * 
- * <!-- With size variant -->
- * <badge-count-notification count="3" size="sm"></badge-count-notification>
- * 
- * <!-- With max truncation -->
- * <badge-count-notification count="150" max="99"></badge-count-notification>
- * 
- * <!-- Disable announcements -->
- * <badge-count-notification count="5" announce-changes="false"></badge-count-notification>
- * 
- * <!-- With test ID -->
- * <badge-count-notification count="5" test-id="notification-badge"></badge-count-notification>
- * ```
- * 
- * @see Requirements: 3.1-3.10, 4.7, 5.1, 6.3
- */
-export class BadgeCountNotification extends HTMLElement {
-  private _shadowRoot: ShadowRoot;
-  private _previousCount: number | null = null;
-  
-  /**
-   * Observed attributes for automatic re-rendering on change.
-   */
-  static get observedAttributes(): string[] {
-    return ['count', 'max', 'show-zero', 'size', 'announce-changes', '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.
-   */
-  connectedCallback(): void {
-    this.render();
-  }
-  
-  /**
-   * Called when an observed attribute changes.
-   * 
-   * Triggers re-render and handles announcement logic for count changes.
-   */
-  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void {
-    if (oldValue !== newValue && this.isConnected) {
-      // Track count changes for announcement logic
-      if (name === 'count' && oldValue !== null) {
-        this._previousCount = parseInt(oldValue, 10);
-      }
-      
-      this.render();
-    }
-  }
-  
-  // ============================================================================
-  // Property Getters/Setters
-  // ============================================================================
-  
-  /**
-   * Get the badge count value.
-   * 
-   * @see Requirement 3.2 - inherits count behavior from Badge-Count-Base
-   */
-  get count(): number {
-    const countAttr = this.getAttribute('count');
-    if (countAttr === null) return 0;
-    
-    const parsed = parseInt(countAttr, 10);
-    if (isNaN(parsed)) return 0;
-    return Math.abs(parsed);
-  }
-  
-  set count(value: number) {
-    this.setAttribute('count', String(value));
-  }
-  
-  /**
-   * Get the maximum value before truncation.
-   * 
-   * @see Requirement 3.2 - inherits max behavior from Badge-Count-Base
-   */
-  get max(): number {
-    const maxAttr = this.getAttribute('max');
-    if (maxAttr === null) return BADGE_COUNT_NOTIFICATION_DEFAULTS.max;
-    
-    const parsed = parseInt(maxAttr, 10);
-    if (isNaN(parsed) || parsed <= 0) return BADGE_COUNT_NOTIFICATION_DEFAULTS.max;
-    return parsed;
-  }
-  
-  set max(value: number) {
-    this.setAttribute('max', String(value));
-  }
-  
-  /**
-   * Get the showZero state.
-   * 
-   * @see Requirement 3.2 - inherits showZero behavior from Badge-Count-Base
-   */
-  get showZero(): boolean {
-    return this.getAttribute('show-zero') === 'true';
-  }
-  
-  set showZero(value: boolean) {
-    if (value) {
-      this.setAttribute('show-zero', 'true');
-    } else {
-      this.removeAttribute('show-zero');
-    }
-  }
-  
-  /**
-   * Get the badge size variant.
-   * 
-   * @see Requirement 3.2 - inherits size behavior from Badge-Count-Base
-   */
-  get size(): BadgeCountSize {
-    const size = this.getAttribute('size');
-    return (size === 'sm' || size === 'md' || size === 'lg') 
-      ? size 
-      : BADGE_COUNT_NOTIFICATION_DEFAULTS.size;
-  }
-  
-  set size(value: BadgeCountSize) {
-    this.setAttribute('size', value);
-  }
-  
-  /**
-   * Get the announceChanges state.
-   * 
-   * @returns true if count changes should be announced (default), false otherwise
-   * @see Requirements 3.3, 3.6, 3.7 - announceChanges prop
-   */
-  get announceChanges(): boolean {
-    const attr = this.getAttribute('announce-changes');
-    // Default is true, only false if explicitly set to "false"
-    return attr !== 'false';
-  }
-  
-  set announceChanges(value: boolean) {
-    if (value) {
-      this.removeAttribute('announce-changes');
-    } else {
-      this.setAttribute('announce-changes', 'false');
-    }
-  }
-  
-  /**
-   * Get the test ID.
-   */
-  get testID(): string | null {
-    return this.getAttribute('test-id');
-  }
-  
-  set testID(value: string | null) {
-    if (value) {
-      this.setAttribute('test-id', value);
-    } else {
-      this.removeAttribute('test-id');
-    }
-  }
-  
-  // ============================================================================
-  // Rendering
-  // ============================================================================
-  
-  /**
-   * Get the display text for the count.
-   * 
-   * @see Requirement 3.2 - inherits max truncation from Badge-Count-Base
-   */
-  private getDisplayText(): string {
-    const count = this.count;
-    const max = this.max;
-    
-    if (count > max) {
-      return `${max}+`;
-    }
-    
-    return String(count);
-  }
-  
-  /**
-   * Get the announcement text for screen readers.
-   * 
-   * Implements pluralization logic:
-   * - "1 notification" (singular)
-   * - "5 notifications" (plural)
-   * - "99 or more notifications" (overflow)
-   * 
-   * @see Requirements 3.4, 3.5 - pluralized announcement text
-   */
-  private getAnnouncementText(): string {
-    const count = this.count;
-    const max = this.max;
-    
-    // @see Requirement 3.5 - overflow announcement
-    if (count > max) {
-      return `${max} or more notifications`;
-    }
-    
-    // @see Requirement 3.4 - pluralized text
-    if (count === 1) {
-      return '1 notification';
-    }
-    
-    return `${count} notifications`;
-  }
-  
-  /**
-   * Determine if the badge should be visible.
-   * 
-   * @see Requirement 3.2 - inherits showZero behavior from Badge-Count-Base
-   */
-  private shouldRender(): boolean {
-    const count = this.count;
-    const showZero = this.showZero;
-    
-    if (count === 0 && !showZero) {
-      return false;
-    }
-    
-    return true;
-  }
-  
-  /**
-   * Determine if an announcement should be made.
-   * 
-   * Only announces when:
-   * - announceChanges is true
-   * - There was a previous count (not initial render)
-   * - The count has actually changed
-   * 
-   * @see Requirements 3.3, 3.7 - announcement conditions
-   */
-  private shouldAnnounce(): boolean {
-    if (!this.announceChanges) {
-      return false;
-    }
-    
-    // Only announce if there was a previous count (not initial render)
-    if (this._previousCount === null) {
-      return false;
-    }
-    
-    // Only announce if count actually changed
-    return this._previousCount !== this.count;
-  }
-  
-  /**
-   * Render the component into shadow DOM.
-   * 
-   * @see Requirements: 3.1-3.10, 4.7, 5.1, 6.3
-   */
-  private render(): void {
-    // Check if badge should be rendered
-    if (!this.shouldRender()) {
-      this._shadowRoot.innerHTML = '';
-      return;
-    }
-    
-    const size = this.size;
-    const testID = this.testID;
-    const displayText = this.getDisplayText();
-    const announcementText = this.getAnnouncementText();
-    const shouldAnnounce = this.shouldAnnounce();
-    
-    // Generate CSS classes
-    const badgeClasses = [
-      'badge-count-notification',
-      `badge-count-notification--${size}`,
-    ].join(' ');
-    
-    // Generate test ID attribute
-    const testIDAttr = testID ? ` data-testid="${this.escapeHtml(testID)}"` : '';
-    
-    // Live region attributes for accessibility
-    // @see Requirement 3.8 - aria-live="polite" and aria-atomic="true"
-    const liveRegionAttrs = this.announceChanges 
-      ? ' aria-live="polite" aria-atomic="true"'
-      : '';
-    
-    // Visually hidden announcement text
-    // Only include if announcements are enabled
-    // @see Requirement 3.8 - visually hidden announcement text
-    const announcementHtml = this.announceChanges
-      ? `<span class="badge-count-notification__announcement" role="status">${this.escapeHtml(announcementText)}</span>`
-      : '';
-    
-    // Render shadow DOM content
-    this._shadowRoot.innerHTML = `
-      <style>
-        :host {
-          display: inline-block;
-        }
-        :host([hidden]) {
-          display: none;
-        }
-        ${badgeStyles}
-      </style>
-      <span class="${badgeClasses}"${testIDAttr}${liveRegionAttrs}>
-        <span class="badge-count-notification__text">${this.escapeHtml(displayText)}</span>
-        ${announcementHtml}
-      </span>
-    `;
-    
-    // Reset previous count after render
-    this._previousCount = this.count;
-  }
-  
-  /**
-   * Escape HTML entities to prevent XSS attacks.
-   */
-  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.
- */
-if (!customElements.get('badge-count-notification')) {
-  customElements.define('badge-count-notification', BadgeCountNotification);
-}
-
-/**
- * Default export for convenience.
- */
-export default BadgeCountNotification;

package/src/components/core/Badge-Count-Notification/tokens.ts

@@ -1,124 +0,0 @@
-/**
- * Badge-Count-Notification Component Token Definitions
- * 
- * Stemma System naming: [Family]-[Type]-[Variant] = Badge-Count-Notification
- * Type: Primitive (foundational component)
- * 
- * Platform-agnostic color token definitions for the Badge-Count-Notification component.
- * These tokens define the visual appearance of notification badges.
- * 
- * COLOR TOKENS (Spec 046 Task 8.2):
- * Badge notification color tokens now reference semantic tokens from the Rosetta System
- * semantic layer (color.feedback.notification.*) instead of primitive tokens directly.
- * This aligns with the architectural decision that color tokens require the semantic
- * token pipeline, as the defineComponentTokens() API only supports numeric values.
- * 
- * Semantic Token References:
- * - notification.background: References color.feedback.notification.background (pink400)
- * - notification.text: References color.feedback.notification.text (white100)
- * 
- * Contrast Ratio:
- * - pink400 (#E91E63) with white100 (#FFFFFF) provides 6.33:1 contrast ratio
- * - Exceeds WCAG AA requirement (4.5:1 for normal text)
- * 
- * @see .kiro/specs/044-badge-base/design.md for Badge component family design
- * @see .kiro/specs/046-input-checkbox-base Task 8.2 for semantic token migration
- * @see .kiro/specs/059-component-color-token-architecture for architectural decision
- * @see .kiro/specs/034-component-architecture-system for Stemma System details
- */
-
-/**
- * Badge-Count-Notification Color Token References
- * 
- * Component-specific color tokens for notification badges following the Rosetta System
- * architecture. These tokens reference semantic tokens from the color.feedback.notification
- * family, which are defined in src/tokens/semantic/ColorTokens.ts.
- * 
- * Architectural Decision (Spec 046 Task 8.2):
- * The defineComponentTokens() API only supports numeric values (spacing, sizing), not
- * color tokens. Color tokens require the semantic token pipeline. Therefore, component
- * color tokens reference semantic tokens instead of primitives directly.
- * 
- * Token Structure:
- * - notification.background: Background color for notification badges
- * - notification.text: Text color on notification badge background
- * 
- * Semantic Token References:
- * - notification.background → color.feedback.notification.background (pink400)
- * - notification.text → color.feedback.notification.text (white100)
- * 
- * @see src/tokens/semantic/ColorTokens.ts for semantic token definitions
- * @see .kiro/specs/046-input-checkbox-base Task 8.2 for migration context
- * @see .kiro/specs/044-badge-base/requirements.md for Badge component requirements
- */
-export const BadgeNotificationColorTokens = {
-  /**
-   * Background color for notification badges
-   * References: color.feedback.notification.background (semantic token)
-   * Underlying primitive: pink400
-   * Reasoning: High-visibility alert background with 6.33:1 contrast ratio against white text.
-   * Pink provides strong visual prominence for notification counts while maintaining
-   * accessibility compliance.
-   */
-  'notification.background': 'color.feedback.notification.background',
-
-  /**
-   * Text color on notification badge background
-   * References: color.feedback.notification.text (semantic token)
-   * Underlying primitive: white100
-   * Reasoning: White text ensures WCAG AA contrast compliance (6.33:1 ratio) on pink400
-   * background. Provides maximum readability for notification count numbers.
-   */
-  'notification.text': 'color.feedback.notification.text',
-} as const;
-
-/**
- * Type for Badge notification color token keys
- */
-export type BadgeNotificationColorTokenKey = keyof typeof BadgeNotificationColorTokens;
-
-/**
- * Get Badge notification color token reference for a given key
- * 
- * @param key - Color token key ('notification.background' | 'notification.text')
- * @returns Primitive token reference string
- * 
- * @example
- * ```typescript
- * getBadgeNotificationColorToken('notification.background')  // Returns 'pink400'
- * getBadgeNotificationColorToken('notification.text')        // Returns 'white100'
- * ```
- * 
- * @see .kiro/specs/058-component-token-architecture-cleanup Requirements 2.1, 2.2, 2.4
- */
-export function getBadgeNotificationColorToken(key: BadgeNotificationColorTokenKey): string {
-  return BadgeNotificationColorTokens[key];
-}
-
-/**
- * Token reference documentation for Badge notification colors
- * 
- * Documents the semantic token references and contrast ratio information.
- * Used for documentation and cross-referencing with the token system.
- * 
- * @see Requirements 2.1, 2.2 in .kiro/specs/058-component-token-architecture-cleanup/requirements.md
- * @see .kiro/specs/046-input-checkbox-base Task 8.2 for semantic token migration
- */
-export const BadgeNotificationTokenReferences = {
-  /** Background references color.feedback.notification.background semantic token */
-  'notification.background': {
-    semanticReference: 'color.feedback.notification.background',
-    primitiveReference: 'pink400',
-    reasoning: 'High-visibility alert background with 6.33:1 contrast ratio against white text',
-    contrastRatio: 6.33,
-    wcagCompliance: 'AA',
-  },
-  /** Text references color.feedback.notification.text semantic token */
-  'notification.text': {
-    semanticReference: 'color.feedback.notification.text',
-    primitiveReference: 'white100',
-    reasoning: 'White text ensures WCAG AA contrast compliance on pink400 background',
-    contrastRatio: 6.33,
-    wcagCompliance: 'AA',
-  },
-} as const;

package/src/components/core/Badge-Count-Notification/types.ts

@@ -1,119 +0,0 @@
-/**
- * Badge-Count-Notification Type Definitions
- * 
- * Stemma System: Badge Family
- * Component Type: Semantic Variant (inherits from Badge-Count-Base)
- * Naming Convention: [Family]-[Type]-[Variant] = Badge-Count-Notification
- * 
- * Provides type-safe props for the Badge-Count-Notification component across all platforms.
- * Badge-Count-Notification is a semantic variant that extends Badge-Count-Base with
- * notification-specific styling and live region announcements for screen readers.
- * 
- * @module Badge-Count-Notification/types
- * @see .kiro/specs/044-badge-base/design.md for design specification
- * @see Requirements 3.1-3.10 in .kiro/specs/044-badge-base/requirements.md
- */
-
-import { BadgeCountSize, BADGE_COUNT_DEFAULTS } from '../Badge-Count-Base/types';
-
-// Re-export shared types from Badge-Count-Base
-export { BadgeCountSize, BADGE_COUNT_DEFAULTS };
-
-/**
- * Default values for Badge-Count-Notification props.
- * 
- * Inherits defaults from Badge-Count-Base and adds notification-specific defaults.
- * 
- * @see Requirements 3.6 in .kiro/specs/044-badge-base/requirements.md
- */
-export const BADGE_COUNT_NOTIFICATION_DEFAULTS = {
-  ...BADGE_COUNT_DEFAULTS,
-  /** Default announceChanges behavior - announce count changes to screen readers */
-  announceChanges: true,
-} as const;
-
-/**
- * Props interface for Badge-Count-Notification component (platform-agnostic).
- * 
- * This interface defines the common API across all platforms (web, iOS, Android).
- * Inherits all props from Badge-Count-Base and adds notification-specific props.
- * 
- * @see Requirements 3.1-3.10 in .kiro/specs/044-badge-base/requirements.md
- * 
- * @example
- * ```typescript
- * // Web usage
- * <badge-count-notification count="5"></badge-count-notification>
- * 
- * // With announceChanges disabled
- * <badge-count-notification count="5" announce-changes="false"></badge-count-notification>
- * 
- * // With max truncation
- * <badge-count-notification count="150" max="99"></badge-count-notification>
- * ```
- */
-export interface BadgeCountNotificationProps {
-  /**
-   * Notification count (required).
-   * 
-   * The count to display inside the notification badge.
-   * 
-   * @see Requirement 3.2 in .kiro/specs/044-badge-base/requirements.md
-   */
-  count: number;
-  
-  /**
-   * Maximum before showing "[max]+".
-   * 
-   * When count exceeds this value, displays "[max]+" (e.g., "99+").
-   * Inherited from Badge-Count-Base.
-   * 
-   * @default 99
-   * @see Requirement 3.2 in .kiro/specs/044-badge-base/requirements.md
-   */
-  max?: number;
-  
-  /**
-   * Whether to show badge when count is 0.
-   * 
-   * When false (default), badge is not rendered when count is 0.
-   * When true, badge renders showing "0".
-   * Inherited from Badge-Count-Base.
-   * 
-   * @default false
-   * @see Requirement 3.2 in .kiro/specs/044-badge-base/requirements.md
-   */
-  showZero?: boolean;
-  
-  /**
-   * Size variant.
-   * 
-   * Determines typography and spacing tokens applied.
-   * Inherited from Badge-Count-Base.
-   * 
-   * @default 'md'
-   * @see Requirement 3.2 in .kiro/specs/044-badge-base/requirements.md
-   */
-  size?: BadgeCountSize;
-  
-  /**
-   * Whether to announce count changes to screen readers.
-   * 
-   * When true (default), count changes are announced via live regions.
-   * When false, count changes are not announced.
-   * 
-   * @default true
-   * @see Requirements 3.3, 3.6, 3.7 in .kiro/specs/044-badge-base/requirements.md
-   */
-  announceChanges?: 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;
-}