ajo-ui 0.1.0

package/src/toggle-group.tsx

@@ -0,0 +1,249 @@
+import type { IntrinsicElements, Stateful, Stateless, WithChildren } from 'ajo'
+import { listen, roving, selection, statefulRootAttrs as rootAttrs } from 'ajo-cloves'
+import { context } from 'ajo/context'
+import type { FixedArgs, OmitArg } from './utils'
+import { flag, strings } from './utils'
+import { Toggle, type ToggleArgs } from './toggle'
+
+/** Selection cardinality of a toggle group. */
+export type ToggleGroupType = 'multiple' | 'single'
+/** Layout and keyboard-navigation axis of a toggle group. */
+export type ToggleGroupOrientation = 'horizontal' | 'vertical'
+
+type ToggleGroupSharedArgs = WithChildren<OmitArg<IntrinsicElements['div'], 'defaultValue' | 'type' | 'value'> & {
+	/** Disable every item in the group. */
+	disabled?: boolean
+	/** Allow arrow-key focus to wrap at the ends. */
+	loop?: boolean
+	/** Layout orientation. */
+	orientation?: ToggleGroupOrientation
+	/** Shared item size marker. */
+	size?: string
+	/** Spacing marker shared with items. */
+	spacing?: number
+	/** Shared item variant marker. */
+	variant?: string
+}>
+
+/** Props for a toggle group that selects at most one value. */
+export type ToggleGroupSingleArgs = ToggleGroupSharedArgs & {
+	type?: 'single'
+	/** Controlled selected value. */
+	value?: string
+	/** Initial selected value for uncontrolled usage. */
+	defaultValue?: string
+	/** Called whenever the selected value changes. */
+	onValueChange?: (value: string, event: Event) => void
+}
+
+/** Props for a toggle group that selects multiple values. */
+export type ToggleGroupMultipleArgs = ToggleGroupSharedArgs & {
+	type: 'multiple'
+	/** Controlled selected values. */
+	value?: string[]
+	/** Initial selected values for uncontrolled usage. */
+	defaultValue?: string[]
+	/** Called whenever the selected values change. */
+	onValueChange?: (value: string[], event: Event) => void
+}
+
+/** Props accepted by either single- or multiple-selection toggle groups. */
+export type ToggleGroupArgs = ToggleGroupSingleArgs | ToggleGroupMultipleArgs
+
+/** Props for a toggle button whose pressed state belongs to its group. */
+export type ToggleGroupItemArgs = OmitArg<ToggleArgs, 'defaultPressed' | 'onPressedChange' | 'pressed'> & {
+	/** Item value used by the parent toggle group. */
+	value: string
+	/** Item size marker. */
+	size?: string
+	/** Item variant marker. */
+	variant?: string
+} & FixedArgs<'defaultPressed' | 'onPressedChange' | 'pressed'>
+
+/** State and styling markers exposed to descendant toggle-group items. */
+export type ToggleGroupContextValue = {
+	disabled?: boolean
+	orientation: ToggleGroupOrientation
+	pressed: (value: string) => boolean
+	size?: string
+	spacing: number
+	toggle: (value: string, pressed: boolean, event: Event) => void
+	type: ToggleGroupType
+	variant?: string
+}
+
+type ToggleGroupRootArgs = WithChildren<{
+	defaultValue?: string | string[]
+	disabled?: boolean
+	loop?: boolean
+	onValueChange?: ((value: string, event: Event) => void) | ((value: string[], event: Event) => void)
+	orientation: ToggleGroupOrientation
+	size?: string
+	spacing: number
+	type: ToggleGroupType
+	value?: string | string[]
+	variant?: string
+}>
+
+/** Composition context exposing ToggleGroup state and styling markers to descendant items. */
+export const ToggleGroupContext = context<ToggleGroupContextValue | null>(null)
+
+const selected = (type: ToggleGroupType, value: unknown) =>
+	type === 'multiple'
+		? strings(value)
+		: value == null || value === '' ? [] : [String(value)]
+
+const isButton = (value: EventTarget | null): value is HTMLButtonElement =>
+	value instanceof HTMLButtonElement && value.dataset.slot === 'toggle-group-item'
+
+const focusableItems = (root: HTMLElement) =>
+	Array.from(root.querySelectorAll<HTMLButtonElement>('button[data-slot="toggle-group-item"]'))
+		.filter(button => !button.disabled)
+
+const ToggleGroupRoot: Stateful<ToggleGroupRootArgs> = function* ({ defaultValue, type: initialType }) {
+	let disabled = false
+	let loop = true
+	let onValueChange: ToggleGroupRootArgs['onValueChange']
+	let orientation: ToggleGroupOrientation = 'horizontal'
+	let type: ToggleGroupType = initialType
+	const sel = selection(this, {
+		multiple: () => type === 'multiple',
+		fallback: selected(initialType, defaultValue),
+		onChange: (next, event) => {
+			if (type === 'multiple') {
+				(onValueChange as ((value: string[], event: Event) => void) | undefined)?.(next, event as Event)
+			} else {
+				(onValueChange as ((value: string, event: Event) => void) | undefined)?.(next[0] ?? '', event as Event)
+			}
+		},
+	})
+
+	const pressed = (value: string) =>
+		sel.has(value)
+
+	const change = (value: string, _nextPressed: boolean, event: Event) => {
+		if (disabled) return
+		sel.toggle(value, event)
+	}
+
+	const nav = roving(this, {
+		items: () => focusableItems(this),
+		orientation: () => orientation,
+		loop: () => loop,
+		onMove: target => target.focus(),
+	})
+
+	listen(this, 'keydown', (event: KeyboardEvent) => {
+		if (!isButton(event.target)) return
+		// Inside a Toolbar the group's items join the toolbar's roving instead
+		// (Base UI model): one tab stop, arrows traverse into and out of the
+		// group without double-roving. The toolbar must be within the group's
+		// own layer: a group inside popover/dialog content that is a DOM
+		// descendant of a toolbar keeps its own roving (the toolbar's control
+		// row excludes it).
+		if (this.closest('[role="toolbar"], [popover], dialog')?.matches('[role="toolbar"]')) return
+		nav.handle(event)
+	})
+
+	for (const args of this) {
+		type = args.type
+		orientation = args.orientation
+		disabled = Boolean(args.disabled)
+		loop = args.loop !== false
+		onValueChange = args.onValueChange
+		sel.sync(args.value != null ? selected(type, args.value) : undefined)
+
+		ToggleGroupContext({
+			disabled,
+			orientation,
+			pressed,
+			size: args.size,
+			spacing: args.spacing,
+			toggle: change,
+			type,
+			variant: args.variant,
+		})
+
+		yield <>{args.children}</>
+	}
+}
+
+
+/** Unstyled toggle group with selection state and roving keyboard focus. */
+const ToggleGroup: Stateless<ToggleGroupArgs> = ({
+	children,
+	defaultValue,
+	disabled,
+	loop = true,
+	onValueChange,
+	orientation = 'horizontal',
+	role = 'group',
+	size,
+	spacing = 2,
+	type = 'single',
+	value,
+	variant,
+	...attrs
+}) => {
+	const disabledFlag = Boolean(disabled)
+
+	return (
+		<ToggleGroupRoot
+			{...rootAttrs(attrs)}
+			defaultValue={defaultValue}
+			disabled={disabledFlag}
+			loop={loop}
+			onValueChange={onValueChange}
+			orientation={orientation}
+			size={size}
+			spacing={spacing}
+			type={type}
+			value={value}
+			variant={variant}
+			attr:aria-disabled={flag(disabledFlag)}
+			attr:aria-orientation={orientation}
+			attr:data-disabled={flag(disabledFlag)}
+			attr:data-orientation={orientation}
+			attr:data-size={size}
+			attr:data-slot="toggle-group"
+			attr:data-spacing={spacing}
+			attr:data-variant={variant}
+			attr:role={role}
+		>
+			{children}
+		</ToggleGroupRoot>
+	)
+}
+
+/** Unstyled toggle group item wired to the nearest group. */
+const ToggleGroupItem: Stateless<ToggleGroupItemArgs> = ({
+	disabled,
+	size,
+	value,
+	variant,
+	...attrs
+}) => {
+	const group = ToggleGroupContext()
+	const itemValue = String(value)
+	const itemSize = size ?? group?.size
+	const itemVariant = variant ?? group?.variant
+	const disabledFlag = Boolean(disabled ?? group?.disabled)
+	const pressed = group?.pressed(itemValue) ?? false
+
+	return (
+		<Toggle
+			{...attrs}
+			data-orientation={group?.orientation ?? 'horizontal'}
+			data-size={itemSize}
+			data-slot="toggle-group-item"
+			data-spacing={group?.spacing ?? 2}
+			data-variant={itemVariant}
+			disabled={disabledFlag}
+			pressed={pressed}
+			value={itemValue}
+			onPressedChange={(next, event) => group?.toggle(itemValue, next, event)}
+		/>
+	)
+}
+
+export { ToggleGroup, ToggleGroupItem }

package/src/toggle.tsx

@@ -0,0 +1,91 @@
+import type { IntrinsicElements, Stateful, Stateless, WithChildren } from 'ajo'
+import type { OmitArg } from './utils'
+import { callHandler, controlled, dom, statefulRootAttrs as rootAttrs } from 'ajo-cloves'
+
+/** Props for a controlled or uncontrolled two-state toggle button. */
+export type ToggleArgs = OmitArg<IntrinsicElements['button'], 'children'> & WithChildren<{
+	/** Controlled pressed state. */
+	pressed?: boolean
+	/** Initial pressed state for uncontrolled usage. */
+	defaultPressed?: boolean
+	/** Called when the pressed state changes. */
+	onPressedChange?: (pressed: boolean, event: Event) => void
+}>
+
+type ToggleRootArgs = WithChildren<{
+	defaultPressed?: boolean
+	disabled?: boolean
+	onClick?: unknown
+	onPressedChange?: ToggleArgs['onPressedChange']
+	pressed?: boolean
+}>
+
+const pressedAttribute = (pressed: boolean) => pressed ? 'true' : 'false'
+const stateAttribute = (pressed: boolean) => pressed ? 'on' : 'off'
+
+const ToggleRoot: Stateful<ToggleRootArgs, 'button'> = function* ({ defaultPressed, pressed }) {
+	let disabled = false
+	let onClick: unknown
+	let onPressedChange: ToggleArgs['onPressedChange']
+	const state = controlled<boolean>(this, {
+		fallback: Boolean(pressed ?? defaultPressed),
+		onChange: (next, event) => onPressedChange?.(next, event!),
+	})
+
+	for (const args of this) {
+		disabled = Boolean(args.disabled)
+		onClick = args.onClick
+		onPressedChange = args.onPressedChange
+		state.sync(args.pressed != null ? Boolean(args.pressed) : undefined)
+
+		if (dom(this)) {
+			this.dataset.state = stateAttribute(state.value)
+			this.setAttribute('aria-pressed', pressedAttribute(state.value))
+			this.onclick = event => {
+				callHandler(onClick, event)
+				if (event.defaultPrevented || disabled) return
+
+				state.set(!state.value, event)
+			}
+		}
+
+		yield <>{args.children}</>
+	}
+}
+
+ToggleRoot.is = 'button'
+
+/** Unstyled two-state button using aria-pressed. */
+const Toggle: Stateless<ToggleArgs> = ({
+	children,
+	defaultPressed,
+	disabled,
+	onPressedChange,
+	pressed,
+	type = 'button',
+	'set:onclick': onClick,
+	...attrs
+}) => {
+	const state = stateAttribute(Boolean(pressed ?? defaultPressed))
+	const disabledFlag = Boolean(disabled)
+
+	return (
+		<ToggleRoot
+			{...rootAttrs(attrs)}
+			defaultPressed={defaultPressed}
+			disabled={disabledFlag}
+			onClick={onClick}
+			onPressedChange={onPressedChange}
+			pressed={pressed}
+			attr:aria-pressed={pressedAttribute(state === 'on')}
+			attr:data-state={state}
+			attr:data-slot={attrs['data-slot'] ?? 'toggle'}
+			attr:disabled={disabledFlag || undefined}
+			attr:type={type}
+		>
+			{children}
+		</ToggleRoot>
+	)
+}
+
+export { Toggle }

package/src/toolbar.tsx

@@ -0,0 +1,212 @@
+import type { IntrinsicElements, Stateful, Stateless, WithChildren } from 'ajo'
+import type { OmitArg } from './utils'
+import { dom, listen, roving, statefulRootAttrs as rootAttrs } from 'ajo-cloves'
+import { context } from 'ajo/context'
+import { DirectionContext } from './direction'
+
+/** Layout and keyboard-navigation axis of a toolbar. */
+export type ToolbarOrientation = 'horizontal' | 'vertical'
+
+/** Props for a toolbar with roving focus among descendant controls. */
+export type ToolbarArgs = WithChildren<OmitArg<IntrinsicElements['div'], 'dir'> & {
+	/** Text direction for horizontal arrow-key navigation. Defaults to the nearest DirectionProvider. */
+	dir?: 'ltr' | 'rtl'
+	/** Allow arrow-key focus to wrap at the ends. */
+	loop?: boolean
+	/** Toolbar orientation. */
+	orientation?: ToolbarOrientation
+}>
+
+/** Props for a separator whose orientation follows the parent toolbar. */
+export type ToolbarSeparatorArgs = IntrinsicElements['div']
+
+type ToolbarRootArgs = WithChildren<{
+	dir: 'ltr' | 'rtl'
+	loop: boolean
+	orientation: ToolbarOrientation
+}>
+
+type ToolbarContextValue = {
+	orientation: ToolbarOrientation
+}
+
+const ToolbarContext = context<ToolbarContextValue | null>(null)
+
+const CONTROL_SELECTOR = 'button, [href], input, select, textarea, summary, [tabindex]'
+
+// Focusable toolbar controls in DOM order (the house trigger-row filter:
+// enabled and visible; summary joins for details-based facets), scoped to
+// the toolbar's own layer: controls inside floating popover content opened
+// from the toolbar (menus, selects) or inside a composed <dialog> never join
+// the row. Visibility uses checkVisibility because closed-details content is
+// content-visibility-hidden in Chromium (offsetParent stays non-null there);
+// the offsetParent fallback covers engines without it.
+const controls = (root: HTMLElement) => {
+	const layer = root.closest('[popover], dialog')
+	return Array.from(root.querySelectorAll<HTMLElement>(CONTROL_SELECTOR)).filter(control =>
+		!(control as HTMLButtonElement).disabled &&
+		(control.checkVisibility?.() ?? control.offsetParent !== null) &&
+		control.closest('[popover], dialog') === layer,
+	)
+}
+
+const NON_TEXT_INPUTS = new Set(['button', 'checkbox', 'color', 'file', 'hidden', 'image', 'radio', 'range', 'reset', 'submit'])
+
+// Text-entry controls own their caret keys (APG): roving must not steal them.
+const textEntry = (element: HTMLElement) =>
+	element instanceof HTMLTextAreaElement ||
+	element.isContentEditable ||
+	(element instanceof HTMLInputElement && !NON_TEXT_INPUTS.has(element.type))
+
+// A text control releases an arrow key only when caret handling no longer
+// needs it: a collapsed caret sitting at the matching edge. Home/End and
+// vertical arrows always stay with the caret. The escape edge follows the
+// control's own resolved direction (a dir="auto" or forced-ltr input inside
+// an rtl toolbar keeps its productive caret keys); the toolbar dir only
+// steers roving movement.
+const caretEscapes = (target: HTMLElement, event: KeyboardEvent) => {
+	if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') return false
+	if (!(target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement)) return false
+	const caret = target.selectionStart
+	if (caret == null || caret !== target.selectionEnd) return false
+	const rtl = getComputedStyle(target).direction === 'rtl'
+	return (event.key === 'ArrowLeft') !== rtl ? caret === 0 : caret === target.value.length
+}
+
+const ToolbarRoot: Stateful<ToolbarRootArgs> = function* () {
+	let active: HTMLElement | null = null
+	let dir: 'ltr' | 'rtl' = 'ltr'
+	let loop = true
+	let orientation: ToolbarOrientation = 'horizontal'
+	let queued = false
+
+	// Single tab stop over the live control row (roving tabindex): the active
+	// control keeps tabindex 0, the rest get -1; focusing any control moves the
+	// stop, and the stop is repaired to the first control in DOM order when the
+	// active one unmounts, hides, or disables.
+	// Toolbar keeps this separate from bar(): it navigates arbitrary controls,
+	// not an open-value trigger row with follow policy.
+	const apply = () => {
+		if (!dom(this)) return
+		const row = controls(this)
+		if (!active || !row.includes(active)) active = row[0] ?? null
+		for (const control of row) {
+			const value = control === active ? '0' : '-1'
+			if (control.getAttribute('tabindex') !== value) control.setAttribute('tabindex', value)
+		}
+	}
+
+	const sync = () => {
+		if (queued) return
+		queued = true
+		queueMicrotask(() => {
+			queued = false
+			apply()
+		})
+	}
+
+	const nav = roving(this, {
+		items: () => controls(this),
+		orientation: () => orientation,
+		dir: () => dir,
+		loop: () => loop,
+		onMove: target => target.focus(),
+	})
+
+	listen(this, 'focusin', (event: FocusEvent) => {
+		const target = event.target as HTMLElement | null
+		if (!target || !controls(this).includes(target)) return
+		active = target
+		apply()
+	})
+
+	listen(this, 'keydown', (event: KeyboardEvent) => {
+		const target = event.target as HTMLElement | null
+		// A composed widget that already consumed the key (open menu, slider,
+		// a toggle group outside a toolbar) wins over toolbar roving, and so
+		// does an active IME composition (keyCode 229 covers engines that
+		// fire the arrow before isComposing settles): an arrow at a caret
+		// edge mid-composition must not move focus and abort the composition.
+		if (!target || event.defaultPrevented || event.isComposing || event.keyCode === 229) return
+		if (!controls(this).includes(target)) return
+		if (textEntry(target) && !caretEscapes(target, event)) return
+		nav.handle(event)
+	})
+
+	if (dom(this)) {
+		// Controls can mount/unmount or flip disabled/hidden from a nested
+		// component's own render without this component re-rendering; watch the
+		// subtree and repair the tab stop. The equality guard in apply() keeps
+		// its own tabindex writes from re-firing the observer.
+		const observer = new MutationObserver(sync)
+		observer.observe(this, {
+			attributeFilter: ['disabled', 'hidden', 'tabindex'],
+			attributes: true,
+			childList: true,
+			subtree: true,
+		})
+		this.signal.addEventListener('abort', () => observer.disconnect())
+	}
+
+	for (const args of this) {
+		dir = args.dir
+		loop = args.loop
+		orientation = args.orientation
+
+		ToolbarContext({ orientation })
+
+		sync()
+		yield <>{args.children}</>
+	}
+}
+
+
+/** Unstyled toolbar: arbitrary controls behind a single tab stop with dir-aware arrow-key roving (APG toolbar pattern). Button, ToggleGroup, Select, and Input compose inside; nested ToggleGroup items join the toolbar roving. */
+const Toolbar: Stateless<ToolbarArgs> = ({
+	children,
+	'data-slot': slot = 'toolbar',
+	dir,
+	loop = true,
+	orientation = 'horizontal',
+	role = 'toolbar',
+	...attrs
+}) => {
+	const resolvedDir = dir ?? DirectionContext()
+
+	return (
+		<ToolbarRoot
+			{...rootAttrs(attrs)}
+			dir={resolvedDir}
+			loop={loop}
+			orientation={orientation}
+			attr:aria-orientation={orientation}
+			attr:data-orientation={orientation}
+			attr:data-slot={slot}
+			attr:dir={resolvedDir}
+			attr:role={role}
+		>
+			{children}
+		</ToolbarRoot>
+	)
+}
+
+/** Unstyled separator between toolbar groups, oriented across the toolbar axis. */
+const ToolbarSeparator: Stateless<ToolbarSeparatorArgs> = ({
+	role = 'separator',
+	...attrs
+}) => {
+	const toolbar = ToolbarContext()
+	const orientation = (toolbar?.orientation ?? 'horizontal') === 'horizontal' ? 'vertical' : 'horizontal'
+
+	return (
+		<div
+			{...attrs}
+			aria-orientation={orientation}
+			data-orientation={orientation}
+			data-slot="toolbar-separator"
+			role={role}
+		/>
+	)
+}
+
+export { Toolbar, ToolbarSeparator }