@octane-xplat/ui 0.9.0 → 0.10.0

package/src/DropdownMenu.tsrx

@@ -1,40 +1,39 @@
 /** @jsxImportSource @nativescript-community/octane */
+import { MenuData } from './MenuParts';
+import { MenuSurface } from './MenuSurface';
 import { useRef, useState } from 'octane';
-import type { DropdownMenuProps, MenuItem } from "./props";
+import type { DropdownMenuProps } from "./props";
 import { cx } from "./cx";
-import { applyEscapeProps } from "./escape-props";
-import { Pressable } from './Pressable.tsrx';
-import { Popover } from './Popover.tsrx';
-import { Icon } from './Icon.tsrx';
+import { Pressable } from './Pressable';
+import { Popover } from './Popover';
+import { useButtonGroup } from './button-group-context';
 
 /** Self-drawn dropdown menu — `trigger` plus an anchored item list via
  *  Popover. The same anchored listbox renders on every target (decision
  *  #48): bounded, unvirtualized items. */
 export function DropdownMenu(props: DropdownMenuProps) @{
 	const anchor = useRef<any>(null);
+	const group = useButtonGroup();
+	const disabled = !!((props.isDisabled ?? props.disabled) || group?.isDisabled);
 	const [internal, setInternal] = useState(props.defaultOpen ?? false);
-	const controlled = props.open !== undefined;
-	const open = controlled ? props.open : internal;
+	const controlled = props.isOpen !== undefined || props.open !== undefined;
+	const open = props.isOpen ?? props.open ?? internal;
 
 	const setOpen = (next: boolean) => {
-		if (props.disabled && next) return;
+		if (disabled && next) return;
 		if (!controlled) setInternal(next);
 		props.onOpenChange?.(next);
 	};
 
-	const select = (item: MenuItem) => {
-		if (item.disabled) return;
-		setOpen(false);
-		item.onSelect?.();
-	};
-
 	<>
 		<Pressable
-			bind={(v: any) => { anchor.current = v; }}
+			ref={(v: any) => { anchor.current = v; }}
 			id={props.id}
-			className={cx('vx-menu-trigger', props.className)}
+			className={cx('vx-menu-trigger', props.triggerClassName, group && `vx-button--group-${group.position}`, group?.size && `vx-button--size-${group.size}`, props.className)}
 			style={props.style}
-			disabled={props.disabled}
+			disabled={disabled}
+			accessibilityLabel={props.accessibilityLabel}
+			web={{ 'aria-haspopup': 'menu', 'aria-expanded': open }}
 			onPress={() => setOpen(!open)}
 		>
 			{props.trigger}
@@ -43,21 +42,13 @@ export function DropdownMenu(props: DropdownMenuProps) @{
 			anchor={anchor}
 			open={open}
 			placement={props.placement ?? 'bottom'}
+			alignment={props.alignment}
 			onDismiss={() => setOpen(false)}
-			className="vx-menu"
+			className={cx('vx-menu', props.menuClassName)}
 		>
-			<flexboxlayout className="vx-menu-list">
-				{props.items.map((item: MenuItem) => (
-					<flexboxlayout
-						key={item.key}
-						className={cx('vx-menu-item', item.disabled && 'vx-menu-item--disabled')}
-						onTap={item.disabled ? undefined : () => select(item)}
-					>
-						{item.icon ? <Icon name={item.icon} /> : null}
-						{item.label != null ? <label className="vx-menu-item-label" text={item.label} /> : null}
-					</flexboxlayout>
-				))}
-			</flexboxlayout>
+			<MenuSurface closeMenu={() => setOpen(false)} label={props.accessibilityLabel}>
+				<MenuData items={props.items} />{props.children}
+			</MenuSurface>
 		</Popover>
 	</>
 }

package/src/DropdownMenu.web.tsrx

@@ -1,47 +1,41 @@
-import { useEffect, useRef, useState } from 'octane';
-import type { DropdownMenuProps, MenuItem } from "./props";
-import { applyEscapeProps } from "./escape-props";
+import { MenuData } from './MenuParts.web.tsrx';
+import { MenuSurface } from './MenuSurface.web.tsrx';
+import { useRef, useState } from 'octane';
+import type { DropdownMenuProps } from "./props";
 import { Pressable } from './Pressable.web.tsrx';
 import { Popover } from './Popover.web.tsrx';
-import { Icon } from './Icon.web.tsrx';
+import { useButtonGroup } from './button-group-context';
 
 /** Self-drawn dropdown menu — `trigger` plus an anchored item list via
  *  Popover. The same anchored listbox renders on every target (decision
  *  #48): bounded, unvirtualized items. */
 export function DropdownMenu(props: DropdownMenuProps) @{
 	const anchor = useRef<any>(null);
+	const initialFocus = useRef<'first' | 'last' | 'container'>('container');
+	const group = useButtonGroup();
+	const disabled = !!((props.isDisabled ?? props.disabled) || group?.isDisabled);
 	const [internal, setInternal] = useState(props.defaultOpen ?? false);
-	const controlled = props.open !== undefined;
-	const open = controlled ? props.open : internal;
+	const controlled = props.isOpen !== undefined || props.open !== undefined;
+	const open = props.isOpen ?? props.open ?? internal;
 
 	const setOpen = (next: boolean) => {
-		if (props.disabled && next) return;
+		if (disabled && next) return;
 		if (!controlled) setInternal(next);
 		props.onOpenChange?.(next);
 	};
 
-	useEffect(() => {
-		if (!open) return;
-		const onKey = (e: any) => { if (e.key === 'Escape') setOpen(false); };
-		window.addEventListener('keydown', onKey);
-		return () => window.removeEventListener('keydown', onKey);
-	}, [open]);
-
-	const select = (item: MenuItem) => {
-		if (item.disabled) return;
-		setOpen(false);
-		item.onSelect?.();
-	};
 
 	<>
 		<Pressable
-			bind={(e: any) => { anchor.current = e; }}
+			ref={(e: any) => { anchor.current = e; }}
 			id={props.id}
-			className={['vx-menu-trigger', props.className]}
+			className={['vx-menu-trigger', props.triggerClassName, group && `vx-button--group-${group.position}`, group?.size && `vx-button--size-${group.size}`, props.className]}
 			style={props.style}
-			disabled={props.disabled}
+			disabled={disabled}
+			accessibilityLabel={props.accessibilityLabel}
 			onPress={() => setOpen(!open)}
-			accessibilityState={{ disabled: props.disabled }}
+			accessibilityState={{ disabled }}
+			web={{ onpointerdown: () => { initialFocus.current = 'container' }, 'aria-haspopup': 'menu', 'aria-expanded': String(open), onkeydown: (event: any) => { if (event.isComposing || event.keyCode === 229 || event.defaultPrevented) return; if (event.key === 'Enter' || event.key === ' ') initialFocus.current = 'first'; if (event.key === 'ArrowDown' || event.key === 'ArrowUp') { event.preventDefault(); initialFocus.current = event.key === 'ArrowUp' ? 'last' : 'first'; setOpen(true); } } }}
 		>
 			{props.trigger}
 		</Pressable>
@@ -49,30 +43,13 @@ export function DropdownMenu(props: DropdownMenuProps) @{
 			anchor={anchor}
 			open={open}
 			placement={props.placement ?? 'bottom'}
+			alignment={props.alignment}
 			onDismiss={() => setOpen(false)}
-			className="vx-menu"
+			className={['vx-menu', props.menuClassName]}
 		>
-			<div role="menu" className="vx-menu-list">
-				{props.items.map((item: MenuItem) => (
-					<div
-						key={item.key}
-						role="menuitem"
-						aria-disabled={item.disabled || undefined}
-						tabIndex={item.disabled ? undefined : 0}
-						className={['vx-menu-item', item.disabled ? 'vx-menu-item--disabled' : undefined]}
-						onClick={item.disabled ? undefined : () => select(item)}
-						onKeyDown={(e: any) => {
-							if (!item.disabled && (e.key === ' ' || e.key === 'Enter')) {
-								e.preventDefault();
-								select(item);
-							}
-						}}
-					>
-						{item.icon ? <Icon name={item.icon} /> : null}
-						{item.label != null ? <span className="vx-menu-item-label">{item.label}</span> : null}
-					</div>
-				))}
-			</div>
+			<MenuSurface initialFocus={initialFocus.current} closeMenu={() => setOpen(false)} label={props.accessibilityLabel}>
+				<MenuData items={props.items} />{props.children}
+			</MenuSurface>
 		</Popover>
 	</>
 }

package/src/Empty.macos.tsrx

@@ -1,4 +1,4 @@
-/** @jsxImportSource @xplat/macos/renderer */
+/** @jsxImportSource @octane-xplat/macos-renderer */
 import type { EmptyProps } from "./props";
 import { cx } from "./cx";
 import { applyEscapeProps } from "./escape-props";

package/src/Empty.tsrx

@@ -2,7 +2,7 @@
 import type { EmptyProps } from "./props";
 import { cx } from "./cx";
 import { applyEscapeProps } from "./escape-props";
-import { Icon } from './Icon.tsrx';
+import { Icon } from './Icon';
 
 /** Empty — empty-state block: icon + title + description + actions. */
 export function Empty(props: EmptyProps) @{

package/src/FieldGroup.macos.tsrx

@@ -1,4 +1,4 @@
-/** @jsxImportSource @xplat/macos/renderer */
+/** @jsxImportSource @octane-xplat/macos-renderer */
 import type { FieldGroupProps } from "./props";
 import { cx } from "./cx";
 import { applyEscapeProps } from "./escape-props";

package/src/FormField.macos.tsrx

@@ -1,25 +1,71 @@
-/** @jsxImportSource @xplat/macos/renderer */
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { useContext, useId } from 'octane'
 import type { FormFieldProps } from "./props";
 import { cx } from "./cx";
 import { applyEscapeProps } from "./escape-props";
+import { FieldProvider } from './field-context'
+import { FormLayoutContext } from './form-layout-context'
+import { Tooltip } from './Tooltip.tsrx'
+import { Pressable } from './Pressable.macos.tsrx'
 
-/** FormField — label + control + hint/error stack. The error replaces the
- *  hint when present; `required` appends a marker to the label. */
+/** Shared field wrapper for labels, descriptions, and validation status.
+ *  Mirrors the other platform leaves' FormLayout integration. */
 export function FormField(props: FormFieldProps) @{
-	const message = props.error ?? props.hint;
+	const generatedControlId = useId()
+	const form = useContext(FormLayoutContext)
+	const isHorizontalLabels = form.direction === 'horizontal-labels'
+	const controlId = props.inputID ?? generatedControlId
+	const labelId = props.label == null ? undefined : (props.labelID ?? `${generatedControlId}-label`)
+	const descriptionId = props.description == null ? undefined : (props.descriptionID ?? `${generatedControlId}-description`)
+	const status = props.status
+	const statusVariant = props.statusVariant ?? 'attached'
+	const statusId = status?.message == null ? undefined : (props.statusID ?? `${generatedControlId}-status`)
+	const isRequired = props.isRequired && !props.isOptional
+	const showRequired = isRequired && form.defaultOptionality !== 'required'
+	const showOptional = Boolean(props.isOptional) && form.defaultOptionality !== 'optional'
+	const labelText = showRequired ? props.label + ' *' : showOptional ? props.label + ' (Optional)' : props.label
+	const fieldContext = {
+		...props,
+		controlId,
+		labelId,
+		descriptionId,
+		statusId,
+	}
 
-	<flexboxlayout
-		ref={(v: any) => applyEscapeProps(v, props)}
-		id={props.id}
-		className={cx('vx-field', props.error && 'vx-field--error', props.className)}
-		style={props.style}
-	>
-		{props.label != null
-			? <label className="vx-field-label" text={props.required ? props.label + ' *' : props.label} />
-			: null}
-		{props.children}
-		{message != null
-			? <label className={cx('vx-field-msg', props.error && 'vx-field-msg--error')} text={message} />
-			: null}
-	</flexboxlayout>
+	const labelNode = props.label == null || props.isLabelHidden ? null
+		: <flexboxlayout className="vx-field-label-row" flexDirection="row" alignItems="center">
+			<label id={labelId} className="vx-field-label" text={labelText} />
+			{props.labelTooltip != null
+				? <Tooltip trigger={<Pressable className="vx-field-info" accessibilityLabel={'More about ' + props.label} accessibilityHint={props.labelTooltip}><label text="i" /></Pressable>} content={props.labelTooltip} placement="top" />
+				: null}
+		</flexboxlayout>
+
+	const descriptionNode = props.description != null && !props.isLabelHidden
+		? <label id={descriptionId} className="vx-field-description" text={props.description} />
+		: null
+
+	const statusNode = status?.message != null
+		? <label id={statusId} className={cx('vx-field-status', `vx-field-status--${status.type}`, `vx-field-status--${statusVariant}`)} text={status.message} />
+		: null
+
+	const rootClass = cx('vx-field', status && `vx-field--${status.type}`, `vx-field--status-${statusVariant}`, props.isDisabled && 'vx-field--disabled', props.isReadOnly && 'vx-field--readonly', props.isLoading && 'vx-field--loading', props.size && `vx-field--size-${props.size}`, props.className)
+	const fieldStyle = { ...(props.width != null ? { width: props.width } : {}), ...props.style }
+
+	@if (isHorizontalLabels) {
+		<flexboxlayout ref={(v: any) => applyEscapeProps(v, props)} id={props.id} flexDirection="row" className={cx(rootClass, 'vx-field--hl')} style={fieldStyle}>
+			<flexboxlayout className="vx-field-hl-label" flexDirection="column">{labelNode}</flexboxlayout>
+			<flexboxlayout className="vx-field-hl-body" flexDirection="column" flexGrow={1}>
+				{descriptionNode}
+				<FieldProvider value={fieldContext}>{props.children}</FieldProvider>
+				{statusNode}
+			</flexboxlayout>
+		</flexboxlayout>
+	} @else {
+		<flexboxlayout ref={(v: any) => applyEscapeProps(v, props)} id={props.id} className={rootClass} style={fieldStyle}>
+			{labelNode}
+			{descriptionNode}
+			<FieldProvider value={fieldContext}>{props.children}</FieldProvider>
+			{statusNode}
+		</flexboxlayout>
+	}
 }

package/src/FormField.tsrx

@@ -1,25 +1,73 @@
 /** @jsxImportSource @nativescript-community/octane */
+import { useContext, useId } from 'octane'
 import type { FormFieldProps } from "./props";
 import { cx } from "./cx";
 import { applyEscapeProps } from "./escape-props";
+import { FieldProvider } from './field-context'
+import { FormLayoutContext } from './form-layout-context'
+import { Tooltip } from './Tooltip.tsrx'
+import { Pressable } from './Pressable'
 
-/** FormField — label + control + hint/error stack. The error replaces the
- *  hint when present; `required` appends a marker to the label. */
+/** Shared field wrapper for labels, descriptions, and validation status.
+ *  Under `FormLayout direction="horizontal-labels"` it renders a row; the
+ *  native label width is per field because the web grid's shared auto column
+ *  has no native analog. Form-wide optionality suppresses redundant markers. */
 export function FormField(props: FormFieldProps) @{
-	const message = props.error ?? props.hint;
+	const generatedControlId = useId()
+	const form = useContext(FormLayoutContext)
+	const isHorizontalLabels = form.direction === 'horizontal-labels'
+	const controlId = props.inputID ?? generatedControlId
+	const labelId = props.label == null ? undefined : (props.labelID ?? `${generatedControlId}-label`)
+	const descriptionId = props.description == null ? undefined : (props.descriptionID ?? `${generatedControlId}-description`)
+	const status = props.status
+	const statusVariant = props.statusVariant === 'tooltip' ? 'detached' : (props.statusVariant ?? 'attached')
+	const statusId = status?.message == null ? undefined : (props.statusID ?? `${generatedControlId}-status`)
+	const isRequired = props.isRequired && !props.isOptional
+	const showRequired = isRequired && form.defaultOptionality !== 'required'
+	const showOptional = Boolean(props.isOptional) && form.defaultOptionality !== 'optional'
+	const labelText = showRequired ? props.label + ' *' : showOptional ? props.label + ' (Optional)' : props.label
+	const fieldContext = {
+		...props,
+		controlId,
+		labelId,
+		descriptionId,
+		statusId,
+	}
 
-	<flexboxlayout
-		ref={(v: any) => applyEscapeProps(v, props)}
-		id={props.id}
-		className={cx('vx-field', props.error && 'vx-field--error', props.className)}
-		style={props.style}
-	>
-		{props.label != null
-			? <label className="vx-field-label" text={props.required ? props.label + ' *' : props.label} />
-			: null}
-		{props.children}
-		{message != null
-			? <label className={cx('vx-field-msg', props.error && 'vx-field-msg--error')} text={message} />
-			: null}
-	</flexboxlayout>
+	const labelNode = props.label == null || props.isLabelHidden ? null
+		: <flexboxlayout className="vx-field-label-row" flexDirection="row" alignItems="center">
+			<label id={labelId} className="vx-field-label" text={labelText} />
+			{props.labelTooltip != null
+				? <Tooltip trigger={<Pressable className="vx-field-info" accessibilityLabel={'More about ' + props.label} accessibilityHint={props.labelTooltip}><label text="i" /></Pressable>} content={props.labelTooltip} placement="top" />
+				: null}
+		</flexboxlayout>
+
+	const descriptionNode = props.description != null && !props.isLabelHidden
+		? <label id={descriptionId} className="vx-field-description" text={props.description} />
+		: null
+
+	const statusNode = status?.message != null
+		? <label id={statusId} className={cx('vx-field-status', `vx-field-status--${status.type}`, `vx-field-status--${statusVariant}`)} text={status.message} />
+		: null
+
+	const rootClass = cx('vx-field', status && `vx-field--${status.type}`, `vx-field--status-${statusVariant}`, props.isDisabled && 'vx-field--disabled', props.isReadOnly && 'vx-field--readonly', props.isLoading && 'vx-field--loading', props.size && `vx-field--size-${props.size}`, props.className)
+	const fieldStyle = { ...(props.width != null ? { width: props.width } : {}), ...props.style }
+
+	@if (isHorizontalLabels) {
+		<flexboxlayout ref={(v: any) => applyEscapeProps(v, props)} id={props.id} flexDirection="row" className={cx(rootClass, 'vx-field--hl')} style={fieldStyle}>
+			<flexboxlayout className="vx-field-hl-label" flexDirection="column">{labelNode}</flexboxlayout>
+			<flexboxlayout className="vx-field-hl-body" flexDirection="column" flexGrow={1}>
+				{descriptionNode}
+				<FieldProvider value={fieldContext}>{props.children}</FieldProvider>
+				{statusNode}
+			</flexboxlayout>
+		</flexboxlayout>
+	} @else {
+		<flexboxlayout ref={(v: any) => applyEscapeProps(v, props)} id={props.id} className={rootClass} style={fieldStyle}>
+			{labelNode}
+			{descriptionNode}
+			<FieldProvider value={fieldContext}>{props.children}</FieldProvider>
+			{statusNode}
+		</flexboxlayout>
+	}
 }

package/src/FormField.web.tsrx

@@ -1,24 +1,75 @@
+import { useContext, useId } from 'octane'
 import type { FormFieldProps } from "./props";
 import { applyEscapeProps } from "./escape-props";
+import { FieldProvider } from './field-context'
+import { FormLayoutContext } from './form-layout-context'
+import { Tooltip } from './Tooltip.web.tsrx'
 
-/** FormField — label + control + hint/error stack. The error replaces the
- *  hint when present; `required` appends a marker to the label. */
+/** Shared field wrapper for labels, descriptions, and validation status.
+ *  Under a `FormLayout`, horizontal labels flatten the root so the grid can
+ *  place labels and controls in shared columns. Form-wide optionality hides
+ *  redundant markers while controls retain their required accessibility state. */
 export function FormField(props: FormFieldProps) @{
-	const message = props.error ?? props.hint;
-
-	<div
-		ref={(e: any) => applyEscapeProps(e, props)}
-		id={props.id}
-		className={['vx-field', props.error ? 'vx-field--error' : undefined, props.className]}
-		style={props.style}
-		role="group"
-	>
-		{props.label != null
-			? <span className="vx-field-label">{props.label}{props.required ? <span className="vx-field-required" aria-hidden="true"> *</span> : null}</span>
-			: null}
-		{props.children}
-		{message != null
-			? <span className={['vx-field-msg', props.error ? 'vx-field-msg--error' : undefined]} role={props.error ? 'alert' : undefined}>{message}</span>
-			: null}
-	</div>
+	const generatedControlId = useId()
+	const form = useContext(FormLayoutContext)
+	const isHorizontalLabels = form.direction === 'horizontal-labels'
+	const controlId = props.inputID ?? generatedControlId
+	const labelId = props.label == null ? undefined : (props.labelID ?? `${generatedControlId}-label`)
+	const descriptionId = props.description == null ? undefined : (props.descriptionID ?? `${generatedControlId}-description`)
+	const isRequired = props.isRequired && !props.isOptional
+	const status = props.status
+	const statusVariant = props.statusVariant ?? 'attached'
+	const statusId = status?.message == null ? undefined : (props.statusID ?? `${generatedControlId}-status`)
+	const fieldContext = {
+		...props,
+		controlId,
+		labelId,
+		descriptionId,
+		statusId,
+	}
+
+	const showRequired = isRequired && form.defaultOptionality !== 'required'
+	const showOptional = Boolean(props.isOptional) && form.defaultOptionality !== 'optional'
+	const labelAffordance = props.labelTooltip != null
+		? <Tooltip trigger={<span className="vx-field-label-tip" aria-hidden="true">{'?'}</span>} content={props.labelTooltip} placement="top" />
+		: null
+
+	const labelText = props.label != null
+		? <span className="vx-field-label-text">{props.label}{showRequired ? <span className="vx-field-required" aria-hidden="true"> *</span> : null}{showOptional ? <span className="vx-field-optional"> (Optional)</span> : null}{labelAffordance}</span>
+		: null
+
+	const labelNode = props.label != null
+		? (props.isGroupLabel
+			? <span id={labelId} className={['vx-field-label', props.isLabelHidden ? 'vx-field-label--hidden' : undefined]}>{labelText}</span>
+			: <label id={labelId} htmlFor={controlId} className={['vx-field-label', props.isLabelHidden ? 'vx-field-label--hidden' : undefined]}>{labelText}</label>)
+		: null
+
+	const descriptionNode = props.description != null
+		? <span id={descriptionId} className={['vx-field-description', props.isLabelHidden ? 'vx-field-description--hidden' : undefined]}>{props.description}</span>
+		: null
+
+	const statusNode = status?.message != null
+		? <span id={statusId} className={['vx-field-status', `vx-field-status--${status.type}`, `vx-field-status--${statusVariant}`]} role={status.type === 'error' ? 'alert' : 'status'}>{status.message}</span>
+		: null
+
+	const rootClass = ['vx-field', status ? `vx-field--${status.type}` : undefined, `vx-field--status-${statusVariant}`, props.isDisabled ? 'vx-field--disabled' : undefined, props.isReadOnly ? 'vx-field--readonly' : undefined, props.isLoading ? 'vx-field--loading' : undefined, props.size ? `vx-field--size-${props.size}` : undefined, props.className]
+	const fieldStyle = { ...(props.width != null ? { width: props.width } : {}), ...props.style }
+
+	@if (isHorizontalLabels) {
+		<div ref={(e: any) => applyEscapeProps(e, props)} id={props.id} className={[...rootClass, 'vx-field--hl']} style={fieldStyle}>
+			<div className="vx-field-hl-label">{labelNode}</div>
+			<div className="vx-field-hl-body">
+				{descriptionNode}
+				<FieldProvider value={fieldContext}>{props.children}</FieldProvider>
+				{statusNode}
+			</div>
+		</div>
+	} @else {
+		<div ref={(e: any) => applyEscapeProps(e, props)} id={props.id} className={rootClass} style={fieldStyle} role="group">
+			{labelNode}
+			{descriptionNode}
+			<FieldProvider value={fieldContext}>{props.children}</FieldProvider>
+			{statusNode}
+		</div>
+	}
 }

package/src/FormLayout.macos.tsrx

@@ -0,0 +1,35 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { useMemo } from 'octane'
+import { refList } from './ref-list'
+import type { FormLayoutProps } from './props'
+import { cx } from './cx'
+import { applyEscapeProps } from './escape-props'
+import { FormLayoutProvider } from './form-layout-context'
+
+/** FormLayout — vertical column / horizontal row / horizontal-labels
+ *  column (each Field renders its own label row). The AppKit grid doesn't
+ *  auto-assign columns, so 'horizontal' uses a wrapped row flow rather
+ *  than equal-width columns. */
+export function FormLayout(props: FormLayoutProps) @{
+	const direction = props.direction ?? 'vertical'
+	const value = { direction, defaultOptionality: props.defaultOptionality }
+
+	const forwardedRef = useMemo(() => refList((v: any) => { if (v) { applyEscapeProps(v, props); } }, props.ref), [props.ref, props.ios, props.android, props.web]);
+
+	<FormLayoutProvider value={value}>
+		<flexboxlayout
+			id={props.id}
+			ref={forwardedRef}
+			flexDirection={direction === 'horizontal' ? 'row' : 'column'}
+			flexWrap={(direction === 'horizontal' ? 'wrap' : undefined) as any}
+			gap={16}
+			className={cx('vx-formlayout', `vx-formlayout--${direction}`, props.className)}
+			style={props.style}
+			accessibilityLabel={props.accessibilityLabel}
+			accessibilityRole={props.accessibilityRole}
+			accessibilityHint={props.accessibilityHint}
+		>
+			{props.children}
+		</flexboxlayout>
+	</FormLayoutProvider>
+}

package/src/FormLayout.tsrx

@@ -0,0 +1,70 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useMemo, useEffect, useRef } from 'octane';
+import { refList } from './ref-list'
+import type { FormLayoutProps } from './props';
+import { cx } from './cx';
+import { applyEscapeProps, nativeAccessibilityRole, nativeAccessibilityState } from './escape-props';
+import { FormLayoutProvider } from './form-layout-context';
+
+/** FormLayout — 'vertical' is a column with 16dip gaps. 'horizontal' is a
+ *  single `*`-column-per-child grid row (NativeScript's grid has no
+ *  auto-flow; the effect assigns each child its column once laid out).
+ *  'horizontal-labels' keeps the column host — each `Field` reads the
+ *  context and renders its own label-beside-control row (per-field label
+ *  width; the web grid's shared label column has no native analog). */
+export function FormLayout(props: FormLayoutProps) @{
+	const direction = props.direction ?? 'vertical';
+	const value = { direction, defaultOptionality: props.defaultOptionality };
+	const host = useRef<any>(null);
+
+	useEffect(() => {
+		if (direction !== 'horizontal' || !host.current) { return; }
+		const views: any[] = [];
+		host.current.eachChildView((child: any) => { views.push(child); return true; });
+		host.current.columns = Array.from({ length: Math.max(1, views.length) }, () => '*').join(',');
+		for (let index = 0; index < views.length; index++) {
+			views[index].col = index;
+		}
+	}, [props.children, direction]);
+
+	const forwardedRef = useMemo(() => refList((v: any) => { host.current = v; if (v) { applyEscapeProps(v, props);  } }, props.ref), [props.ref, props.ios, props.android, props.web]);
+	const forwardedRef2 = useMemo(() => refList((v: any) => { if (v) { applyEscapeProps(v, props); } }, props.ref), [props.ref, props.ios, props.android, props.web]);
+
+	<FormLayoutProvider value={value}>
+		{direction === 'horizontal' ? (
+			<gridlayout
+				id={props.id}
+				ref={forwardedRef}
+				className={cx('vx-formlayout', 'vx-formlayout--horizontal', props.className)}
+				style={props.style}
+				accessible={props.accessible}
+				accessibilityLabel={props.accessibilityLabel}
+				accessibilityRole={nativeAccessibilityRole(props.accessibilityRole) as any}
+				accessibilityHint={props.accessibilityHint}
+				accessibilityValue={props.accessibilityValue}
+				accessibilityState={nativeAccessibilityState(props.accessibilityState) as any}
+				accessibilityLiveRegion={props.accessibilityLiveRegion as any}
+			>
+				{props.children}
+			</gridlayout>
+		) : (
+			<flexboxlayout
+				id={props.id}
+				ref={forwardedRef2}
+				flexDirection="column"
+				gap={16}
+				className={cx('vx-formlayout', `vx-formlayout--${direction}`, props.className)}
+				style={props.style}
+				accessible={props.accessible}
+				accessibilityLabel={props.accessibilityLabel}
+				accessibilityRole={nativeAccessibilityRole(props.accessibilityRole) as any}
+				accessibilityHint={props.accessibilityHint}
+				accessibilityValue={props.accessibilityValue}
+				accessibilityState={nativeAccessibilityState(props.accessibilityState) as any}
+				accessibilityLiveRegion={props.accessibilityLiveRegion as any}
+			>
+				{props.children}
+			</flexboxlayout>
+		)}
+	</FormLayoutProvider>
+}

package/src/FormLayout.web.tsrx

@@ -0,0 +1,38 @@
+import { useMemo } from 'octane'
+import { refList } from './ref-list'
+import type { FormLayoutProps } from './props';
+import { applyEscapeProps } from './escape-props';
+import { applyWebProps } from './platformProps.web';
+import { FormLayoutProvider } from './form-layout-context';
+
+/** FormLayout — arranges fields: 'vertical' column (16px gaps),
+ *  'horizontal' equal-width row, 'horizontal-labels' a two-column grid
+ *  (`auto 1fr`) where each field's label sits beside its control —
+ *  `Field` renders `display:contents` under this mode so its label/body
+ *  become grid items; collapses to a column under 480px (CSS). */
+export function FormLayout(props: FormLayoutProps) @{
+	const direction = props.direction ?? 'vertical';
+	const value = { direction, defaultOptionality: props.defaultOptionality };
+
+	const forwardedRef = useMemo(() => refList((e: any) => { if (e) { applyEscapeProps(e, props); applyWebProps(e, props.web); } }, props.ref), [props.ref, props.ios, props.android, props.web]);
+
+	<FormLayoutProvider value={value}>
+		<div
+			id={props.id}
+			ref={forwardedRef}
+			className={['vx-formlayout', `vx-formlayout--${direction}`, props.className]}
+			style={props.style}
+			role={props.accessibilityRole}
+			aria-label={props.accessibilityLabel}
+			aria-hidden={props.accessible === false ? true : undefined}
+			aria-description={props.accessibilityHint}
+			aria-valuetext={props.accessibilityValue}
+			aria-disabled={props.accessibilityState?.disabled}
+			aria-selected={props.accessibilityState?.selected}
+			aria-checked={props.accessibilityState?.checked}
+			aria-live={props.accessibilityLiveRegion === 'none' ? 'off' : props.accessibilityLiveRegion}
+		>
+			{props.children}
+		</div>
+	</FormLayoutProvider>
+}

package/src/HStack.macos.tsrx

@@ -0,0 +1,13 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import type { HStackProps } from './props'
+import { Stack } from './layout.macos.tsrx'
+
+/** Horizontal flow stack — `Stack` with `direction="horizontal"`. */
+export function HStack(props: HStackProps) @{
+	return <Stack
+		{...props}
+		direction="horizontal"
+		hAlign={props.hAlign ?? props.justify}
+		vAlign={props.vAlign ?? props.align}
+	/>
+}