@3fn/core 13.0.0 → 14.0.0

package/src/components/core/Button-CTA/platforms/web/ButtonCTA.web.ts

@@ -12,7 +12,7 @@
  * composition pattern as iOS and Android platforms. This ensures cross-platform
  * consistency and single source of truth for icon rendering.
  * 
- * Uses theme-aware blend utilities for state colors (hover, pressed, disabled, icon)
+ * Uses theme-aware blend utilities for state colors (hover, pressed, icon)
  * instead of opacity or filter workarounds. This ensures cross-platform consistency
  * with iOS and Android implementations.
  * 
@@ -86,13 +86,12 @@ function getIconSizeForButton(buttonSize: ButtonSize): IconBaseSize {
  * - Semantic `<button>` element with proper accessibility
  * - Token-based styling via CSS custom properties
  * - Supports text wrapping by default (accessibility-first)
- * - Uses blend utilities for state colors (hover, pressed, disabled, icon)
+ * - Uses blend utilities for state colors (hover, pressed, icon)
  * - WCAG 2.1 AA compliant:
  *   - Keyboard navigation (Tab, Enter, Space)
  *   - Focus indicators with 3:1 contrast ratio
  *   - Color contrast 4.5:1 for all styles
  *   - Screen reader support with ARIA attributes
- *   - Proper disabled state handling
  * 
  * @example
  * ```html
@@ -106,7 +105,6 @@ function getIconSizeForButton(buttonSize: ButtonSize): IconBaseSize {
  *   variant="primary"
  *   icon="arrow-right"
  *   no-wrap="false"
- *   disabled="false"
  *   test-id="submit-button"
  * ></button-cta>
  * ```
@@ -143,7 +141,6 @@ export class ButtonCTA extends HTMLElement {
   // Cached blend colors for state styling
   private _hoverColor: string = '';
   private _pressedColor: string = '';
-  private _disabledColor: string = '';
   private _iconColor: string = '';
   private _iconOpticalBalanceColor: string = '';
   
@@ -153,7 +150,7 @@ export class ButtonCTA extends HTMLElement {
    * When these attributes change, attributeChangedCallback is invoked.
    */
   static get observedAttributes(): string[] {
-    return ['label', 'size', 'variant', 'icon', 'no-wrap', 'disabled', 'test-id'];
+    return ['label', 'size', 'variant', 'icon', 'no-wrap', 'test-id'];
   }
   
   constructor() {
@@ -219,15 +216,14 @@ export class ButtonCTA extends HTMLElement {
    * Calculate blend colors from CSS custom properties.
    * 
    * Reads base colors from CSS custom properties and applies theme-aware blend
-   * utilities to generate state colors (hover, pressed, disabled, icon).
-   * 
+   * utilities to generate state colors (hover, pressed, icon).
+   *
    * Uses getBlendUtilities() factory functions instead of direct blend calculations
    * for cross-platform consistency with iOS and Android implementations.
-   * 
+   *
    * State color mappings:
    * - Hover: darkerBlend(color.action.primary, blend.hoverDarker) - 8% darker
    * - Pressed: darkerBlend(color.action.primary, blend.pressedDarker) - 12% darker
-   * - Disabled: desaturate(color.action.primary, blend.disabledDesaturate) - 12% less saturated
    * - Icon: lighterBlend(color.contrast.onAction, blend.iconLighter) - 8% lighter
    * 
    * @see Requirements: 7.1, 7.2, 7.3, 7.4 - Button-CTA state colors
@@ -258,10 +254,7 @@ export class ButtonCTA extends HTMLElement {
     
     // @see Requirements: 7.2 - Pressed uses darkerBlend(color.action.primary, blend.pressedDarker)
     this._pressedColor = this._blendUtils.pressedColor(primaryColor);
-    
-    // @see Requirements: 7.3 - Disabled uses desaturate(color.action.primary, blend.disabledDesaturate)
-    this._disabledColor = this._blendUtils.disabledColor(primaryColor);
-    
+
     // @see Requirements: 7.4 - Icon uses lighterBlend(color.contrast.onAction, blend.iconLighter)
     // Icon for primary buttons: provides optical balance for icons on primary background
     this._iconColor = this._blendUtils.iconColor(onActionColor);
@@ -371,24 +364,6 @@ export class ButtonCTA extends HTMLElement {
     this.setAttribute('no-wrap', value.toString());
   }
   
-  /**
-   * Get the disabled state.
-   */
-  get disabled(): boolean {
-    return this.hasAttribute('disabled');
-  }
-  
-  /**
-   * Set the disabled state.
-   */
-  set disabled(value: boolean) {
-    if (value) {
-      this.setAttribute('disabled', '');
-    } else {
-      this.removeAttribute('disabled');
-    }
-  }
-  
   /**
    * Get the test ID.
    */
@@ -451,17 +426,15 @@ export class ButtonCTA extends HTMLElement {
     const variant = this.buttonVariant;
     const icon = this.icon;
     const noWrap = this.noWrap;
-    const disabled = this.disabled;
     const testID = this.testID;
-    
+
     // Generate class names
     const buttonClasses = [
       'button-cta',
       `button-cta--${size}`,
-      `button-cta--${variant}`,
-      disabled ? 'button-cta--disabled' : ''
-    ].filter(Boolean).join(' ');
-    
+      `button-cta--${variant}`
+    ].join(' ');
+
     // Get icon size for button size variant
     // Icon sizes are type-safe mapped from button size:
     // - Small/Medium: 24px (iconBaseSize100)
@@ -480,7 +453,6 @@ export class ButtonCTA extends HTMLElement {
     const blendColorStyles = `
       --_cta-hover-bg: ${this._hoverColor};
       --_cta-pressed-bg: ${this._pressedColor};
-      --_cta-disabled-bg: ${this._disabledColor};
       --_cta-icon-color: ${this._iconColor};
       --_cta-icon-optical: ${this._iconOpticalBalanceColor};
     `;
@@ -491,11 +463,10 @@ export class ButtonCTA extends HTMLElement {
     // @see Requirements: 8.2, 8.3 (components render correctly with interactivity)
     this._shadowRoot.innerHTML = `
       <style>${buttonStyles}</style>
-      <button 
+      <button
         class="${buttonClasses}"
         type="button"
         role="button"
-        ${disabled ? 'disabled aria-disabled="true"' : 'aria-disabled="false"'}
         ${testIDAttr}
         aria-label="${label}"
         style="${blendColorStyles}"
@@ -536,34 +507,23 @@ export class ButtonCTA extends HTMLElement {
     const variant = this.buttonVariant;
     const icon = this.icon;
     const noWrap = this.noWrap;
-    const disabled = this.disabled;
     const testID = this.testID;
-    
+
     // Get icon size for button size variant
     const iconSize: IconBaseSize = getIconSizeForButton(size);
-    
+
     // ─────────────────────────────────────────────────────────────────
     // Update button element
     // ─────────────────────────────────────────────────────────────────
-    
+
     // Update CSS class (preserves element identity for transitions)
     const buttonClasses = [
       'button-cta',
       `button-cta--${size}`,
-      `button-cta--${variant}`,
-      disabled ? 'button-cta--disabled' : ''
-    ].filter(Boolean).join(' ');
+      `button-cta--${variant}`
+    ].join(' ');
     this._button.className = buttonClasses;
-    
-    // Update disabled state
-    if (disabled) {
-      this._button.setAttribute('disabled', '');
-      this._button.setAttribute('aria-disabled', 'true');
-    } else {
-      this._button.removeAttribute('disabled');
-      this._button.setAttribute('aria-disabled', 'false');
-    }
-    
+
     // Update aria-label
     this._button.setAttribute('aria-label', label);
     
@@ -577,7 +537,6 @@ export class ButtonCTA extends HTMLElement {
     // Update blend color CSS custom properties
     this._button.style.setProperty('--_cta-hover-bg', this._hoverColor);
     this._button.style.setProperty('--_cta-pressed-bg', this._pressedColor);
-    this._button.style.setProperty('--_cta-disabled-bg', this._disabledColor);
     this._button.style.setProperty('--_cta-icon-color', this._iconColor);
     this._button.style.setProperty('--_cta-icon-optical', this._iconOpticalBalanceColor);
     
@@ -638,13 +597,6 @@ export class ButtonCTA extends HTMLElement {
    * Dispatches a custom 'press' event that bubbles up to parent elements.
    */
   private _handleClick = (event: Event): void => {
-    // Don't dispatch if disabled
-    if (this.disabled) {
-      event.preventDefault();
-      event.stopPropagation();
-      return;
-    }
-    
     // Dispatch custom 'press' event
     this.dispatchEvent(new CustomEvent('press', {
       bubbles: true,
@@ -663,11 +615,6 @@ export class ButtonCTA extends HTMLElement {
    * @param event - The keyboard event
    */
   private _handleKeyDown = (event: KeyboardEvent): void => {
-    // Don't handle if disabled
-    if (this.disabled) {
-      return;
-    }
-    
     // Handle Enter and Space keys (WCAG 2.1 AA keyboard navigation)
     if (event.key === 'Enter' || event.key === ' ') {
       event.preventDefault(); // Prevent default space scrolling

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

@@ -82,7 +82,6 @@ export type ButtonStyle = 'primary' | 'secondary' | 'tertiary';
  *   variant="primary"
  *   icon="arrow-right"
  *   noWrap={false}
- *   disabled={false}
  *   testID="submit-button"
  *   onPress={handleSubmit}
  * />
@@ -197,15 +196,13 @@ export interface ButtonProps {
   
   /**
    * Click/tap handler (required)
-   * 
+   *
    * Callback function invoked when the button is clicked or tapped.
-   * Not called when button is disabled.
-   * 
+   *
    * @remarks
    * - Function signature: `() => void`
-   * - Not invoked when `disabled` is true
    * - Triggered by click, tap, Enter key, or Space key
-   * 
+   *
    * @example
    * ```typescript
    * onPress={() => console.log('Clicked')}
@@ -232,26 +229,11 @@ export interface ButtonProps {
    * ```
    */
   testID?: string;
-  
-  /**
-   * Optional disabled state (default: false)
-   * 
-   * When true, the button is non-interactive and visually indicates
-   * disabled state. The onPress handler is not called when disabled.
-   * 
-   * @defaultValue false
-   * 
-   * @remarks
-   * - Disabled buttons are not keyboard focusable
-   * - Screen readers announce disabled state
-   * - Visual styling indicates non-interactive state
-   * 
-   * @example
-   * ```typescript
-   * disabled={false}  // Interactive (default)
-   * disabled={true}   // Non-interactive
-   * disabled={isSubmitting}  // Conditional disable
-   * ```
-   */
-  disabled?: boolean;
 }
+
+// NO DISABLED STATES
+// DesignerPunk does not support disabled states for usability and
+// accessibility reasons. If an action is unavailable, the component
+// should not be rendered. For in-flight async actions, use the loading
+// state (state_loading) instead.
+// Ruled by Peter 2026-07-15 (Button-CTA disabled-state adjudication).

package/src/components/core/Chip-Base/__tests__/ChipBase.test.ts

@@ -40,11 +40,24 @@ describe('Chip-Base Web Component', () => {
   beforeEach(async () => {
     // Wait for custom element to be defined
     await customElements.whenDefined('chip-base');
+    // Silence ONLY the known environmental warn ("Could not calculate blend colors",
+    // fired async via rAF): jsdom never applies real CSS, so the token lookup cannot
+    // succeed here and the component's designed fallback fires every run, forever.
+    // Anything ELSE passes through to the real console — a NEW warn class stays audible.
+    const realWarn = console.warn.bind(console);
+    jest.spyOn(console, 'warn').mockImplementation((...args: unknown[]) => {
+      // Component-prefixed match (Lina review, PR #39): the bare substring is shared by
+      // Button components too — prefix-matching prevents accidentally swallowing a
+      // cross-component warn if this suite ever composes a Button.
+      if (typeof args[0] === 'string' && args[0].includes('ChipBase: Could not calculate blend colors')) return;
+      realWarn(...args);
+    });
   });
 
   afterEach(() => {
     // Clean up any created elements
     cleanupDOM();
+    jest.restoreAllMocks();
   });
 
   // ============================================================================

package/src/components/core/Chip-Filter/__tests__/ChipFilter.test.ts

@@ -42,11 +42,24 @@ describe('Chip-Filter Web Component', () => {
   beforeEach(async () => {
     // Wait for custom element to be defined
     await customElements.whenDefined('chip-filter');
+    // Silence ONLY the known environmental warn ("Could not calculate blend colors",
+    // fired async via rAF): jsdom never applies real CSS, so the token lookup cannot
+    // succeed here and the component's designed fallback fires every run, forever.
+    // Anything ELSE passes through to the real console — a NEW warn class stays audible.
+    const realWarn = console.warn.bind(console);
+    jest.spyOn(console, 'warn').mockImplementation((...args: unknown[]) => {
+      // Component-prefixed match (Lina review, PR #39): the bare substring is shared by
+      // Button components too — prefix-matching prevents accidentally swallowing a
+      // cross-component warn if this suite ever composes a Button.
+      if (typeof args[0] === 'string' && args[0].includes('ChipFilter: Could not calculate blend colors')) return;
+      realWarn(...args);
+    });
   });
 
   afterEach(() => {
     // Clean up any created elements
     cleanupDOM();
+    jest.restoreAllMocks();
   });
 
   // ============================================================================

package/src/components/core/Chip-Input/__tests__/ChipInput.test.ts

@@ -41,11 +41,24 @@ describe('Chip-Input Web Component', () => {
   beforeEach(async () => {
     // Wait for custom element to be defined
     await customElements.whenDefined('chip-input');
+    // Silence ONLY the known environmental warn ("Could not calculate blend colors",
+    // fired async via rAF): jsdom never applies real CSS, so the token lookup cannot
+    // succeed here and the component's designed fallback fires every run, forever.
+    // Anything ELSE passes through to the real console — a NEW warn class stays audible.
+    const realWarn = console.warn.bind(console);
+    jest.spyOn(console, 'warn').mockImplementation((...args: unknown[]) => {
+      // Component-prefixed match (Lina review, PR #39): the bare substring is shared by
+      // Button components too — prefix-matching prevents accidentally swallowing a
+      // cross-component warn if this suite ever composes a Button.
+      if (typeof args[0] === 'string' && args[0].includes('ChipInput: Could not calculate blend colors')) return;
+      realWarn(...args);
+    });
   });
 
   afterEach(() => {
     // Clean up any created elements
     cleanupDOM();
+    jest.restoreAllMocks();
   });
 
   // ============================================================================

package/src/components/core/Input-Text-Base/Input-Text-Base.schema.yaml

@@ -11,7 +11,7 @@
 name: Input-Text-Base
 type: primitive
 family: FormInput
-version: "1.0.0"
+version: "1.1.0"
 readiness:
   web:
     reviewed: true
@@ -25,6 +25,16 @@ composition:
     - component: Icon-Base
       role: Trailing contextual icon (error, success, info)
       required: false
+  slots:
+    - name: trailingContent
+      description: >-
+        Trailing content slot rendered after the status icons. Semantic
+        variants use it to inject interactive trailing controls (e.g.,
+        Input-Text-Password's visibility toggle). Native platforms only
+        (iOS: AnyView?, Android: @Composable lambda) — the web base has no
+        equivalent slot; web variants render trailing controls in their
+        own Shadow DOM.
+      required: false
 
 # Component description
 description: |
@@ -113,7 +123,11 @@ properties:
     type: boolean
     required: false
     default: false
-    description: Read-only state (alternative to disabled)
+    description: >-
+      Read-only display state (state_readonly contract) — the value is
+      non-editable but stays perceivable, selectable, and copyable; no
+      keyboard/IME is raised and disabled semantics are never applied. iOS
+      renders it as selectable static text inside the field chrome.
   
   required:
     type: boolean
@@ -188,9 +202,23 @@ platform_notes:
   ios:
     implementation: SwiftUI View
     file: platforms/ios/InputTextBase.ios.swift
+    notes: |
+      Platform composition parameters (not part of the cross-platform props):
+      - trailingContent: AnyView? = nil — trailing content slot (see composition.slots)
+      Masking: type .password renders SecureField; other types render TextField.
+      Variants toggle visibility by switching type between .password and .text.
   android:
     implementation: Jetpack Compose Composable
     file: platforms/android/InputTextBase.android.kt
+    notes: |
+      Platform composition parameters (not part of the cross-platform props):
+      - modifier, imeAction, keyboardActions — standard Compose passthroughs
+      - visualTransformation: VisualTransformation? = null — masking override;
+        null derives from type (PasswordVisualTransformation for PASSWORD)
+      - trailingContent: (@Composable () -> Unit)? = null — trailing content
+        slot (see composition.slots)
+      Variants toggle password visibility via visualTransformation while
+      keeping type = PASSWORD (preserves the password keyboard type).
 
 # Semantic components that inherit from this primitive
 semantic_variants:

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

@@ -36,11 +36,12 @@ This component guarantees the following behaviors across all platforms:
 | `validates_on_blur` | Validation triggers on blur | 3.3.1 |
 | `error_state_display` | Shows error message and styling | 3.3.1, 1.4.1 |
 | `success_state_display` | Shows success styling | 1.4.1 |
-| `disabled_state` | Prevents interaction when disabled | 4.1.2 |
 | `trailing_icon_display` | Shows contextual trailing icons | 1.4.1 |
 | `focus_ring` | WCAG 2.4.7 focus visible indicator | 2.4.7 |
 | `reduced_motion_support` | Respects prefers-reduced-motion | 2.3.3 |
 
+**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).
+
 ---
 
 ## Related Documentation
@@ -145,12 +146,27 @@ InputTextBase(
 | `type` | `'text' \| 'email' \| 'password' \| 'tel' \| 'url'` | No | `'text'` | Input type |
 | `autocomplete` | `string` | No | - | Autocomplete attribute for browser autofill |
 | `placeholder` | `string` | No | - | Placeholder text (only shown when label is floated and input is empty) |
-| `readOnly` | `boolean` | No | `false` | Read-only state (alternative to disabled) |
+| `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. Ignored for secure types; not supported by Input-Text-Password |
 | `required` | `boolean` | No | `false` | Required field indicator |
 | `maxLength` | `number` | No | - | Maximum length for input value |
 | `testID` | `string` | No | - | Test ID for automated testing |
 | `className` | `string` | No | - | Additional CSS class names (web only) |
 
+### Platform Composition Parameters (native only)
+
+These parameters exist on the native implementations for platform composition —
+they are not part of the cross-platform props contract above:
+
+| Parameter | Platform | Type | Default | Description |
+|-----------|----------|------|---------|-------------|
+| `trailingContent` | iOS | `AnyView?` | `nil` | Trailing content slot rendered after the status icons (e.g., Input-Text-Password's visibility toggle) |
+| `trailingContent` | Android | `(@Composable () -> Unit)?` | `null` | Same slot, Compose form |
+| `visualTransformation` | Android | `VisualTransformation?` | `null` | Masking override; `null` derives from `type` (`PasswordVisualTransformation` for `PASSWORD`). Lets variants toggle password visibility while keeping the password keyboard type |
+| `modifier`, `imeAction`, `keyboardActions` | Android | — | — | Standard Compose passthroughs |
+
+The web base has no trailing slot equivalent — web semantic variants render
+trailing controls inside their own Shadow DOM.
+
 ---
 
 ## Token Consumption
@@ -221,6 +237,13 @@ Legacy type aliases are provided for backward compatibility during migration.
 
 ## Changelog
 
+### v1.1.0 (July 2026)
+
+- Native bases gain a `trailingContent` composition slot (iOS `AnyView?`, Android `@Composable` lambda) so semantic variants can inject trailing controls — required by Input-Text-Password's visibility toggle
+- Android base gains a `visualTransformation` override (null = derived from `type`) so variants can toggle masking without changing the input type
+- Fixed Input-Text-PhoneNumber native callers referencing nonexistent enum members (`.phone`/`PHONE` → `.tel`/`TEL`)
+- Added static base-call alignment test (`src/__tests__/stemma-system/input-text-native-base-call-alignment.test.ts`) guarding native call sites against parameter/enum drift
+
 ### v1.0.0 (January 2026)
 
 - Initial release as Input-Text-Base (renamed from TextInputField)

package/src/components/core/Input-Text-Base/__tests__/focusIndicators.test.ts

@@ -165,8 +165,8 @@ describe('Input-Text-Base Focus Indicators', () => {
       expect(iosComponentContent).toContain('accessibilityFocusWidth');
       expect(iosComponentContent).toContain('accessibilityFocusOffset');
       
-      // Verify focus ring is visible when focused (and not disabled)
-      expect(iosComponentContent).toContain('.opacity(isFocused && !isDisabled ? 1 : 0)');
+      // Verify focus ring is visible when focused
+      expect(iosComponentContent).toContain('.opacity(isFocused ? 1 : 0)');
     });
     
     it('should have focus ring animation that respects reduce motion', () => {
@@ -194,8 +194,8 @@ describe('Input-Text-Base Focus Indicators', () => {
       expect(androidComponentContent).toContain('accessibilityFocusColor');
       expect(androidComponentContent).toContain('accessibilityFocusOffset');
       
-      // Verify focus ring is conditional on focus state (and not disabled)
-      expect(androidComponentContent).toContain('if (isFocused && !isDisabled)');
+      // Verify focus ring is conditional on focus state
+      expect(androidComponentContent).toContain('if (isFocused)');
     });
   });
   
@@ -219,16 +219,17 @@ describe('Input-Text-Base Focus Indicators', () => {
       
       // iOS: Verify focus ring is not conditional on error/success state
       // (it should always show when focused, regardless of validation state)
-      // Note: Focus ring is hidden when disabled (isDisabled check is expected)
-      // Find the focus ring section in the InputTextBaseFieldStyle
+      // Find the focus ring section in InputTextBaseFieldChrome (the shared
+      // field chrome, extracted from InputTextBaseFieldStyle per the B-prime
+      // readOnly ruling, 2026-07-15)
       const iosFocusRingSection = iosContent.substring(
-        iosContent.indexOf('.opacity(isFocused && !isDisabled ? 1 : 0)'),
-        iosContent.indexOf('.opacity(isFocused && !isDisabled ? 1 : 0)') + 200
+        iosContent.indexOf('.opacity(isFocused ? 1 : 0)'),
+        iosContent.indexOf('.opacity(isFocused ? 1 : 0)') + 200
       );
-      expect(iosFocusRingSection).toContain('.opacity(isFocused && !isDisabled ? 1 : 0)');
-      
-      // Android: Verify focus ring is conditional on focus state (and not disabled)
-      expect(androidContent).toContain('if (isFocused && !isDisabled)');
+      expect(iosFocusRingSection).toContain('.opacity(isFocused ? 1 : 0)');
+
+      // Android: Verify focus ring is conditional on focus state
+      expect(androidContent).toContain('if (isFocused)');
     });
   });
   
@@ -249,10 +250,10 @@ describe('Input-Text-Base Focus Indicators', () => {
       expect(cssContent).toContain(':focus-visible');
       
       // iOS: Uses overlay with opacity based on focus state
-      expect(iosContent).toContain('.opacity(isFocused && !isDisabled ? 1 : 0)');
-      
+      expect(iosContent).toContain('.opacity(isFocused ? 1 : 0)');
+
       // Android: Uses conditional border based on focus state
-      expect(androidContent).toContain('if (isFocused && !isDisabled)');
+      expect(androidContent).toContain('if (isFocused)');
     });
 
     it('should document WCAG 2.4.7 compliance in behavioral contracts', () => {

package/src/components/core/Input-Text-Base/contracts.yaml

@@ -9,12 +9,29 @@ contracts:
     behavior: |
       Component can receive focus via Tab key navigation.
       Focus state is visually indicated and triggers label animation.
+
+      Platform note — iOS readOnly carve-out (declared, adjudicated): when
+      readOnly is true, iOS renders the value as selectable static text
+      (see state_readonly) and does NOT participate in keyboard/Full
+      Keyboard Access focus order; onFocus/onBlur are declared not-fired on
+      that path. Web and Android readOnly fields affirmatively REMAIN in
+      focus order and fire focus events (removing an Android readOnly field
+      from focus order would require enabled=false — banned disabled
+      semantics — so normalizing web/Android down to iOS is not an
+      available move). The carve-out is a mitigable declared exception, not
+      a settled permanent difference: an on-device .focusable(interactions:)
+      prototype is tracked, and if it verifies (FKA reachability + keyboard
+      copy), iOS re-enters focus order and this note tightens to full
+      three-platform participation.
+      Ruling: .kiro/issues/input-text-base-ios-readonly-adjudication.md
+      (RULED B-prime, Peter 2026-07-15).
     wcag: "2.1.1 Keyboard"
     platforms: [web, ios, android]
     validation:
       - Tab key moves focus to input
       - Focus state is visually distinct
       - Focus triggers label float animation
+      - readOnly fields remain in keyboard focus order on web and Android
     test_approach: |
       - Press Tab, verify input receives focus
       - Verify label animates on focus
@@ -74,6 +91,79 @@ contracts:
       - Set error state, verify border/label/icon/message
     required: true
 
+  # state_readonly concept ratified into the Concept Catalog via ballot
+  # (.kiro/docs/ballots/2026-07-15-state-readonly-concept.md, RATIFIED Peter
+  # 2026-07-15). Authored under the B-prime ruling:
+  # .kiro/issues/input-text-base-ios-readonly-adjudication.md (RULED by Peter,
+  # 2026-07-15).
+  state_readonly:
+    category: state
+    description: Displays a non-editable value that stays perceivable, selectable, and copyable — never disabled semantics
+    behavior: |
+      When readOnly is true, the component displays its value without
+      allowing edits. Invariants on all platforms:
+      - Content is selectable and copyable (whole-string copy is the
+        accepted iOS behavior — long-press select/copy on static text).
+      - Content is not editable; no software keyboard/IME is raised.
+      - Assistive technology announces the label, the value, and a
+        read-only indication — NEVER a disabled/dimmed trait or state.
+      - No disabled semantics of any kind (no SwiftUI .disabled(), no
+        Compose enabled=false, no aria-disabled/disabled attribute).
+
+      Announcement per platform:
+      - Web: native readonly attribute semantics (implicit aria-readonly).
+      - Android: explicit stateDescription("read only") in semantics.
+      - iOS: composed accessibility — label + value + read-only hint.
+
+      Focus order per platform:
+      - Web and Android: readOnly fields affirmatively PARTICIPATE in
+        keyboard focus order and fire onFocus/onBlur.
+      - iOS: readOnly content is rendered as selectable static text inside
+        the shared field chrome (B-prime); it is NOT in keyboard/FKA focus
+        order and onFocus/onBlur are DECLARED not-fired — a mitigable
+        declared exception. A .focusable(interactions:) on-device prototype
+        is tracked; if it verifies, this contract auto-tightens and iOS
+        re-enters focus order.
+
+      Tap-acknowledgment delta (platform note): tapping an Android readOnly
+      field focuses it (focus ring engages; empty-field label floats);
+      tapping the iOS readOnly text gives no acknowledgment until
+      long-press (select/copy). Declared, cosmetic.
+
+      Empty-value behavior: the label rests in placeholder position on all
+      platforms (no platform force-floats it), and the field chrome
+      reserves its full height unconditionally.
+
+      Secure-type carve-out (declared): when Input-Text-Base is used
+      directly with a secure/password type, readOnly is IGNORED — the field
+      remains an editable secure field. The read-only display path renders
+      the value as selectable plaintext and must be unreachable for
+      secrets; read-only passwords are excluded at the variant level
+      (Input-Text-Password excludes state_readonly and never forwards
+      readOnly).
+    wcag: "4.1.2 Name, Role, Value"
+    platforms: [web, ios, android]
+    validation:
+      - Value is not editable when readOnly is true
+      - Content is selectable and copyable on all platforms
+      - No software keyboard/IME is raised
+      - Web renders the native readonly attribute
+      - Android passes readOnly to the text field with enabled=true and sets
+        stateDescription("read only")
+      - iOS renders selectable Text (textSelection enabled) inside the
+        shared field chrome and composes a read-only accessibility hint
+      - No platform applies disabled semantics (.disabled(), enabled=false,
+        aria-disabled, dimmed trait)
+      - readOnly fields remain in keyboard focus order on web and Android
+    test_approach: |
+      - Static (Jest): web readonly attribute wiring; Android
+        readOnly = readOnly pass-through; iOS textSelection path present and
+        no .disabled( anywhere in Form Inputs iOS sources
+      - Device: attempt edit (rejected), copy value, verify announcement
+        (VoiceOver: label + value + read-only hint, never "dimmed";
+        TalkBack: "read only")
+    required: true
+
   state_success:
     category: state
     description: Shows success styling