@octane-xplat/ui 0.9.0 → 0.11.0

package/src/Screen.tsrx

@@ -2,7 +2,7 @@
 import type { ScreenProps } from "./props";
 import { cx } from "./cx";
 import { applyEscapeProps } from "./escape-props";
-import { registerRootLayout, unregisterRootLayout } from "./root-layout.mobile";
+import { registerRootLayout, unregisterRootLayout } from "./root-layout";
 import { attachTapToBlur } from "./tap-to-blur";
 // The screen shell is a RootLayout so RootLayout.open() can layer overlays
 // over it (decision #22). Self-registers on loaded/unloaded — overlay and

package/src/ScrollableArea.macos.tsrx

@@ -0,0 +1,20 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import type { ScrollableAreaProps } from './props'
+
+/** AppKit NSScrollView leaf. `axis` maps the same way as on NativeScript;
+ *  `axis: 'both'` isn't supported by the AppKit leaf — the scroller
+ *  follows the block axis there (documented deviation). Pull-to-refresh
+ *  props are ignored on macOS. */
+export function ScrollableArea(props: ScrollableAreaProps) @{
+	const horizontal = props.axis === 'inline';
+
+	<scrollview
+		id={props.id}
+		className={props.className}
+		style={props.style}
+		horizontal={horizontal as any}
+		accessibilityLabel={props.accessibilityLabel ?? props.label}
+	>
+		<flexboxlayout flexDirection={horizontal ? 'row' : 'column'}>{props.children}</flexboxlayout>
+	</scrollview>
+}

package/src/ScrollableArea.tsrx

@@ -0,0 +1,159 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useMemo, useEffect, useRef } from 'octane';
+import { mergedRef } from './ref-list'
+import type { ScrollableAreaProps } from './props';
+import type { RefreshConfig, RefreshController } from './refresh';
+import { cx } from './cx';
+import { applyEscapeProps, nativeAccessibilityRole, nativeAccessibilityState } from './escape-props';
+import { layoutChildProps } from './layout-child';
+import { ActivityIndicator } from './ActivityIndicator.tsrx';
+import { REFRESH_HEADER_HEIGHT } from './refresh-metrics';
+import { createPullToRefresh } from './refresh';
+import { spacingStep } from './spacing';
+
+/** Native padding — logical start/end map to left/right (NativeScript has
+ *  no logical properties; RTL mirroring is the app's escape-hatch job). */
+function contentPadding(props: ScrollableAreaProps) {
+	const p = spacingStep(props.padding);
+	const style: Record<string, any> = {};
+	style.paddingTop = spacingStep(props.paddingBlockStart) ?? spacingStep(props.paddingBlock) ?? p ?? 0;
+	style.paddingBottom = spacingStep(props.paddingBlockEnd) ?? spacingStep(props.paddingBlock) ?? p ?? 0;
+	style.paddingLeft = spacingStep(props.paddingInlineStart) ?? spacingStep(props.paddingInline) ?? p ?? 0;
+	style.paddingRight = spacingStep(props.paddingInlineEnd) ?? spacingStep(props.paddingInline) ?? p ?? 0;
+	return style;
+}
+
+const a11y = (props: ScrollableAreaProps) => ({
+	accessible: props.accessible,
+	// `label` is the Astryx contract; `accessibilityLabel` still wins when
+	// both are given.
+	accessibilityLabel: props.accessibilityLabel ?? props.label,
+	accessibilityRole: nativeAccessibilityRole(props.accessibilityRole) as any,
+	accessibilityHint: props.accessibilityHint,
+	accessibilityValue: props.accessibilityValue,
+	accessibilityState: nativeAccessibilityState(props.accessibilityState) as any,
+	accessibilityLiveRegion: props.accessibilityLiveRegion as any,
+});
+
+/** Pull-enabled variant — the grid wrapper hosts the scroller plus the
+ *  self-drawn indicator strip; refresh.ts owns the gesture. Only the
+ *  block axis pulls. */
+function ScrollableAreaRefreshable(props: ScrollableAreaProps) @{
+	const cfg = useRef<RefreshConfig>({});
+	cfg.current = {
+		onRefresh: props.onRefresh,
+		refreshing: props.refreshing,
+		threshold: props.refreshThreshold,
+	};
+
+	const ctl = useRef<RefreshController | null>(null);
+	const scroller = useRef<any>(null);
+	const indicator = useRef<any>(null);
+
+	useEffect(() => {
+		if (!scroller.current || !indicator.current) return;
+		ctl.current = createPullToRefresh({
+			scroller: scroller.current,
+			indicator: indicator.current,
+			isAtTop: () => scroller.current?.verticalOffset <= 0,
+			cfg,
+		});
+
+		return () => {
+			ctl.current?.detach();
+			ctl.current = null;
+		};
+	}, []);
+
+	useEffect(() => {
+		ctl.current?.sync();
+	}, [props.refreshing]);
+
+	const forwardedRef = useMemo(() => mergedRef((v: any) => {
+				scroller.current = v;
+				applyEscapeProps(v, props);
+			}, props.ref), [props.ref, props.ios, props.android, props.web]);
+
+	<gridlayout
+		ref={(v: any) => {
+			if (v?.ios) v.ios.clipsToBounds = true;
+		}}
+		{...layoutChildProps(props)}
+		className={cx('vx-refresh-wrap', props.className)}
+		style={props.style}
+	>
+		<scrollview
+			ref={forwardedRef}
+			id={props.id}
+			className="vx-scrollable"
+			orientation="vertical"
+			{...a11y(props)}
+		>
+			<flexboxlayout flexDirection="column" style={contentPadding(props)}>
+				{props.children}
+			</flexboxlayout>
+		</scrollview>
+		<flexboxlayout
+			ref={(v: any) => {
+				indicator.current = v;
+			}}
+			className="vx-refresh"
+			verticalAlignment="top"
+			height={REFRESH_HEADER_HEIGHT}
+			translateY={-REFRESH_HEADER_HEIGHT}
+		>
+			<ActivityIndicator />
+		</flexboxlayout>
+	</gridlayout>
+}
+
+/** Scroll viewport (Astryx `ScrollableArea`). NativeScript's ScrollView
+ *  hosts exactly one child, so children wrap in a content flexboxlayout —
+ *  the padding + content box lives there. `axis: 'both'` nests a
+ *  horizontal scroller inside the vertical one (NS has no two-axis
+ *  ScrollView). `overscroll`/`stickyContainment`/`isFullBleed` are web
+ *  semantics and inert here; `role` has no native equivalent. */
+export function ScrollableArea(props: ScrollableAreaProps) @{
+	const axis = props.axis ?? 'block';
+	const horizontal = axis === 'inline';
+	const both = axis === 'both';
+
+	const forwardedRef = useMemo(() => mergedRef((v: any) => {
+				applyEscapeProps(v, props);
+			}, props.ref), [props.ref, props.ios, props.android, props.web]);
+
+	@if (axis === 'block' && (props.onRefresh != null || props.refreshing != null)) {
+		<ScrollableAreaRefreshable {...props} />
+	} @else {
+		<scrollview
+			ref={forwardedRef}
+			id={props.id}
+			{...layoutChildProps(props)}
+			className={cx('vx-scrollable', props.className)}
+			style={{
+				width: props.width as any,
+				height: props.height as any,
+				maxWidth: props.maxWidth as any,
+				minHeight: props.minHeight as any,
+				...props.style,
+			}}
+			orientation={both ? 'vertical' : horizontal ? 'horizontal' : 'vertical'}
+			{...a11y(props)}
+		>
+			{both ? (
+				<scrollview orientation="horizontal">
+					<flexboxlayout flexDirection="row" style={contentPadding(props)}>
+						{props.children}
+					</flexboxlayout>
+				</scrollview>
+			) : (
+				<flexboxlayout
+					flexDirection={horizontal ? 'row' : 'column'}
+					style={contentPadding(props)}
+				>
+					{props.children}
+				</flexboxlayout>
+			)}
+		</scrollview>
+	}
+}

package/src/ScrollableArea.web.tsrx

@@ -0,0 +1,183 @@
+import { useMemo, useEffect, useRef } from 'octane';
+import { refList } from './ref-list'
+import type { ScrollableAreaProps } from './props';
+import type { RefreshConfig, RefreshController } from './refresh.web';
+import { applyEscapeProps } from './escape-props';
+import { layoutChildProps } from './layout-child.web';
+import { ActivityIndicator } from './ActivityIndicator.web.tsrx';
+import { REFRESH_HEADER_HEIGHT } from './refresh-metrics';
+import { createPullToRefresh } from './refresh.web';
+import { useScrollableArea } from './use-scrollable-area.web.tsrx';
+import { spacingStep } from './spacing';
+
+const size = (v: number | string | undefined) =>
+	v == null ? undefined : typeof v === 'number' ? `${v}px` : v;
+
+function contentPadding(props: ScrollableAreaProps) {
+	const inline = spacingStep(props.paddingInline ?? props.padding);
+	const block = spacingStep(props.paddingBlock ?? props.padding);
+	const style: Record<string, any> = {};
+	if (inline != null) {
+		style.paddingInlineStart = `${spacingStep(props.paddingInlineStart) ?? inline}px`;
+		style.paddingInlineEnd = `${spacingStep(props.paddingInlineEnd) ?? inline}px`;
+	} else {
+		if (props.paddingInlineStart != null) {
+			style.paddingInlineStart = `${spacingStep(props.paddingInlineStart)}px`;
+		}
+
+		if (props.paddingInlineEnd != null) {
+			style.paddingInlineEnd = `${spacingStep(props.paddingInlineEnd)}px`;
+		}
+	}
+
+	if (block != null) {
+		style.paddingBlockStart = `${spacingStep(props.paddingBlockStart) ?? block}px`;
+		style.paddingBlockEnd = `${spacingStep(props.paddingBlockEnd) ?? block}px`;
+	} else {
+		if (props.paddingBlockStart != null) {
+			style.paddingBlockStart = `${spacingStep(props.paddingBlockStart)}px`;
+		}
+
+		if (props.paddingBlockEnd != null) {
+			style.paddingBlockEnd = `${spacingStep(props.paddingBlockEnd)}px`;
+		}
+	}
+
+	return style;
+}
+
+/** Pull-enabled variant — same structure the old ScrollView used: a
+ *  relative wrapper hosts the scroller plus the self-drawn indicator
+ *  strip; refresh.web.ts owns the gesture. Only the block axis pulls. */
+function ScrollableAreaRefreshable(props: ScrollableAreaProps) @{
+	const area = useScrollableArea({
+		axis: props.axis,
+		overscroll: props.overscroll,
+		stickyContainment: props.stickyContainment,
+		keyboardAccess: { owner: 'viewport', label: props.label ?? '', role: props.role },
+	});
+
+	const cfg = useRef<RefreshConfig>({});
+	cfg.current = {
+		onRefresh: props.onRefresh,
+		refreshing: props.refreshing,
+		threshold: props.refreshThreshold,
+	};
+
+	const ctl = useRef<RefreshController | null>(null);
+	const scroller = useRef<HTMLElement | null>(null);
+	const indicator = useRef<HTMLElement | null>(null);
+
+	useEffect(() => {
+		if (!scroller.current || !indicator.current) return;
+		ctl.current = createPullToRefresh({
+			scroller: scroller.current,
+			indicator: indicator.current,
+			cfg,
+		});
+
+		return () => {
+			ctl.current?.detach();
+			ctl.current = null;
+		};
+	}, []);
+
+	useEffect(() => {
+		ctl.current?.sync();
+	}, [props.refreshing]);
+
+	const { ref: viewportRef, ...viewport } = area.getViewportProps();
+	const { ref: contentRef, ...content } = area.getContentProps();
+
+	const forwardedRef = useMemo(() => [(el: any) => {
+				scroller.current = el;
+
+				applyEscapeProps(el, props);
+			}, viewportRef, props.ref], [props.ref, props.ios, props.android, props.web, viewportRef]);
+
+	<div {...layoutChildProps(props, { ...props.style })} className={['vx-refresh-wrap', props.className]}>
+		<div
+			ref={(el: any) => {
+				indicator.current = el;
+			}}
+			className="vx-refresh"
+			style={{ transform: `translateY(${-REFRESH_HEADER_HEIGHT}px)` }}
+			aria-hidden="true"
+		>
+			<ActivityIndicator />
+		</div>
+		<div
+			{...viewport}
+			ref={forwardedRef}
+			id={props.id}
+			className={['vx-scrollable', viewport.className]}
+			style={{
+				...viewport.style,
+				width: size(props.width),
+				height: size(props.height),
+				maxWidth: size(props.maxWidth),
+				minHeight: size(props.minHeight),
+			}}
+		>
+			<div {...content} ref={contentRef} className={['vx-scrollable-content', content.className]} style={{ ...content.style, ...contentPadding(props) }}>
+				{props.children}
+			</div>
+		</div>
+	</div>
+}
+
+/** Scroll viewport (Astryx `ScrollableArea`): axis-aware scrolling with a
+ *  named, keyboard-scrollable viewport and live overflow state — see
+ *  `useScrollableArea` for the measurement. `overscroll` maps to
+ *  `overscroll-behavior`; `stickyContainment` keeps the scroller as the
+ *  sticky boundary; `isFullBleed` is inert here (no container-padding
+ *  protocol exists yet — documented deviation). */
+export function ScrollableArea(props: ScrollableAreaProps) @{
+	const axis = props.axis ?? 'block';
+
+	@if (axis === 'block' && (props.onRefresh != null || props.refreshing != null)) {
+		<ScrollableAreaRefreshable {...props} />
+	} @else {
+		<ScrollableAreaCore {...props} />
+	}
+}
+
+function ScrollableAreaCore(props: ScrollableAreaProps) @{
+	const area = useScrollableArea({
+		axis: props.axis,
+		overscroll: props.overscroll,
+		stickyContainment: props.stickyContainment,
+		keyboardAccess: { owner: 'viewport', label: props.label ?? '', role: props.role },
+	});
+
+	const { ref: viewportRef, ...viewport } = area.getViewportProps();
+	const { ref: contentRef, ...content } = area.getContentProps();
+	const outer = layoutChildProps(props, { ...props.style });
+
+	const forwardedRef = useMemo(() => refList((el: any) => applyEscapeProps(el, props), viewportRef, props.ref), [props.ref, props.ios, props.android, props.web, viewportRef]);
+
+	<div
+		{...viewport}
+		ref={forwardedRef}
+		id={props.id}
+		className={['vx-scrollable', props.className]}
+		style={{
+			...viewport.style,
+			...outer.style,
+			width: size(props.width) ?? outer.style?.width,
+			height: size(props.height) ?? outer.style?.height,
+			maxWidth: size(props.maxWidth),
+			minHeight: size(props.minHeight),
+		}}
+		aria-hidden={props.accessible === false ? true : undefined}
+	>
+		<div
+			{...content}
+			ref={contentRef}
+			className={['vx-scrollable-content', content.className]}
+			style={{ ...content.style, ...contentPadding(props) }}
+		>
+			{props.children}
+		</div>
+	</div>
+}

package/src/SearchInput.tsrx

@@ -1,9 +1,9 @@
 /** @jsxImportSource @nativescript-community/octane */
-import { useEffect, useRef, useState } from 'octane';
+import { useImperativeHandle, useEffect, useRef, useState } from 'octane';
 import type { SearchInputProps } from './props';
-import { Icon } from './Icon.tsrx';
+import { Icon } from './Icon';
 import { cx } from './cx';
-import { applyEscapeProps } from './escape-props';
+import { applyEscapeProps, nativeAccessibilityState } from './escape-props';
 import { isWritingText, writeText } from './text-write';
 import { blurText } from './text-focus';
 
@@ -16,6 +16,8 @@ export function SearchInput(props: SearchInputProps) @{
 	const el = useRef<any>(null);
 	const [internal, setInternal] = useState(props.defaultValue ?? '');
 	const value = props.value ?? internal;
+	const isBlocked = props.isDisabled || props.isReadOnly;
+	const hasClear = props.hasClear !== false;
 	useEffect(() => writeText(el.current, value), [value]);
 
 	const setValue = (next: string) => {
@@ -24,35 +26,39 @@ export function SearchInput(props: SearchInputProps) @{
 	};
 
 	const clear = () => {
+		if (isBlocked || !hasClear) return;
 		setValue('');
 		props.onClear?.();
 	};
 
+	useImperativeHandle(props.ref, () => ({ focus: () => el.current.focus(), blur: () => blurText(el.current), native: el.current }), []);
+
 	<flexboxlayout
 		ref={(v: any) => applyEscapeProps(v, props)}
 		id={props.id}
 		flexDirection="row"
-		className={cx('vx-search', props.editable === false && 'vx-search--disabled', props.className)}
+		className={cx('vx-search', props.isDisabled && 'vx-search--disabled', props.isReadOnly && 'vx-search--readonly', props.isLoading && 'vx-search--loading', props.status && `vx-search--status-${props.status.type}`, props.size && `vx-search--size-${props.size}`, props.className)}
 		style={props.style}
-		accessibilityLabel={props.accessibilityLabel}
+		accessibilityLabel={props.accessibilityLabel ?? props.label}
+		accessibilityState={nativeAccessibilityState({ disabled: props.isDisabled }) as any}
 	>
 		{props.icon !== false ? <Icon name={props.icon ?? 'xplat-search'} size={16} className="vx-search-icon" /> : null}
 		<textfield
 			ref={(v: any) => {
 				el.current = v;
 				if (!v) return;
-				props.bind?.({ focus: () => v.focus(), blur: () => blurText(v), native: v });
 			}}
 			className="vx-search-field"
 			hint={props.placeholder}
 			returnKeyType="search"
-			editable={props.editable ?? true}
+			isEnabled={!props.isDisabled}
+			editable={!isBlocked}
 			onTextChange={(e: any) => { if (!isWritingText(e.object)) setValue(e.value); }}
 			onReturnPress={props.onSubmit}
 			onFocus={props.onFocus}
 			onBlur={props.onBlur}
 		/>
-		{value !== '' && props.editable !== false ? (
+		{value !== '' && hasClear && !isBlocked ? (
 			<flexboxlayout className="vx-search-clear" accessibilityLabel="Clear search" onTap={clear}>
 				<Icon name="xplat-clear" size={12} />
 			</flexboxlayout>

package/src/SearchInput.web.test.tsrx

@@ -2,6 +2,10 @@
 import { describe, expect, it, vi } from 'vitest';
 import { act, createRoot } from 'octane';
 import { SearchInput } from './SearchInput.web.tsrx';
+import { TextInput } from './TextInput.web.tsrx';
+import { PinInput } from './PinInput.web.tsrx';
+import { Select } from './Select.web.tsrx';
+import { FormField } from './FormField.web.tsrx';
 
 describe('SearchInput (web leaf)', () => {
 	it('renders the shell, default glyph, and a clear button once text is present', () => {
@@ -56,3 +60,164 @@ describe('SearchInput (web leaf)', () => {
 		el.remove();
 	});
 });
+
+describe('TextInput field props (web leaf)', () => {
+	it('clears only when requested and reports clear after the empty value', () => {
+		const onChange = vi.fn();
+		const onClear = vi.fn();
+		const el = document.createElement('div');
+		document.body.appendChild(el);
+		const root = createRoot(el);
+		act(() => root.render(<TextInput label="Name" value="Ada" onChange={onChange} />));
+		expect(el.querySelector('.vx-input-clear')).toBeNull();
+
+		act(() => root.render(<TextInput label="Name" value="Ada" hasClear onChange={onChange} onClear={onClear} />));
+		const clear = el.querySelector('.vx-input-clear') as HTMLButtonElement;
+		expect(clear.getAttribute('aria-label')).toBe('Clear Name');
+		act(() => clear.click());
+		expect(onChange).toHaveBeenCalledWith('');
+		expect(onClear).toHaveBeenCalledTimes(1);
+
+		act(() => root.render(<TextInput label="Name" value="" hasClear onChange={onChange} onClear={onClear} />));
+		expect(el.querySelector('.vx-input-clear')).toBeNull();
+		root.unmount();
+		el.remove();
+	});
+
+	it('keeps loading separate from disabled and blocks clear while read-only', () => {
+		const el = document.createElement('div');
+		const root = createRoot(el);
+		act(() => root.render(<TextInput value="Ada" hasClear isLoading isReadOnly />));
+		const input = el.querySelector('.vx-input') as HTMLInputElement;
+		expect(input.readOnly).toBe(true);
+		expect(input.disabled).toBe(false);
+		expect(input.getAttribute('aria-busy')).toBe('true');
+		expect(el.querySelector('.vx-input-clear')).toBeNull();
+		root.unmount();
+	});
+});
+
+describe('Select field props (web leaf)', () => {
+	it('clears a selected value without opening the trigger', () => {
+		const onValueChange = vi.fn();
+		const onClear = vi.fn();
+		const onOpenChange = vi.fn();
+		const el = document.createElement('div');
+		document.body.appendChild(el);
+		const root = createRoot(el);
+		act(() => root.render(
+			<Select
+				label="Country"
+				options={[{ value: 'nz', label: 'New Zealand' }]}
+				defaultValue="nz"
+				hasClear
+				onValueChange={onValueChange}
+				onClear={onClear}
+				onOpenChange={onOpenChange}
+			/>,
+		));
+
+		act(() => (el.querySelector('.vx-select-clear') as HTMLButtonElement).click());
+
+		expect(onValueChange).toHaveBeenCalledWith(null);
+		expect(onClear).toHaveBeenCalledTimes(1);
+		expect(onOpenChange).toHaveBeenCalledTimes(1);
+		expect(onOpenChange).toHaveBeenCalledWith(false);
+		root.unmount();
+		el.remove();
+	});
+
+	it('exposes busy state without disabling available options', () => {
+		const onValueChange = vi.fn();
+		vi.stubGlobal('matchMedia', vi.fn(() => ({
+			matches: false,
+			media: '(prefers-color-scheme: dark)',
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+		})));
+
+		const el = document.createElement('div');
+		document.body.appendChild(el);
+		const root = createRoot(el);
+		act(() => root.render(
+			<Select
+				label="Country"
+				options={[{ value: 'nz', label: 'New Zealand' }, { value: 'au', label: 'Australia' }]}
+				defaultValue="nz"
+				defaultOpen
+				isLoading
+				onValueChange={onValueChange}
+			/>,
+		));
+
+		expect(el.querySelector('.vx-select-trigger')?.getAttribute('aria-busy')).toBe('true');
+		const australia = Array.from(document.querySelectorAll('.vx-select-option'))
+			.find((option) => option.textContent?.includes('Australia')) as HTMLElement;
+
+		act(() => australia.click());
+		expect(onValueChange).toHaveBeenCalledWith('au');
+		root.unmount();
+		el.remove();
+		vi.unstubAllGlobals();
+	});
+});
+
+describe('Field anatomy (web leaf)', () => {
+	it('associates the label, description, status, and shared states with its control', () => {
+		const el = document.createElement('div');
+		document.body.appendChild(el);
+		const root = createRoot(el);
+		act(() => root.render(
+			<FormField
+				label="Email"
+				description="Used for account updates"
+				isRequired
+				isDisabled
+				status={{ type: 'error', message: 'Enter a valid address' }}
+			>
+				<TextInput placeholder="name@example.com" />
+			</FormField>,
+		));
+
+		const input = el.querySelector('.vx-input') as HTMLInputElement;
+		const label = el.querySelector('.vx-field-label') as HTMLLabelElement;
+		const description = el.querySelector('.vx-field-description') as HTMLElement;
+		const status = el.querySelector('.vx-field-status') as HTMLElement;
+		expect(label.htmlFor).toBe(input.id);
+		expect(input.getAttribute('aria-labelledby')).toBe(label.id);
+		expect(input.getAttribute('aria-describedby')?.split(' ')).toEqual([description.id, status.id]);
+		expect(input.disabled).toBe(true);
+		expect(input.getAttribute('aria-required')).toBe('true');
+		expect(input.getAttribute('aria-invalid')).toBe('true');
+		expect(status.getAttribute('role')).toBe('alert');
+		root.unmount();
+		el.remove();
+	});
+
+	it('keeps a composite PIN field labelled once without duplicate control IDs', () => {
+		const el = document.createElement('div');
+		document.body.appendChild(el);
+		const root = createRoot(el);
+		act(() => root.render(
+			<FormField label="Security code">
+				<PinInput length={4} />
+			</FormField>,
+		));
+
+		const group = el.querySelector('.vx-pininput') as HTMLElement;
+		const label = el.querySelector('.vx-field-label') as HTMLLabelElement;
+		const cells = Array.from(el.querySelectorAll('.vx-pininput-cell')) as HTMLInputElement[];
+		expect(group.getAttribute('aria-labelledby')).toBe(label.id);
+		expect(group.id).toBeTruthy();
+		expect(cells.map((cell) => cell.getAttribute('aria-label'))).toEqual([
+			'Security code, digit 1',
+			'Security code, digit 2',
+			'Security code, digit 3',
+			'Security code, digit 4',
+		]);
+
+		expect(cells.every((cell) => !cell.id)).toBe(true);
+		root.unmount();
+		el.remove();
+	});
+});

package/src/SearchInput.web.tsrx

@@ -1,4 +1,4 @@
-import { useState } from 'octane';
+import { useRef, useImperativeHandle, useState } from 'octane';
 import type { SearchInputProps } from './props';
 import { Icon } from './Icon.web.tsrx';
 import { applyWebProps } from './platformProps.web';
@@ -9,35 +9,47 @@ import { normStyle } from './layout-child.web';
  *  own ::-webkit-search-cancel-button is hidden — same pixels as native).
  *  `value`/`onChange` for controlled, `defaultValue` for uncontrolled. */
 export function SearchInput(props: SearchInputProps) @{
+	const hostRef = useRef<any>(null);
 	const [internal, setInternal] = useState(props.defaultValue ?? '');
 	const value = props.value ?? internal;
+	const isBlocked = props.isDisabled || props.isReadOnly;
+	const hasClear = props.hasClear !== false;
 	const setValue = (next: string) => {
+		if (isBlocked) return;
 		if (props.value === undefined) setInternal(next);
 		props.onChange?.(next);
 	};
 
 	const clear = () => {
+		if (isBlocked || !hasClear) return;
 		setValue('');
 		props.onClear?.();
 	};
 
+	useImperativeHandle(props.ref, () => ({ focus: () => hostRef.current.focus(), blur: () => hostRef.current.blur(), native: hostRef.current }), []);
+
 	<div
 		ref={(el: any) => applyWebProps(el, props.web)}
 		id={props.id}
-		className={['vx-search', props.editable === false ? 'vx-search--disabled' : undefined, props.className]}
+		className={['vx-search', props.isDisabled ? 'vx-search--disabled' : undefined, props.isReadOnly ? 'vx-search--readonly' : undefined, props.isLoading ? 'vx-search--loading' : undefined, props.status ? `vx-search--status-${props.status.type}` : undefined, props.size ? `vx-search--size-${props.size}` : undefined, props.className]}
 		style={normStyle(props.style)}
+		aria-busy={props.isLoading || undefined}
 	>
 		{props.icon !== false ? <Icon name={props.icon ?? 'xplat-search'} size={16} className="vx-search-icon" /> : null}
 		<input
 			ref={(el: any) => {
-				if (el) props.bind?.({ focus: () => el.focus(), blur: () => el.blur(), native: el });
+				hostRef.current = el;
 			}}
 			type="search"
 			className="vx-search-field"
 			value={value}
 			placeholder={props.placeholder}
-			aria-label={props.accessibilityLabel ?? props.placeholder}
-			readOnly={props.editable === false}
+			aria-label={props.accessibilityLabel ?? props.label ?? props.placeholder}
+			aria-required={props.isRequired && !props.isOptional || undefined}
+			aria-invalid={props.status?.type === 'error' || undefined}
+			aria-busy={props.isLoading || undefined}
+			disabled={props.isDisabled || undefined}
+			readOnly={props.isReadOnly || undefined}
 			enterKeyHint="search"
 			onInput={(e: any) => setValue(e.target.value)}
 			onKeyDown={(e: any) => {
@@ -46,7 +58,7 @@ export function SearchInput(props: SearchInputProps) @{
 			onFocus={props.onFocus}
 			onBlur={props.onBlur}
 		/>
-		{value !== '' && props.editable !== false ? (
+		{value !== '' && hasClear && !isBlocked ? (
 			<button type="button" className="vx-search-clear" aria-label="Clear search" onClick={clear}>
 				<Icon name="xplat-clear" size={12} />
 			</button>