@hjmds/react-native 1.12.1 → 1.13.1

package/dist/inputs.js

@@ -9,13 +9,14 @@ import { visibleControlHeight } from "@hjmds/design-contracts/components/design-
 import { passwordFieldRecipe, resolvePasswordFieldDescriptor, } from "@hjmds/design-contracts/components/password-field";
 import { getOtpFieldSlotValues, otpFieldRecipe, resolveOtpFieldValue, } from "@hjmds/design-contracts/components/otp-field";
 import { getCheckboxNextState, reconcileCheckboxSelection, resolveControlAccessibleName, resolveInitialRadioValue, resolveInitialTabValue, reconcileRadioSelection, selectionGroupBehaviorDefaults, toggleCheckboxSelection, validateCheckboxSelection, validateRadioSelection, validateSelectionItems, } from "@hjmds/design-contracts/behaviors";
-import { forwardRef, useEffect, useId, useImperativeHandle, useRef, useState, } from "react";
+import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useRef, useState, } from "react";
 import { ActivityIndicator, Platform, Pressable, Switch as NativeSwitch, Text as NativeText, TextInput, View, } from "react-native";
 import { mixedCheckboxState, useControllableState } from "./internal/state.js";
 import { webChoiceProps, webOnly } from "./internal/web-a11y.js";
 import { logicalTextAlign, minimumTargetStyle, resolveNativeTextScaleProps, } from "./internal/styles.js";
 import { Text } from "./primitives.js";
 import { useHjmNativeTheme } from "./provider.js";
+import { warnDeprecatedStyleProps } from "./internal/deprecated-style.js";
 function resolveFieldAccessibleName(label, accessibilityLabel) {
     const visibleLabel = label?.trim();
     const explicitAccessibleName = accessibilityLabel?.trim();
@@ -28,10 +29,20 @@ function resolveFieldAccessibleName(label, accessibilityLabel) {
         ...(visibleLabel ? { visibleLabel } : {}),
     };
 }
-const FieldRenderer = forwardRef(function FieldRenderer({ label, value, defaultValue = "", onValueChange, description, error, required = false, disabled = false, busy = false, variant = fieldRecipe.defaults.variant, shape, accessibilityLabel, layoutStyle, allowFontScaling, multiline, maxVisibleLines, minVisibleLines, align = fieldRecipe.defaults.align, search, recipeInputStyle, searchSize = searchFieldRecipe.defaults.size, leading, trailing, onBlur, onFocus, ...props }, ref) {
+const FieldRenderer = forwardRef(function FieldRenderer({ label, value, defaultValue = "", onValueChange, description, error, required = false, disabled = false, busy = false, variant = fieldRecipe.defaults.variant, shape, accessibilityLabel, layoutStyle, allowFontScaling, multiline, maxVisibleLines, minVisibleLines, align = fieldRecipe.defaults.align, search, recipeInputStyle, disabledOpacity, searchSize = searchFieldRecipe.defaults.size, leading, trailing, leadingAction, hjmCompactMultiline = false, onBlur, onFocus, onContentSizeChange, onSelectionChange, ...props }, ref) {
+    const resolvedDisabledOpacity = disabledOpacity ?? (search ? searchFieldRecipe.states.disabledOpacity : fieldRecipe.disabledOpacity);
     const theme = useHjmNativeTheme();
     const { colors, environment, textScaling } = theme;
     const [focused, setFocused] = useState(false);
+    const [contentHeight, setContentHeight] = useState(0);
+    const inputRef = useRef(null);
+    const restoreFocusRef = useRef(false);
+    const selectionRef = useRef(null);
+    const attachInput = useCallback((node) => {
+        if (node === null)
+            restoreFocusRef.current = inputRef.current?.isFocused?.() ?? false;
+        inputRef.current = node;
+    }, []);
     const [currentValue, setCurrentValue] = useControllableState({
         ...(value === undefined ? {} : { value }),
         defaultValue,
@@ -65,16 +76,39 @@ const FieldRenderer = forwardRef(function FieldRenderer({ label, value, defaultV
         ? resolveColorReference(searchFieldRecipe.colors.placeholder, theme.palette)
         : colors[fieldRecipe.placeholder.color];
     const textStyle = typography[search ? searchSizing.textVariant : fieldRecipe.textVariant];
+    // Native TextInput scales its text without enlarging a fixed frame (BT-QA-020).
+    // Size the one-line frame for the same scale instead of capping accessible text.
+    const frameTextScale = textScaling.mode === "controlled"
+        ? textScaling.scale
+        : allowFontScaling === false
+            ? 1
+            : Math.min(textScaling.scale, props.maxFontSizeMultiplier && props.maxFontSizeMultiplier > 0 ? props.maxFontSizeMultiplier : Infinity);
+    const singleLineMinHeight = Math.ceil(textStyle.lineHeight * frameTextScale + fieldRecipe.paddingVertical * 2 + borderWidth * 2);
+    // iOS RCTUITextView updates typingAttributes/placeholder but leaves existing
+    // attributed text at its old scale (BT-QA-025). Refresh only the native editor,
+    // keeping the field's draft state and restoring focus/selection instead of capping text.
+    const editorKey = Platform.OS === "ios" && multiline
+        ? `multiline-${frameTextScale}`
+        : "field";
+    // Deps: only an editorKey remount changes the handle; none re-attached callback refs every render.
+    useImperativeHandle(ref, () => inputRef.current, [editorKey]);
+    useLayoutEffect(() => {
+        if (restoreFocusRef.current) {
+            inputRef.current?.focus?.();
+            const selection = props.selection ?? selectionRef.current;
+            if (selection)
+                inputRef.current?.setNativeProps?.({ selection });
+            restoreFocusRef.current = false;
+        }
+    }, [editorKey, props.selection]);
     // A composer that should open several lines tall asks in lines, not pixels,
-    // so the recipe keeps ownership of line height and vertical padding.
+    // so the recipe keeps ownership of line height and vertical padding. Compact: see field-private.ts.
     const minHeight = multiline
         ? minVisibleLines === undefined
             ? fieldRecipe.multilineMinHeight
-            : Math.max(fieldRecipe.multilineMinHeight, textStyle.lineHeight * minVisibleLines +
+            : Math.max(hjmCompactMultiline ? fieldRecipe.minHeight : fieldRecipe.multilineMinHeight, textStyle.lineHeight * minVisibleLines +
                 fieldRecipe.paddingVertical * 2)
-        : search
-            ? searchSizing.minHeight
-            : fieldRecipe.minHeight;
+        : Math.max(search ? searchSizing.minHeight : fieldRecipe.minHeight, singleLineMinHeight);
     const controlRadius = radius[search
         ? searchFieldRecipe.shapes[resolvedShape]
         : fieldRecipe.shapes[resolvedShape]];
@@ -88,6 +122,8 @@ const FieldRenderer = forwardRef(function FieldRenderer({ label, value, defaultV
             fontWeight: textStyle.fontWeight,
             lineHeight: textStyle.lineHeight,
             minHeight: minHeight - borderWidth * 2,
+            // Explicit line bounds opt into content-driven composer sizing, without changing ordinary editors.
+            ...(multiline && minVisibleLines !== undefined ? { height: Math.max(minHeight - borderWidth * 2, Math.min(currentValue ? contentHeight : 0, textStyle.lineHeight * (resolvedMaxVisibleLines ?? 1000) + fieldRecipe.paddingVertical * 2)) } : {}),
             ...(multiline &&
                 resolvedMaxVisibleLines !== null &&
                 resolvedMaxVisibleLines !== undefined
@@ -105,16 +141,8 @@ const FieldRenderer = forwardRef(function FieldRenderer({ label, value, defaultV
         },
         recipeInputStyle,
     ], allowFontScaling);
-    return (_jsx(NativeFieldFrame, { ...(visibleLabel === undefined ? {} : { label: visibleLabel }), required: required, ...(error === undefined ? {} : { error }), ...(supportText === undefined ? {} : { description: supportText }), style: [
-            {
-                opacity: disabled
-                    ? search
-                        ? searchFieldRecipe.states.disabledOpacity
-                        : fieldRecipe.disabledOpacity
-                    : 1,
-            },
-            layoutStyle,
-        ], children: _jsxs(View, { style: {
+    return (_jsx(NativeFieldFrame, { ...(visibleLabel === undefined ? {} : { label: visibleLabel }), required: required, ...(error === undefined ? {} : { error }), ...(supportText === undefined ? {} : { description: supportText }), ...(disabled ? { disabledOpacity: resolvedDisabledOpacity } : {}), style: layoutStyle, children: _jsxs(View, { style: {
+                opacity: disabled ? resolvedDisabledOpacity : 1,
                 alignItems: multiline ? "stretch" : "center",
                 backgroundColor,
                 borderColor,
@@ -127,13 +155,25 @@ const FieldRenderer = forwardRef(function FieldRenderer({ label, value, defaultV
                 paddingHorizontal: search
                     ? searchSizing.paddingHorizontal
                     : fieldRecipe.paddingHorizontal,
-            }, children: [leading ? (_jsx(View, { accessibilityElementsHidden: true, accessible: false, importantForAccessibility: "no-hide-descendants", children: leading })) : null, _jsx(TextInput, { ...props, ...inputTextScaleProps, ref: ref, accessibilityHint: hint, accessibilityLabel: accessibleName, accessibilityRole: search ? "search" : undefined, accessibilityState: { busy, disabled }, editable: !disabled && !busy, multiline: multiline, onBlur: (event) => {
+            }, children: [leading ? (_jsx(View, { accessibilityElementsHidden: true, accessible: false, importantForAccessibility: "no-hide-descendants", children: leading })) : null, leadingAction ? _jsx(View, { style: { alignSelf: "center" }, children: leadingAction }) : null, _jsx(TextInput, { ...props, ...inputTextScaleProps, ref: attachInput, accessibilityHint: hint, accessibilityLabel: accessibleName, accessibilityRole: search ? "search" : undefined, accessibilityState: { busy, disabled }, 
+                    // SearchField `busy` means "results are loading", not "this value is being committed":
+                    // locking the editor dropped every keystroke typed while suggestions refreshed, while the
+                    // Web SearchField keeps typing under `aria-busy` (2026-10-06 parity follow-up). Plain
+                    // fields keep the lock because their busy means a pending save of the current value.
+                    editable: !disabled && (search || !busy), multiline: multiline, onBlur: (event) => {
                         setFocused(false);
                         onBlur?.(event);
+                    }, onContentSizeChange: event => {
+                        if (multiline && minVisibleLines !== undefined)
+                            setContentHeight(event.nativeEvent.contentSize.height);
+                        onContentSizeChange?.(event);
+                    }, onSelectionChange: event => {
+                        selectionRef.current = event.nativeEvent.selection;
+                        onSelectionChange?.(event);
                     }, onChangeText: setCurrentValue, onFocus: (event) => {
                         setFocused(true);
                         onFocus?.(event);
-                    }, placeholderTextColor: placeholderColor, value: currentValue }), trailing] }) }));
+                    }, placeholderTextColor: placeholderColor, value: currentValue }, editorKey), trailing] }) }));
 });
 export const TextField = forwardRef(function TextField(props, ref) {
     return _jsx(FieldRenderer, { ...props, ref: ref, multiline: false, search: false });
@@ -142,6 +182,9 @@ export const TextArea = forwardRef(function TextArea(props, ref) {
     return _jsx(FieldRenderer, { ...props, ref: ref, multiline: true, search: false });
 });
 export const SearchField = forwardRef(function SearchField({ clearLabel, busyLabel, onClear, leading: leadingNode, trailing: trailingNode, renderLeading, renderClearIcon, renderBusyIndicator, value, defaultValue, onValueChange, size = searchFieldRecipe.defaults.size, busy = false, disabled = false, ...props }, ref) {
+    const inputRef = useRef(null);
+    // Single-line child editor never remounts.
+    useImperativeHandle(ref, () => inputRef.current, []);
     const theme = useHjmNativeTheme();
     const searchSizing = searchFieldRecipe.sizes[size];
     const iconProps = {
@@ -163,14 +206,16 @@ export const SearchField = forwardRef(function SearchField({ clearLabel, busyLab
         }, children: renderBusyIndicator?.(iconProps) ?? (_jsx(ActivityIndicator, { color: iconProps.color, size: iconProps.size })) })) : searchValue.length > 0 ? (_jsx(Pressable, { accessibilityLabel: clearLabel, accessibilityRole: "button", disabled: disabled, hitSlop: searchSizing.clearHitSlop, onPress: () => {
             setSearchValue("");
             onClear?.();
+            inputRef.current?.focus();
         }, style: {
             alignItems: "center",
             height: searchSizing.clearDiameter,
             justifyContent: "center",
             width: searchSizing.clearDiameter,
         }, children: renderClearIcon?.(iconProps) ?? (_jsx(Text, { align: "center", style: { fontSize: iconProps.size, lineHeight: iconProps.size }, tone: "muted", children: "\u00D7" })) })) : trailingNode;
-    return (_jsx(FieldRenderer, { ...props, ref: ref, busy: busy, disabled: disabled, leading: leading, multiline: false, onValueChange: (next) => {
-            if (!busy && !disabled)
+    return (_jsx(FieldRenderer, { ...props, ref: inputRef, busy: busy, disabled: disabled, leading: leading, multiline: false, onValueChange: (next) => {
+            // Typing continues while busy (same as Web `loading`); only disabled ignores input.
+            if (!disabled)
                 setSearchValue(next);
         }, search: true, searchSize: size, trailing: trailing, value: searchValue }));
 });
@@ -209,7 +254,8 @@ function DefaultPasswordToggleIcon({ color, revealed, size, }) {
 export const PasswordField = forwardRef(function PasswordField({ revealed: revealedProp, defaultRevealed = false, onRevealedChange, autofillHint, revealLabel, concealLabel, size = passwordFieldRecipe.defaults.size, renderToggleIcon, disabled = false, onSelectionChange, ...props }, forwardedRef) {
     const theme = useHjmNativeTheme();
     const inputRef = useRef(null);
-    useImperativeHandle(forwardedRef, () => inputRef.current);
+    // Single-line child editor never remounts.
+    useImperativeHandle(forwardedRef, () => inputRef.current, []);
     const selectionRef = useRef({ start: 0, end: 0 });
     const [revealed, setRevealed] = useControllableState({
         ...(revealedProp === undefined ? {} : { value: revealedProp }),
@@ -236,7 +282,9 @@ export const PasswordField = forwardRef(function PasswordField({ revealed: revea
         }, 0);
         return () => clearTimeout(timeout);
     }, [revealed]);
-    return (_jsx(FieldRenderer, { ...props, ref: inputRef, autoComplete: autofillHint === "current" ? "current-password" : "new-password", disabled: disabled, recipeInputStyle: [
+    return (_jsx(FieldRenderer, { ...props, ref: inputRef, autoComplete: autofillHint === "current" ? "current-password" : "new-password", disabled: disabled, 
+        // passwordFieldRecipe.states owns the amount; both renderers used the field default 0.6 until 2026-10-06.
+        disabledOpacity: passwordFieldRecipe.states.disabledOpacity, recipeInputStyle: [
             size === "large"
                 ? {
                     fontSize: typography.bodyLarge.fontSize,
@@ -247,7 +295,11 @@ export const PasswordField = forwardRef(function PasswordField({ revealed: revea
         ], multiline: false, onSelectionChange: (event) => {
             selectionRef.current = event.nativeEvent.selection;
             onSelectionChange?.(event);
-        }, search: false, secureTextEntry: resolved.nativeSecureTextEntry, textContentType: autofillHint === "current" ? "password" : "newPassword", trailing: (_jsx(Pressable, { accessibilityLabel: resolved.toggleAccessibleName, accessibilityRole: "button", accessibilityState: { disabled, selected: revealed }, disabled: disabled, onPress: () => setRevealed(!revealed), style: ({ pressed }) => ({
+        }, search: false, secureTextEntry: resolved.nativeSecureTextEntry, textContentType: autofillHint === "current" ? "password" : "newPassword", trailing: (_jsx(Pressable, { accessibilityLabel: resolved.toggleAccessibleName, accessibilityRole: "button", 
+            // No `selected`: the label already names the next action, and VoiceOver
+            // would read "Selected, Hide password" — the Native twin of the
+            // `aria-pressed` the contract rules out (password-field.md, rationale 1).
+            accessibilityState: { disabled }, disabled: disabled, onPress: () => setRevealed(!revealed), style: ({ pressed }) => ({
                 alignItems: "center",
                 height: metrics.toggleDiameter,
                 justifyContent: "center",
@@ -256,9 +308,13 @@ export const PasswordField = forwardRef(function PasswordField({ revealed: revea
             }), children: renderToggleIcon?.(appearance) ?? _jsx(DefaultPasswordToggleIcon, { ...appearance }) })) }));
 });
 /** One accessible numeric TextInput rendered through decorative OTP slots. */
-export const OtpField = forwardRef(function OtpField({ label, accessibilityLabel, description, error, required = false, disabled = false, busy = false, readOnly = false, length, value: valueProp, defaultValue = "", onValueChange, onComplete, size = otpFieldRecipe.defaults.size, presentation = "boxes", slotStyle, slotTextStyle, allowFontScaling, onBlur, onFocus, ...props }, ref) {
+export const OtpField = forwardRef(function OtpField({ label, accessibilityLabel, description, error, required = false, disabled = false, busy = false, readOnly = false, length, value: valueProp, defaultValue = "", onValueChange, onComplete, size = otpFieldRecipe.defaults.size, presentation = "boxes", slotStyle, slotTextStyle, 
+// Inherited from BaseFieldProps; before 1.13 it fell into `...props` and was spread onto the
+// hidden TextInput, so OtpField silently ignored its own canonical placement prop.
+layoutStyle, allowFontScaling, onBlur, onFocus, ...props }, ref) {
     const supportText = description;
     const theme = useHjmNativeTheme();
+    warnDeprecatedStyleProps("OtpField", { slotStyle, slotTextStyle }, "size/presentation for slot appearance and layoutStyle for placement");
     const { accessibleName, visibleLabel } = resolveFieldAccessibleName(label, accessibilityLabel);
     const [focused, setFocused] = useState(false);
     const [value, setValue] = useControllableState({
@@ -282,17 +338,20 @@ export const OtpField = forwardRef(function OtpField({ label, accessibilityLabel
     const invalidBorder = resolveColorReference(otpFieldRecipe.slot.invalidBorder, theme.palette);
     const filledBorder = resolveColorReference(otpFieldRecipe.slot.filledBorder, theme.palette);
     const contentColor = resolveColorReference(otpFieldRecipe.slot.content, theme.palette);
+    // fieldRecipe.disabledScope: label and slots fade; the hint/error below keep full contrast.
+    // The whole column used to fade (2026-10-06 change, same as Web).
+    const disabledOpacity = disabled || busy ? otpFieldRecipe.states.disabledOpacity : 1;
     return (_jsxs(View, { style: [
-            {
-                gap: fieldRecipe.label.gap,
-                opacity: disabled || busy ? otpFieldRecipe.states.disabledOpacity : 1,
-            },
+            { gap: fieldRecipe.label.gap },
+            layoutStyle,
         ], children: [visibleLabel ? (_jsxs(Text, { style: {
                     color: theme.colors[fieldRecipe.label.color],
                     fontWeight: fieldRecipe.label.fontWeight,
+                    opacity: disabledOpacity,
                 }, tone: "body", variant: fieldRecipe.label.textVariant, children: [visibleLabel, required ? " *" : ""] })) : null, _jsxs(View, { style: { gap: otpFieldRecipe.support.gap }, children: [_jsxs(View, { style: {
                             direction: "ltr",
                             maxWidth: metrics.slotSize * length + metrics.gap * (length - 1),
+                            opacity: disabledOpacity,
                             position: "relative",
                             width: "100%",
                         }, children: [_jsx(TextInput, { ...props, ref: ref, accessibilityHint: error ?? supportText, accessibilityLabel: accessibleName, accessibilityState: { busy, disabled: disabled || readOnly }, allowFontScaling: allowFontScaling, autoComplete: "one-time-code", caretHidden: true, editable: !disabled && !busy && !readOnly, keyboardType: "number-pad", maxLength: length, onBlur: (event) => {
@@ -341,7 +400,20 @@ export const OtpField = forwardRef(function OtpField({ label, accessibilityLabel
                                         ], children: _jsx(Text, { accessible: false, align: "center", allowFontScaling: allowFontScaling, style: [{ color: contentColor }, slotTextStyle], variant: metrics.textVariant, children: digit }) }, index));
                                 }) })] }), _jsx(FieldMessage, { ...(error === undefined ? {} : { error }), ...(supportText === undefined ? {} : { supportText }) })] })] }));
 });
-function ChoiceRow({ kind, label, description, checked, disabled, readOnly, required, invalid, readOnlyLabel, requiredLabel, invalidLabel, accessibilityHint, presentation = selectionControlRecipe.defaults.presentation, size = selectionControlRecipe.defaults.size, indicator = "default", leading, renderLeading, renderIndicator, onActivate, webTabIndex, style, controlStyle, indicatorStyle, leadingStyle, contentStyle, labelStyle, descriptionStyle, }) {
+const choiceVisualReplacement = "layoutStyle for placement and presentation/size/indicator/renderIndicator/renderLeading for appearance";
+/** Public choice components share one deprecated slot list; ChoiceRow itself stays silent. */
+function warnChoiceVisualStyles(component, visual) {
+    warnDeprecatedStyleProps(component, {
+        style: visual.style,
+        controlStyle: visual.controlStyle,
+        indicatorStyle: visual.indicatorStyle,
+        leadingStyle: visual.leadingStyle,
+        contentStyle: visual.contentStyle,
+        labelStyle: visual.labelStyle,
+        descriptionStyle: visual.descriptionStyle,
+    }, choiceVisualReplacement);
+}
+function ChoiceRow({ kind, label, description, checked, disabled, readOnly, required, invalid, readOnlyLabel, requiredLabel, invalidLabel, accessibilityHint, presentation = selectionControlRecipe.defaults.presentation, size = selectionControlRecipe.defaults.size, indicator = "default", leading, renderLeading, renderIndicator, onActivate, webTabIndex, layoutStyle, style, controlStyle, indicatorStyle, leadingStyle, contentStyle, labelStyle, descriptionStyle, }) {
     const theme = useHjmNativeTheme();
     const metrics = selectionControlRecipe.sizes[size];
     const plate = selectionControlRecipe.presentations[presentation];
@@ -418,6 +490,7 @@ function ChoiceRow({ kind, label, description, checked, disabled, readOnly, requ
                 paddingVertical: plate.useSizePadding ? metrics.paddingVertical : 0,
             },
             style,
+            layoutStyle,
         ], children: [indicator === "default" ? (_jsx(View, { accessibilityElementsHidden: true, accessible: false, importantForAccessibility: "no-hide-descendants", style: [
                     {
                         alignItems: "center",
@@ -448,6 +521,7 @@ function ChoiceRow({ kind, label, description, checked, disabled, readOnly, requ
                         ], variant: metrics.descriptionVariant, children: description })) : null] })] }));
 }
 export function Checkbox({ label, checked, defaultChecked = false, onCheckedChange, disabled = false, readOnly = false, required = false, invalid = false, description, readOnlyLabel, requiredLabel, invalidLabel, leading, renderLeading, renderIndicator, accessibilityHint, ...visual }) {
+    warnChoiceVisualStyles("Checkbox", visual);
     const [selected, setSelected] = useControllableState({
         ...(checked === undefined ? {} : { value: checked }),
         defaultValue: defaultChecked,
@@ -459,6 +533,7 @@ export function Checkbox({ label, checked, defaultChecked = false, onCheckedChan
 }
 /** Standalone native radio item. Prefer RadioGroup when group state is owned here. */
 export function Radio({ label, checked, defaultChecked = false, onCheckedChange, disabled = false, readOnly = false, required = false, invalid = false, description, readOnlyLabel, requiredLabel, invalidLabel, leading, renderLeading, renderIndicator, accessibilityHint, ...visual }) {
+    warnChoiceVisualStyles("Radio", visual);
     const [selected, setSelected] = useControllableState({
         ...(checked === undefined ? {} : { value: checked }),
         defaultValue: defaultChecked,
@@ -468,7 +543,7 @@ export function Radio({ label, checked, defaultChecked = false, onCheckedChange,
     });
     return (_jsx(ChoiceRow, { ...visual, accessibilityHint: accessibilityHint, checked: selected, description: description, disabled: disabled, indicator: visual.indicator ?? "default", invalid: invalid, invalidLabel: invalidLabel, kind: "radio", label: label, leading: leading, onActivate: () => setSelected(true), readOnly: readOnly, readOnlyLabel: readOnlyLabel, renderIndicator: renderIndicator, renderLeading: renderLeading, required: required, requiredLabel: requiredLabel }));
 }
-function ChoiceGroupFrame({ label, accessibilityLabel, required, requiredLabel, readOnly, readOnlyLabel, disabled, description, error, role, orientation, presentation, style, children, }) {
+function ChoiceGroupFrame({ label, accessibilityLabel, required, requiredLabel, readOnly, readOnlyLabel, disabled, description, error, role, orientation, presentation, style, layoutStyle, children, }) {
     const theme = useHjmNativeTheme();
     const id = useId().replaceAll(":", "");
     const labelId = `${id}-label`;
@@ -480,16 +555,18 @@ function ChoiceGroupFrame({ label, accessibilityLabel, required, requiredLabel,
     ].filter(Boolean).join(", ");
     const gap = selectionGroupRecipe.orientations[orientation].gap[presentation];
     return (_jsxs(View, { accessibilityHint: [error ?? description, readOnly ? readOnlyLabel : undefined]
-            .filter(Boolean).join(". ") || undefined, accessibilityLabel: announcedName, accessibilityLabelledBy: label ? labelId : undefined, accessibilityRole: role, accessibilityState: { disabled: disabled || readOnly }, accessibilityValue: error ? { text: error } : undefined, style: [{ direction: theme.environment.direction, gap: selectionGroupRecipe.supportGap }, style], children: [label ? (_jsxs(Text, { nativeID: labelId, tone: "primary", variant: selectionGroupRecipe.label.textVariant, children: [label, required ? requiredLabel ? ` (${requiredLabel})` : " *" : ""] })) : null, _jsx(View, { style: {
+            .filter(Boolean).join(". ") || undefined, accessibilityLabel: announcedName, accessibilityLabelledBy: label ? labelId : undefined, accessibilityRole: role, accessibilityState: { disabled: disabled || readOnly }, accessibilityValue: error ? { text: error } : undefined, style: [{ direction: theme.environment.direction, gap: selectionGroupRecipe.supportGap }, style, layoutStyle], children: [label ? (_jsxs(Text, { nativeID: labelId, tone: "primary", variant: selectionGroupRecipe.label.textVariant, children: [label, required ? requiredLabel ? ` (${requiredLabel})` : " *" : ""] })) : null, description && !error ? (_jsx(Text, { tone: "muted", variant: selectionGroupRecipe.description.textVariant, children: description })) : null, _jsx(View, { style: {
                     direction: theme.environment.direction,
                     flexDirection: orientation === "horizontal" && theme.environment.textScale < 1.6
                         ? "row"
                         : "column",
                     gap,
-                }, children: children }), error ? (_jsx(Text, { accessibilityLiveRegion: "assertive", accessibilityRole: "alert", tone: "danger", variant: selectionGroupRecipe.error.textVariant, children: error })) : description ? (_jsx(Text, { tone: "muted", variant: selectionGroupRecipe.description.textVariant, children: description })) : null] }));
+                }, children: children }), error ? (_jsx(Text, { accessibilityLiveRegion: "assertive", accessibilityRole: "alert", tone: "danger", variant: selectionGroupRecipe.error.textVariant, children: error })) : null] }));
 }
 export function RadioGroup(props) {
-    const { label, accessibilityLabel, items, value, defaultValue, onValueChange, required = false, disabled = false, readOnly = false, invalid = false, description, error, requiredLabel, readOnlyLabel, invalidLabel, orientation = selectionGroupBehaviorDefaults.orientation, presentation = selectionGroupRecipe.defaults.presentation, size = selectionControlRecipe.defaults.size, indicator = "default", renderLeading, renderIndicator, style, ...slotStyles } = props;
+    const { label, accessibilityLabel, items, value, defaultValue, onValueChange, required = false, disabled = false, readOnly = false, invalid = false, description, error, requiredLabel, readOnlyLabel, invalidLabel, orientation = selectionGroupBehaviorDefaults.orientation, presentation = selectionGroupRecipe.defaults.presentation, size = selectionControlRecipe.defaults.size, indicator = "default", renderLeading, renderIndicator, layoutStyle, style, ...slotStyles } = props;
+    // Group `style` paints the frame; the remaining slot styles reach every row.
+    warnChoiceVisualStyles("RadioGroup", { style, ...slotStyles });
     // Removed aliases must not silently change the selected collection in JavaScript callers.
     if ("options" in props || !Array.isArray(items))
         throw new TypeError("RadioGroup requires items; options was removed");
@@ -521,14 +598,15 @@ export function RadioGroup(props) {
             setSelected(selected);
     }, [selected, setSelected, storedValue, value]);
     const hasError = invalid || error !== undefined;
-    return (_jsx(ChoiceGroupFrame, { accessibilityLabel: accessibilityLabel, description: description, disabled: disabled, error: error, label: label, orientation: orientation, presentation: presentation, readOnly: readOnly, readOnlyLabel: readOnlyLabel, required: required, requiredLabel: requiredLabel, role: "radiogroup", style: style, children: resolvedItems.map((item) => {
+    return (_jsx(ChoiceGroupFrame, { accessibilityLabel: accessibilityLabel, description: description, disabled: disabled, error: error, label: label, orientation: orientation, presentation: presentation, readOnly: readOnly, readOnlyLabel: readOnlyLabel, required: required, requiredLabel: requiredLabel, role: "radiogroup", style: style, layoutStyle: layoutStyle, children: resolvedItems.map((item) => {
             const optionDisabled = disabled || item.disabled === true;
             const optionSelected = selected === item.value;
             return (_createElement(ChoiceRow, { ...slotStyles, key: item.value, accessibilityHint: item.accessibilityHint, checked: optionSelected, description: item.description, disabled: optionDisabled, indicator: indicator, invalid: hasError, invalidLabel: invalidLabel ?? error, kind: "radio", label: item.label, leading: item.leading, onActivate: () => setSelected(item.value), webTabIndex: !optionDisabled && !readOnly && item.value === webTabStop ? 0 : -1, presentation: presentation, readOnly: readOnly, readOnlyLabel: readOnlyLabel, renderIndicator: renderIndicator ? (props) => renderIndicator(item, props) : undefined, renderLeading: renderLeading ? (props) => renderLeading(item, props) : undefined, required: required, requiredLabel: requiredLabel, size: size }));
         }) }));
 }
 /** Validated controlled/uncontrolled checkbox collection using immutable Sets. */
-export function CheckboxGroup({ label, accessibilityLabel, items, value, defaultValue = new Set(), onValueChange, required = false, disabled = false, readOnly = false, invalid = false, description, error, requiredLabel, readOnlyLabel, invalidLabel, orientation = selectionGroupBehaviorDefaults.orientation, presentation = selectionGroupRecipe.defaults.presentation, size = selectionControlRecipe.defaults.size, indicator = "default", renderLeading, renderIndicator, style, ...slotStyles }) {
+export function CheckboxGroup({ label, accessibilityLabel, items, value, defaultValue = new Set(), onValueChange, required = false, disabled = false, readOnly = false, invalid = false, description, error, requiredLabel, readOnlyLabel, invalidLabel, orientation = selectionGroupBehaviorDefaults.orientation, presentation = selectionGroupRecipe.defaults.presentation, size = selectionControlRecipe.defaults.size, indicator = "default", renderLeading, renderIndicator, layoutStyle, style, ...slotStyles }) {
+    warnChoiceVisualStyles("CheckboxGroup", { style, ...slotStyles });
     validateSelectionItems(items);
     if (value !== undefined)
         validateCheckboxSelection(items, value);
@@ -543,7 +621,7 @@ export function CheckboxGroup({ label, accessibilityLabel, items, value, default
             setSelected(selected);
     }, [selected, setSelected, storedValue, value]);
     const hasError = invalid || error !== undefined;
-    return (_jsx(ChoiceGroupFrame, { accessibilityLabel: accessibilityLabel, description: description, disabled: disabled, error: error, label: label, orientation: orientation, presentation: presentation, readOnly: readOnly, readOnlyLabel: readOnlyLabel, required: required, requiredLabel: requiredLabel, style: style, children: items.map((item) => {
+    return (_jsx(ChoiceGroupFrame, { accessibilityLabel: accessibilityLabel, description: description, disabled: disabled, error: error, label: label, orientation: orientation, presentation: presentation, readOnly: readOnly, readOnlyLabel: readOnlyLabel, required: required, requiredLabel: requiredLabel, style: style, layoutStyle: layoutStyle, children: items.map((item) => {
             const optionDisabled = disabled || item.disabled === true;
             const optionSelected = selected.has(item.id);
             return (_createElement(ChoiceRow, { ...slotStyles, key: item.id, checked: optionSelected, description: item.description, disabled: optionDisabled, indicator: indicator, invalid: hasError, invalidLabel: invalidLabel ?? error, kind: "checkbox", label: item.label, onActivate: () => setSelected(toggleCheckboxSelection(items, selected, item.id)), presentation: presentation, readOnly: readOnly, readOnlyLabel: readOnlyLabel, renderIndicator: renderIndicator ? (props) => renderIndicator(item, props) : undefined, renderLeading: renderLeading ? (props) => renderLeading(item, props) : undefined, required: required, requiredLabel: requiredLabel, size: size }));
@@ -554,6 +632,7 @@ export function Switch({ label, labelVisibility = "visible", presentation = swit
     if (["value", "defaultValue", "onValueChange"].some(key => key in props)) {
         throw new TypeError("Switch no longer accepts value/defaultValue/onValueChange; use checked/defaultChecked/onCheckedChange");
     }
+    warnDeprecatedStyleProps("Switch", { style }, "layoutStyle for placement and presentation/size for appearance");
     const { colors, environment, ...nativeTheme } = useHjmNativeTheme();
     const dimensions = switchRecipe.sizes[size];
     const stacked = presentation === "row" && labelVisibility === "visible"
@@ -610,15 +689,19 @@ export function Switch({ label, labelVisibility = "visible", presentation = swit
                     : { height: dimensions.height, width: dimensions.width }, thumbColor: thumb, trackColor: { false: trackOff, true: trackOn }, value: enabled })] }));
 }
 export function SegmentedControl(props) {
-    const { label, items, value, defaultValue, onValueChange, size = segmentedControlRecipe.defaults.size, disabled = false, style, } = props;
+    const { label, items, value, defaultValue, onValueChange, size = segmentedControlRecipe.defaults.size, presentation = "connected", disabled = false, layoutStyle, style, } = props;
     // Removed aliases must not silently change the selected collection in JavaScript callers.
     if ("options" in props || !Array.isArray(items))
         throw new TypeError("SegmentedControl requires items; options was removed");
+    warnDeprecatedStyleProps("SegmentedControl", { style }, "layoutStyle for placement and size for appearance");
+    const pills = presentation === "pills";
     const resolvedItems = items;
     const theme = useHjmNativeTheme();
     const { environment } = theme;
     const sizeContract = segmentedControlRecipe.sizes[size];
-    const stacked = segmentedControlRecipe.adaptive.largeTextLayout === "stacked"
+    // Pills keep their row at large text (segmentedControlRecipe.pills.largeTextLayout, 1.13.1): they wrap in a
+    // block and stay one line in a rail. Stacking them made a filter rail a ~440pt column (utilverse, 2026-10-06).
+    const stacked = !pills && segmentedControlRecipe.adaptive.largeTextLayout === "stacked"
         && environment.textScale >= segmentedControlRecipe.adaptive.stackAtFontScale;
     const descriptors = resolvedItems.map((item) => ({
         id: item.value,
@@ -651,21 +734,23 @@ export function SegmentedControl(props) {
     }, [collectionFallback, controlled, setSelected, storedValueValid]);
     return (_jsx(View, { accessibilityLabel: label, accessibilityRole: "radiogroup", style: [
             {
-                backgroundColor: resolveColorReference(segmentedControlRecipe.container.background, theme.palette),
+                backgroundColor: pills ? "transparent" : resolveColorReference(segmentedControlRecipe.container.background, theme.palette),
                 borderColor: resolveColorReference(segmentedControlRecipe.container.border, theme.palette),
                 borderRadius: radius[segmentedControlRecipe.container.radius],
-                borderWidth: segmentedControlRecipe.container.borderWidth,
+                borderWidth: pills ? 0 : segmentedControlRecipe.container.borderWidth,
                 direction: environment.direction,
                 flexDirection: stacked ? "column" : "row",
-                gap: segmentedControlRecipe.container.gap,
-                padding: segmentedControlRecipe.container.padding,
+                flexWrap: pills ? "wrap" : "nowrap",
+                gap: pills ? segmentedControlRecipe.pills.gap : segmentedControlRecipe.container.gap,
+                padding: pills ? 0 : segmentedControlRecipe.container.padding,
             },
             style,
+            layoutStyle,
         ], children: resolvedItems.map((item) => {
             const isSelected = item.value === selected;
             const optionDisabled = disabled || item.disabled === true;
             const contentColor = resolveColorReference(isSelected
-                ? segmentedControlRecipe.item.selectedContent
+                ? (pills ? segmentedControlRecipe.pills.selectedContent : segmentedControlRecipe.item.selectedContent)
                 : segmentedControlRecipe.item.idleContent, theme.palette);
             const leading = item.leading ?? item.renderLeading?.({
                 selected: isSelected,
@@ -676,29 +761,31 @@ export function SegmentedControl(props) {
             return (_jsxs(Pressable, { accessibilityLabel: item.label, accessibilityRole: "radio", accessibilityState: { checked: isSelected, disabled: optionDisabled }, disabled: optionDisabled, hitSlop: sizeContract.hitSlop, onPress: () => setSelected(item.value), style: ({ pressed }) => [
                     {
                         alignItems: "center",
-                        backgroundColor: isSelected
+                        backgroundColor: !pills && isSelected
                             ? resolveColorReference(segmentedControlRecipe.item.selectedBackground, theme.palette)
                             : "transparent",
                         borderColor: isSelected
                             ? resolveColorReference(segmentedControlRecipe.item.selectedBorder, theme.palette)
                             : "transparent",
                         borderRadius: radius[segmentedControlRecipe.item.radius],
-                        borderWidth: isSelected
+                        borderWidth: !pills && isSelected
                             ? segmentedControlRecipe.item.selectedBorderWidth
                             : 0,
-                        flex: stacked ? undefined : 1,
+                        flex: stacked || pills ? undefined : 1,
+                        maxWidth: pills ? "100%" : undefined,
                         gap: segmentedControlRecipe.item.gap,
                         justifyContent: "center",
-                        minHeight: sizeContract.minHeight,
+                        minHeight: pills ? segmentedControlRecipe.pills.minHeight : sizeContract.minHeight,
                         opacity: optionDisabled
                             ? segmentedControlRecipe.item.disabledOpacity
                             : pressed
                                 ? segmentedControlRecipe.item.pressedOpacity
                                 : 1,
-                        paddingHorizontal: sizeContract.paddingHorizontal,
+                        paddingHorizontal: pills ? spacing.md : sizeContract.paddingHorizontal,
+                        paddingVertical: pills ? segmentedControlRecipe.pills.inset : undefined,
                         width: stacked ? "100%" : undefined,
                     },
-                ], children: [leading ? (_jsx(View, { accessibilityElementsHidden: true, accessible: false, importantForAccessibility: "no-hide-descendants", children: leading })) : null, _jsx(Text, { align: "center", style: {
+                ], children: [pills ? _jsx(View, { pointerEvents: "none", accessible: false, style: { position: "absolute", left: 0, right: 0, top: segmentedControlRecipe.pills.inset, bottom: segmentedControlRecipe.pills.inset, borderRadius: segmentedControlRecipe.pills.radius, backgroundColor: isSelected ? resolveColorReference(segmentedControlRecipe.pills.selectedBackground, theme.palette) : theme.colors.surfaceAlt } }) : null, leading ? (_jsx(View, { accessibilityElementsHidden: true, accessible: false, importantForAccessibility: "no-hide-descendants", children: leading })) : null, _jsx(Text, { align: "center", style: {
                             color: contentColor,
                             fontWeight: isSelected
                                 ? segmentedControlRecipe.item.selectedFontWeight
@@ -709,6 +796,7 @@ export function SegmentedControl(props) {
 /** Action/filter chip with role-specific, controlled selection semantics. */
 export function Chip({ label, size = chipRecipe.defaults.size, disabled = false, leading, trailing, accessibilityLabel, accessibilityHint, layoutStyle, leadingStyle, indicatorStyle, labelStyle, trailingStyle, renderSelectionIndicator, selectionMode = "action", selected, onPress, }) {
     const theme = useHjmNativeTheme();
+    warnDeprecatedStyleProps("Chip", { labelStyle }, "size/selected for label typography");
     const selectable = selectionMode !== "action";
     const active = selectable && selected === true;
     const metrics = chipRecipe.sizes[size];
@@ -746,7 +834,10 @@ export function Chip({ label, size = chipRecipe.defaults.size, disabled = false,
                 direction: theme.environment.direction,
                 flexDirection: "row",
                 gap: metrics.gap,
-                height: visibleControlHeight(metrics.height, theme.environment.minimumVisualTarget),
+                // A floor, not a fixed height, as Button does for text content and as Web `.hjm-chip` already does
+                // (min-block-size): the fixed 36 clipped the filter-trigger and suggested-query labels at accessibility-large
+                // (utilverse 1.13.0 adoption, 2026-10-06). At 1x the label fits, so the chip is still 36.
+                minHeight: visibleControlHeight(metrics.height, theme.environment.minimumVisualTarget),
                 opacity: disabled
                     ? chipRecipe.states.disabledOpacity
                     : pressed