@3fn/core 13.0.0 → 14.1.0

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

package/src/components/core/Input-Text-Base/platforms/android/InputTextBase.android.kt

@@ -13,17 +13,17 @@
  * - Color animation (text.subtle → primary with blend.focusSaturate)
  * - Offset animation (translateY)
  * - Trailing icon support (error, success, info)
+ * - Trailing content slot for semantic variants (e.g., password toggle)
  * - Respects reduce motion settings
  * - WCAG 2.1 AA compliant
- * - Uses theme-aware blend utilities for state colors (focus, disabled)
- * 
+ * - Uses theme-aware blend utilities for state colors (focus)
+ *
  * Behavioral Contracts:
  * - focusable: Can receive keyboard focus
  * - float_label_animation: Label animates on focus
  * - validates_on_blur: Validation triggers on blur
  * - error_state_display: Shows error message and styling
  * - success_state_display: Shows success styling
- * - disabled_state: Prevents interaction when disabled
  * - trailing_icon_display: Shows contextual trailing icons
  * - focus_ring: WCAG 2.4.7 focus visible indicator
  * - reduced_motion_support: Respects prefers-reduced-motion
@@ -57,6 +57,7 @@ import androidx.compose.ui.platform.LocalDensity
 import androidx.compose.ui.semantics.contentDescription
 import androidx.compose.ui.semantics.error
 import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.semantics.stateDescription
 import androidx.compose.ui.text.TextStyle
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.text.input.ImeAction
@@ -68,7 +69,6 @@ import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
 import android.provider.Settings
 import com.designerpunk.tokens.focusBlend
-import com.designerpunk.tokens.disabledBlend
 
 /**
  * Input type enumeration
@@ -99,13 +99,17 @@ enum class InputType {
  * @param isSuccess Success state indicator
  * @param showInfoIcon Info icon support
  * @param type Input type
+ * @param visualTransformation Override for the input's visual transformation.
+ *        When null, derived from type (PasswordVisualTransformation for PASSWORD).
+ *        Semantic variants use this to control masking (e.g., password visibility toggle).
  * @param placeholder Placeholder text (only shown when label is floated and input is empty)
  * @param readOnly Read-only state
  * @param required Required field indicator
  * @param maxLength Maximum length for input value
  * @param imeAction IME action for keyboard
  * @param keyboardActions Keyboard actions
- * @param isDisabled Disabled state
+ * @param trailingContent Trailing content slot rendered after the status icons
+ *        (e.g., password visibility toggle)
  */
 @Composable
 fun InputTextBase(
@@ -121,13 +125,14 @@ fun InputTextBase(
     isSuccess: Boolean = false,
     showInfoIcon: Boolean = false,
     type: InputType = InputType.TEXT,
+    visualTransformation: VisualTransformation? = null,
     placeholder: String? = null,
     readOnly: Boolean = false,
     required: Boolean = false,
     maxLength: Int? = null,
     imeAction: ImeAction = ImeAction.Done,
     keyboardActions: KeyboardActions = KeyboardActions.Default,
-    isDisabled: Boolean = false
+    trailingContent: (@Composable () -> Unit)? = null
 ) {
     // State
     var isFocused by remember { mutableStateOf(false) }
@@ -192,7 +197,6 @@ fun InputTextBase(
         targetValue = when {
             hasError -> colorFeedbackErrorText
             isSuccess -> colorFeedbackSuccessText
-            isDisabled -> colorActionPrimary.disabledBlend()
             isFocused -> colorActionPrimary.focusBlend()
             else -> colorTextMuted
         },
@@ -204,7 +208,6 @@ fun InputTextBase(
         targetValue = when {
             hasError -> colorFeedbackErrorText
             isSuccess -> colorFeedbackSuccessText
-            isDisabled -> colorActionPrimary.disabledBlend()
             isFocused -> colorActionPrimary.focusBlend()
             else -> colorBorder
         },
@@ -230,6 +233,14 @@ fun InputTextBase(
                 if (errorMessage != null) {
                     error(errorMessage)
                 }
+                if (readOnly) {
+                    // Explicit TalkBack read-only announcement — label, value,
+                    // and "read only", never a disabled/dimmed state
+                    // (state_readonly contract, announcement-parity condition 3:
+                    // .kiro/issues/input-text-base-ios-readonly-adjudication.md,
+                    // RULED B-prime, Peter 2026-07-15).
+                    stateDescription = "read only"
+                }
             }
     ) {
         // Input wrapper with label and trailing icon
@@ -278,7 +289,7 @@ fun InputTextBase(
                         shape = RoundedCornerShape(radius150)
                     )
                     .then(
-                        if (isFocused && !isDisabled) {
+                        if (isFocused) {
                             Modifier.border(
                                 width = accessibilityFocusWidth,
                                 color = accessibilityFocusColor,
@@ -295,7 +306,7 @@ fun InputTextBase(
                     lineHeight = typographyInputLineHeight.sp,
                     fontWeight = FontWeight(typographyInputFontWeight),
                     letterSpacing = typographyInputLetterSpacing.sp,
-                    color = if (isDisabled) colorTextMuted else colorTextDefault
+                    color = colorTextDefault
                 ),
                 keyboardOptions = KeyboardOptions(
                     keyboardType = getKeyboardType(type),
@@ -303,8 +314,8 @@ fun InputTextBase(
                 ),
                 keyboardActions = keyboardActions,
                 singleLine = true,
-                readOnly = readOnly || isDisabled,
-                visualTransformation = if (type == InputType.PASSWORD) {
+                readOnly = readOnly,
+                visualTransformation = visualTransformation ?: if (type == InputType.PASSWORD) {
                     PasswordVisualTransformation()
                 } else {
                     VisualTransformation.None
@@ -373,6 +384,9 @@ fun InputTextBase(
                     )
                 }
             }
+
+            // Trailing content slot (e.g., password visibility toggle)
+            trailingContent?.invoke()
         }
         
         // Helper text (persistent)