@octane-xplat/ui 0.7.3 → 0.10.0

package/src/Markdown.web.test.tsrx

@@ -0,0 +1,68 @@
+// @vitest-environment jsdom
+import { afterEach, expect, it } from 'vitest'
+import { act, createRoot } from 'octane'
+import { Markdown } from './Markdown.tsrx'
+
+const roots: any[] = []
+function mount() {
+	const el = document.createElement('div')
+	document.body.append(el)
+	const root = createRoot(el)
+	roots.push(root)
+	const render = (props: any) => act(() => root.render(<Markdown {...props} />))
+	return { el, render }
+}
+
+afterEach(() => {
+	for (const root of roots.splice(0)) act(() => root.unmount())
+	document.body.innerHTML = ''
+})
+
+it('renders a baked data doc', () => {
+	const { el, render } = mount()
+	render({ data: { kind: 'octane-xplat/md', v: 1, children: [{ t: 'h', depth: 1, children: [{ t: 'text', text: 'Hi' }] }] } })
+	expect(el.textContent).toContain('Hi')
+})
+
+it('parses and renders a text prop', () => {
+	const { el, render } = mount()
+	render({ text: 'body **bold** and `code`' })
+	expect(el.textContent).toContain('body bold and code')
+	const bolds = [...el.querySelectorAll('.font-bold')].map((n) => n.textContent)
+	expect(bolds).toContain('bold')
+})
+
+it('streams growing text without remounting settled blocks', () => {
+	const { el, render } = mount()
+	render({ text: '# Title\n\nfirst para', isStreaming: true })
+	const heading = el.querySelector('.text-2xl')
+	const para = el.querySelectorAll('label, span, p')
+	render({ text: '# Title\n\nfirst para\n\nsecond para', isStreaming: true })
+	expect(el.textContent).toContain('second para')
+	// Settled blocks keep their DOM nodes across chunk renders.
+	expect(el.querySelector('.text-2xl')).toBe(heading)
+})
+
+it('withholds a half-typed link while streaming', () => {
+	const { el, render } = mount()
+	render({ text: 'see [the doc', isStreaming: true })
+	expect(el.textContent).not.toContain('[')
+	render({ text: 'see [the doc](https://x.dev)', isStreaming: true })
+	expect(el.textContent).toContain('the doc')
+})
+
+it('wraps newly arrived text in vx-md-fade spans', () => {
+	const { el, render } = mount()
+	render({ text: 'alpha', isStreaming: true })
+	render({ text: 'alpha beta', isStreaming: true })
+	const fades = [...el.querySelectorAll('.vx-md-fade')].map((n) => n.textContent)
+	expect(fades.at(-1)).toBe(' beta')
+})
+
+it('skips fade spans when fadeIn is false', () => {
+	const { el, render } = mount()
+	render({ text: 'alpha', isStreaming: true, fadeIn: false })
+	render({ text: 'alpha beta', isStreaming: true, fadeIn: false })
+	expect(el.textContent).toContain('alpha beta')
+	expect(el.querySelector('.vx-md-fade')).toBeNull()
+})

package/src/MenuParts.macos.tsrx

@@ -0,0 +1,137 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { useContext, useMemo, useRef, useState } from 'octane'
+import type { MenuItemProps, MenuCheckboxItemProps, MenuRadioItemProps, MenuRadioGroupProps, MenuDividerProps, MenuSubMenuProps, MenuSurfaceProps } from './props'
+import { MenuRadioContext, MenuRadioProvider, useDropdownMenuContext } from './menu-context'
+import { View } from './View.macos.tsrx'
+import { Text } from './Text.macos.tsrx'
+import { Pressable } from './Pressable.macos.tsrx'
+import { Icon } from './Icon.macos.tsrx'
+import { Separator } from './Separator.macos.tsrx'
+import { Popover } from './Popover.macos.tsrx'
+import { MenuSurface } from './MenuSurface.macos.tsrx'
+
+export function DropdownMenuItem(props: MenuItemProps) @{
+	const menu = useDropdownMenuContext()
+	const select = () => {
+		if (props.isDisabled) return
+		props.onSelect?.()
+		if (props.hasCloseOnSelect !== false) menu?.closeMenu()
+	}
+
+	<Pressable ref={props.ref} id={props.id} className={['vx-menu-item', props.isDisabled && 'vx-menu-item--disabled', props.className]} style={props.style}
+		accessibilityRole="menuitem" accessibilityLabel={typeof props.label === 'string' ? props.label : undefined}
+		accessibilityState={{ disabled: props.isDisabled }} onPress={select}>
+		{props.icon && <Icon name={props.icon} />}
+		<Text className="vx-menu-item-label">{props.label}</Text>
+		{props.description && <Text>{props.description}</Text>}{props.endContent}
+	</Pressable>
+}
+
+export function DropdownMenuCheckboxItem(props: MenuCheckboxItemProps) @{
+	const menu = useDropdownMenuContext()
+	const select = () => {
+		if (props.isDisabled) return
+		props.onValueChange?.(!props.value)
+		props.onSelect?.()
+		if (props.hasCloseOnSelect) menu?.closeMenu()
+	}
+
+	<Pressable ref={props.ref} id={props.id} className={['vx-menu-item', props.isDisabled && 'vx-menu-item--disabled', props.className]} style={props.style}
+		accessibilityRole="menuitemcheckbox" accessibilityLabel={typeof props.label === 'string' ? props.label : undefined}
+		accessibilityState={{ disabled: props.isDisabled, checked: props.value }} onPress={select}>
+		<Text accessible={false}>{props.value ? '✓' : '○'}</Text>
+		{props.icon && <Icon name={props.icon} />}
+		<Text className="vx-menu-item-label">{props.label}</Text>
+		{props.description && <Text>{props.description}</Text>}{props.endContent}
+	</Pressable>
+}
+
+export function DropdownMenuRadioGroup(props: MenuRadioGroupProps) @{
+	const [internal, setInternal] = useState(props.defaultValue)
+	const context: MenuRadioGroupProps = {
+		get value() { return props.value !== undefined ? props.value : internal },
+		get isDisabled() { return props.isDisabled },
+		get hasCloseOnSelect() { return props.hasCloseOnSelect },
+		get label() { return props.label },
+		onValueChange: (value) => {
+			if (props.isDisabled) return
+			if (props.value === undefined) setInternal(value)
+			props.onValueChange?.(value)
+		},
+	}
+
+	<View accessibilityRole="group" accessibilityLabel={props.label}>
+		<MenuRadioProvider value={context}>{props.children}</MenuRadioProvider>
+	</View>
+}
+
+export function DropdownMenuRadioItem(props: MenuRadioItemProps) @{
+	const group = useContext(MenuRadioContext)
+	const menu = useDropdownMenuContext()
+	if (!group) throw new Error('MenuRadioItem requires a MenuRadioGroup')
+	const select = () => {
+		if (props.isDisabled || group.isDisabled) return
+		if (group.value !== props.value) group.onValueChange?.(props.value)
+		props.onSelect?.()
+		if ((props.hasCloseOnSelect ?? group.hasCloseOnSelect) !== false) menu?.closeMenu()
+	}
+
+	<Pressable ref={props.ref} id={props.id} className={['vx-menu-item', props.isDisabled && 'vx-menu-item--disabled', props.className]} style={props.style}
+		accessibilityRole="menuitemradio" accessibilityLabel={typeof props.label === 'string' ? props.label : undefined}
+		accessibilityState={{ disabled: props.isDisabled || group.isDisabled, checked: group.value === props.value }} onPress={select}>
+		<Text accessible={false}>{group.value === props.value ? '●' : '○'}</Text>
+		{props.icon && <Icon name={props.icon} />}
+		<Text className="vx-menu-item-label">{props.label}</Text>
+		{props.description && <Text>{props.description}</Text>}{props.endContent}
+	</Pressable>
+}
+
+export function DropdownMenuDivider(props: MenuDividerProps) @{
+	<Separator {...props} />
+}
+
+export function DropdownMenuSubMenu(props: MenuSubMenuProps) @{
+	const parent = useDropdownMenuContext()
+	const anchor = useRef<any>(null)
+	const mergedRef = useMemo(() => props.ref ? [anchor, props.ref] : anchor, [props.ref])
+	const [internal, setInternal] = useState(props.defaultOpen ?? false)
+	const open = props.isOpen ?? internal
+	const setOpen = (next: boolean) => {
+		if (next && props.isDisabled) return
+		if (props.isOpen === undefined) setInternal(next)
+		props.onOpenChange?.(next)
+	}
+
+	const closeLevel = () => setOpen(false)
+
+	<>
+		<Pressable ref={mergedRef} id={props.id} className={['vx-menu-item', props.isDisabled && 'vx-menu-item--disabled', props.className]} style={props.style}
+			accessibilityRole="menuitem" accessibilityLabel={typeof props.label === 'string' ? props.label : undefined}
+			accessibilityHint="Opens submenu" accessibilityState={{ disabled: props.isDisabled }} onPress={() => setOpen(!open)}
+			web={{ 'aria-haspopup': 'menu', 'aria-expanded': open, 'data-menu-submenu': true,
+				onKeyDown: (event: any) => {
+					if (event.isComposing || event.keyCode === 229 || event.defaultPrevented) return
+					if (event.key === 'ArrowRight' && !props.isDisabled) { event.preventDefault(); event.stopPropagation(); setOpen(true) }
+				} }}>
+			{props.icon && <Icon name={props.icon} />}<Text>{props.label}</Text><Text accessible={false}>›</Text>
+		</Pressable>
+		<Popover anchor={anchor} open={open} placement="right" alignment="start" onDismiss={() => setOpen(false)} className="vx-menu">
+			<MenuSurface closeMenu={() => { setOpen(false); parent?.closeMenu() }} closeLevel={closeLevel} label={typeof props.label === 'string' ? props.label : undefined}>
+				<MenuData items={props.items} />{props.children}
+			</MenuSurface>
+		</Popover>
+	</>
+}
+
+/** Convert legacy data into the same stateful components as compound content. */
+export function MenuData(props: Pick<MenuSurfaceProps, 'items'>) @{
+	<>
+		{props.items?.map((item) => item.type === 'divider' ? <DropdownMenuDivider id={item.key} />
+			: item.type === 'radio-group' ? <DropdownMenuRadioGroup label={item.label ?? 'Options'} value={typeof item.value === 'string' ? item.value : undefined} onValueChange={item.onValueChange} isDisabled={item.isDisabled ?? item.disabled} hasCloseOnSelect={item.hasCloseOnSelect}>
+				{item.items?.map((option) => <DropdownMenuRadioItem id={option.key} label={option.label} value={typeof option.value === 'string' ? option.value : option.key} isDisabled={option.isDisabled ?? option.disabled} onSelect={option.onSelect} />)}
+			</DropdownMenuRadioGroup>
+			: item.type === 'checkbox' ? <DropdownMenuCheckboxItem {...item} id={item.key} label={item.label} value={item.value === true} onValueChange={item.onValueChange} isDisabled={item.isDisabled ?? item.disabled} />
+			: item.items ? <DropdownMenuSubMenu {...item} id={item.key} label={item.label} isDisabled={item.isDisabled ?? item.disabled} />
+			: <DropdownMenuItem {...item} id={item.key} label={item.label} isDisabled={item.isDisabled ?? item.disabled} />)}
+	</>
+}

package/src/MenuParts.tsrx

@@ -0,0 +1,137 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useContext, useMemo, useRef, useState } from 'octane'
+import type { MenuItemProps, MenuCheckboxItemProps, MenuRadioItemProps, MenuRadioGroupProps, MenuDividerProps, MenuSubMenuProps, MenuSurfaceProps } from './props'
+import { MenuRadioContext, MenuRadioProvider, useDropdownMenuContext } from './menu-context'
+import { View } from './View'
+import { Text } from './Text'
+import { Pressable } from './Pressable'
+import { Icon } from './Icon'
+import { Separator } from './Separator'
+import { Popover } from './Popover'
+import { MenuSurface } from './MenuSurface'
+
+export function DropdownMenuItem(props: MenuItemProps) @{
+	const menu = useDropdownMenuContext()
+	const select = () => {
+		if (props.isDisabled) return
+		props.onSelect?.()
+		if (props.hasCloseOnSelect !== false) menu?.closeMenu()
+	}
+
+	<Pressable ref={props.ref} id={props.id} className={['vx-menu-item', props.isDisabled && 'vx-menu-item--disabled', props.className]} style={props.style}
+		accessibilityRole="menuitem" accessibilityLabel={typeof props.label === 'string' ? props.label : undefined}
+		accessibilityState={{ disabled: props.isDisabled }} onPress={select}>
+		{props.icon && <Icon name={props.icon} />}
+		<Text className="vx-menu-item-label">{props.label}</Text>
+		{props.description && <Text>{props.description}</Text>}{props.endContent}
+	</Pressable>
+}
+
+export function DropdownMenuCheckboxItem(props: MenuCheckboxItemProps) @{
+	const menu = useDropdownMenuContext()
+	const select = () => {
+		if (props.isDisabled) return
+		props.onValueChange?.(!props.value)
+		props.onSelect?.()
+		if (props.hasCloseOnSelect) menu?.closeMenu()
+	}
+
+	<Pressable ref={props.ref} id={props.id} className={['vx-menu-item', props.isDisabled && 'vx-menu-item--disabled', props.className]} style={props.style}
+		accessibilityRole="menuitemcheckbox" accessibilityLabel={typeof props.label === 'string' ? props.label : undefined}
+		accessibilityState={{ disabled: props.isDisabled, checked: props.value }} onPress={select}>
+		<Text accessible={false}>{props.value ? '✓' : '○'}</Text>
+		{props.icon && <Icon name={props.icon} />}
+		<Text className="vx-menu-item-label">{props.label}</Text>
+		{props.description && <Text>{props.description}</Text>}{props.endContent}
+	</Pressable>
+}
+
+export function DropdownMenuRadioGroup(props: MenuRadioGroupProps) @{
+	const [internal, setInternal] = useState(props.defaultValue)
+	const context: MenuRadioGroupProps = {
+		get value() { return props.value !== undefined ? props.value : internal },
+		get isDisabled() { return props.isDisabled },
+		get hasCloseOnSelect() { return props.hasCloseOnSelect },
+		get label() { return props.label },
+		onValueChange: (value) => {
+			if (props.isDisabled) return
+			if (props.value === undefined) setInternal(value)
+			props.onValueChange?.(value)
+		},
+	}
+
+	<View accessibilityRole="group" accessibilityLabel={props.label}>
+		<MenuRadioProvider value={context}>{props.children}</MenuRadioProvider>
+	</View>
+}
+
+export function DropdownMenuRadioItem(props: MenuRadioItemProps) @{
+	const group = useContext(MenuRadioContext)
+	const menu = useDropdownMenuContext()
+	if (!group) throw new Error('MenuRadioItem requires a MenuRadioGroup')
+	const select = () => {
+		if (props.isDisabled || group.isDisabled) return
+		if (group.value !== props.value) group.onValueChange?.(props.value)
+		props.onSelect?.()
+		if ((props.hasCloseOnSelect ?? group.hasCloseOnSelect) !== false) menu?.closeMenu()
+	}
+
+	<Pressable ref={props.ref} id={props.id} className={['vx-menu-item', props.isDisabled && 'vx-menu-item--disabled', props.className]} style={props.style}
+		accessibilityRole="menuitemradio" accessibilityLabel={typeof props.label === 'string' ? props.label : undefined}
+		accessibilityState={{ disabled: props.isDisabled || group.isDisabled, checked: group.value === props.value }} onPress={select}>
+		<Text accessible={false}>{group.value === props.value ? '●' : '○'}</Text>
+		{props.icon && <Icon name={props.icon} />}
+		<Text className="vx-menu-item-label">{props.label}</Text>
+		{props.description && <Text>{props.description}</Text>}{props.endContent}
+	</Pressable>
+}
+
+export function DropdownMenuDivider(props: MenuDividerProps) @{
+	<Separator {...props} />
+}
+
+export function DropdownMenuSubMenu(props: MenuSubMenuProps) @{
+	const parent = useDropdownMenuContext()
+	const anchor = useRef<any>(null)
+	const mergedRef = useMemo(() => props.ref ? [anchor, props.ref] : anchor, [props.ref])
+	const [internal, setInternal] = useState(props.defaultOpen ?? false)
+	const open = props.isOpen ?? internal
+	const setOpen = (next: boolean) => {
+		if (next && props.isDisabled) return
+		if (props.isOpen === undefined) setInternal(next)
+		props.onOpenChange?.(next)
+	}
+
+	const closeLevel = () => setOpen(false)
+
+	<>
+		<Pressable ref={mergedRef} id={props.id} className={['vx-menu-item', props.isDisabled && 'vx-menu-item--disabled', props.className]} style={props.style}
+			accessibilityRole="menuitem" accessibilityLabel={typeof props.label === 'string' ? props.label : undefined}
+			accessibilityHint="Opens submenu" accessibilityState={{ disabled: props.isDisabled }} onPress={() => setOpen(!open)}
+			web={{ 'aria-haspopup': 'menu', 'aria-expanded': open, 'data-menu-submenu': true,
+				onKeyDown: (event: any) => {
+					if (event.isComposing || event.keyCode === 229 || event.defaultPrevented) return
+					if (event.key === 'ArrowRight' && !props.isDisabled) { event.preventDefault(); event.stopPropagation(); setOpen(true) }
+				} }}>
+			{props.icon && <Icon name={props.icon} />}<Text>{props.label}</Text><Text accessible={false}>›</Text>
+		</Pressable>
+		<Popover anchor={anchor} open={open} placement="right" alignment="start" onDismiss={() => setOpen(false)} className="vx-menu">
+			<MenuSurface closeMenu={() => { setOpen(false); parent?.closeMenu() }} closeLevel={closeLevel} label={typeof props.label === 'string' ? props.label : undefined}>
+				<MenuData items={props.items} />{props.children}
+			</MenuSurface>
+		</Popover>
+	</>
+}
+
+/** Convert legacy data into the same stateful components as compound content. */
+export function MenuData(props: Pick<MenuSurfaceProps, 'items'>) @{
+	<>
+		{props.items?.map((item) => item.type === 'divider' ? <DropdownMenuDivider id={item.key} />
+			: item.type === 'radio-group' ? <DropdownMenuRadioGroup label={item.label ?? 'Options'} value={typeof item.value === 'string' ? item.value : undefined} onValueChange={item.onValueChange} isDisabled={item.isDisabled ?? item.disabled} hasCloseOnSelect={item.hasCloseOnSelect}>
+				{item.items?.map((option) => <DropdownMenuRadioItem id={option.key} label={option.label} value={typeof option.value === 'string' ? option.value : option.key} isDisabled={option.isDisabled ?? option.disabled} onSelect={option.onSelect} />)}
+			</DropdownMenuRadioGroup>
+			: item.type === 'checkbox' ? <DropdownMenuCheckboxItem {...item} id={item.key} label={item.label} value={item.value === true} onValueChange={item.onValueChange} isDisabled={item.isDisabled ?? item.disabled} />
+			: item.items ? <DropdownMenuSubMenu {...item} id={item.key} label={item.label} isDisabled={item.isDisabled ?? item.disabled} />
+			: <DropdownMenuItem {...item} id={item.key} label={item.label} isDisabled={item.isDisabled ?? item.disabled} />)}
+	</>
+}

package/src/MenuParts.web.tsrx

@@ -0,0 +1,138 @@
+import { useContext, useMemo, useRef, useState } from 'octane'
+import type { MenuItemProps, MenuCheckboxItemProps, MenuRadioItemProps, MenuRadioGroupProps, MenuDividerProps, MenuSubMenuProps, MenuSurfaceProps } from './props'
+import { MenuRadioContext, MenuRadioProvider, useDropdownMenuContext } from './menu-context'
+import { View } from './View.web.tsrx'
+import { Text } from './Text.web.tsrx'
+import { Pressable } from './Pressable.web.tsrx'
+import { Icon } from './Icon.web.tsrx'
+import { Separator } from './Separator.web.tsrx'
+import { Popover } from './Popover.web.tsrx'
+import { MenuSurface } from './MenuSurface.web.tsrx'
+
+export function DropdownMenuItem(props: MenuItemProps) @{
+	const menu = useDropdownMenuContext()
+	const select = () => {
+		if (props.isDisabled) return
+		props.onSelect?.()
+		if (props.hasCloseOnSelect !== false) menu?.closeMenu()
+	}
+
+	<Pressable ref={props.ref} id={props.id} className={['vx-menu-item', props.isDisabled && 'vx-menu-item--disabled', props.className]} style={props.style}
+		accessibilityRole="menuitem" accessibilityLabel={typeof props.label === 'string' ? props.label : undefined}
+		accessibilityState={{ disabled: props.isDisabled }} onPress={select}>
+		{props.icon && <Icon name={props.icon} />}
+		<Text className="vx-menu-item-label">{props.label}</Text>
+		{props.description && <Text>{props.description}</Text>}{props.endContent}
+	</Pressable>
+}
+
+export function DropdownMenuCheckboxItem(props: MenuCheckboxItemProps) @{
+	const menu = useDropdownMenuContext()
+	const select = () => {
+		if (props.isDisabled) return
+		props.onValueChange?.(!props.value)
+		props.onSelect?.()
+		if (props.hasCloseOnSelect) menu?.closeMenu()
+	}
+
+	<Pressable ref={props.ref} id={props.id} className={['vx-menu-item', props.isDisabled && 'vx-menu-item--disabled', props.className]} style={props.style}
+		accessibilityRole="menuitemcheckbox" accessibilityLabel={typeof props.label === 'string' ? props.label : undefined}
+		accessibilityState={{ disabled: props.isDisabled, checked: props.value }} onPress={select}>
+		<Text accessible={false}>{props.value ? '✓' : '○'}</Text>
+		{props.icon && <Icon name={props.icon} />}
+		<Text className="vx-menu-item-label">{props.label}</Text>
+		{props.description && <Text>{props.description}</Text>}{props.endContent}
+	</Pressable>
+}
+
+export function DropdownMenuRadioGroup(props: MenuRadioGroupProps) @{
+	const [internal, setInternal] = useState(props.defaultValue)
+	const context: MenuRadioGroupProps = {
+		get value() { return props.value !== undefined ? props.value : internal },
+		get isDisabled() { return props.isDisabled },
+		get hasCloseOnSelect() { return props.hasCloseOnSelect },
+		get label() { return props.label },
+		onValueChange: (value) => {
+			if (props.isDisabled) return
+			if (props.value === undefined) setInternal(value)
+			props.onValueChange?.(value)
+		},
+	}
+
+	<View accessibilityRole="group" accessibilityLabel={props.label}>
+		<MenuRadioProvider value={context}>{props.children}</MenuRadioProvider>
+	</View>
+}
+
+export function DropdownMenuRadioItem(props: MenuRadioItemProps) @{
+	const group = useContext(MenuRadioContext)
+	const menu = useDropdownMenuContext()
+	if (!group) throw new Error('MenuRadioItem requires a MenuRadioGroup')
+	const select = () => {
+		if (props.isDisabled || group.isDisabled) return
+		if (group.value !== props.value) group.onValueChange?.(props.value)
+		props.onSelect?.()
+		if ((props.hasCloseOnSelect ?? group.hasCloseOnSelect) !== false) menu?.closeMenu()
+	}
+
+	<Pressable ref={props.ref} id={props.id} className={['vx-menu-item', props.isDisabled && 'vx-menu-item--disabled', props.className]} style={props.style}
+		accessibilityRole="menuitemradio" accessibilityLabel={typeof props.label === 'string' ? props.label : undefined}
+		accessibilityState={{ disabled: props.isDisabled || group.isDisabled, checked: group.value === props.value }} onPress={select}>
+		<Text accessible={false}>{group.value === props.value ? '●' : '○'}</Text>
+		{props.icon && <Icon name={props.icon} />}
+		<Text className="vx-menu-item-label">{props.label}</Text>
+		{props.description && <Text>{props.description}</Text>}{props.endContent}
+	</Pressable>
+}
+
+export function DropdownMenuDivider(props: MenuDividerProps) @{
+	<Separator {...props} />
+}
+
+export function DropdownMenuSubMenu(props: MenuSubMenuProps) @{
+	const parent = useDropdownMenuContext()
+	const anchor = useRef<any>(null)
+	const initialFocus = useRef<'first' | 'container'>('container')
+	const mergedRef = useMemo(() => props.ref ? [anchor, props.ref] : anchor, [props.ref])
+	const [internal, setInternal] = useState(props.defaultOpen ?? false)
+	const open = props.isOpen ?? internal
+	const setOpen = (next: boolean) => {
+		if (next && props.isDisabled) return
+		if (props.isOpen === undefined) setInternal(next)
+		props.onOpenChange?.(next)
+	}
+
+	const closeLevel = () => setOpen(false)
+
+	<>
+		<Pressable ref={mergedRef} id={props.id} className={['vx-menu-item', props.isDisabled && 'vx-menu-item--disabled', props.className]} style={props.style}
+			accessibilityRole="menuitem" accessibilityLabel={typeof props.label === 'string' ? props.label : undefined}
+			accessibilityHint="Opens submenu" accessibilityState={{ disabled: props.isDisabled }} onPress={() => setOpen(!open)}
+			web={{ onpointerdown: () => { initialFocus.current = 'container' }, 'aria-haspopup': 'menu', 'aria-expanded': String(open), 'data-menu-submenu': true,
+				onkeydown: (event: any) => {
+					if (event.isComposing || event.keyCode === 229 || event.defaultPrevented) return
+					if (event.key === 'Enter' || event.key === ' ') initialFocus.current = 'first'
+					if (event.key === (getComputedStyle(anchor.current).direction === 'rtl' ? 'ArrowLeft' : 'ArrowRight') && !props.isDisabled) { event.preventDefault(); event.stopPropagation(); initialFocus.current = 'first'; setOpen(true) }
+				} }}>
+			{props.icon && <Icon name={props.icon} />}<Text>{props.label}</Text><Text accessible={false}>›</Text>
+		</Pressable>
+		<Popover anchor={anchor} open={open} placement="right" alignment="start" onDismiss={() => setOpen(false)} className="vx-menu">
+			<MenuSurface initialFocus={initialFocus.current} closeMenu={() => { setOpen(false); parent?.closeMenu() }} closeLevel={closeLevel} label={typeof props.label === 'string' ? props.label : undefined}>
+				<MenuData items={props.items} />{props.children}
+			</MenuSurface>
+		</Popover>
+	</>
+}
+
+/** Convert legacy data into the same stateful components as compound content. */
+export function MenuData(props: Pick<MenuSurfaceProps, 'items'>) @{
+	<>
+		{props.items?.map((item) => item.type === 'divider' ? <DropdownMenuDivider id={item.key} />
+			: item.type === 'radio-group' ? <DropdownMenuRadioGroup label={item.label ?? 'Options'} value={typeof item.value === 'string' ? item.value : undefined} onValueChange={item.onValueChange} isDisabled={item.isDisabled ?? item.disabled} hasCloseOnSelect={item.hasCloseOnSelect}>
+				{item.items?.map((option) => <DropdownMenuRadioItem id={option.key} label={option.label} value={typeof option.value === 'string' ? option.value : option.key} isDisabled={option.isDisabled ?? option.disabled} onSelect={option.onSelect} />)}
+			</DropdownMenuRadioGroup>
+			: item.type === 'checkbox' ? <DropdownMenuCheckboxItem {...item} id={item.key} label={item.label} value={item.value === true} onValueChange={item.onValueChange} isDisabled={item.isDisabled ?? item.disabled} />
+			: item.items ? <DropdownMenuSubMenu {...item} id={item.key} label={item.label} isDisabled={item.isDisabled ?? item.disabled} />
+			: <DropdownMenuItem {...item} id={item.key} label={item.label} isDisabled={item.isDisabled ?? item.disabled} />)}
+	</>
+}

package/src/MenuSurface.macos.tsrx

@@ -0,0 +1,18 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import type { MenuSurfaceProps } from './props'
+import { MenuProvider } from './menu-context'
+import { View } from './View.macos.tsrx'
+import { Pressable } from './Pressable.macos.tsrx'
+import { Text } from './Text.macos.tsrx'
+
+/** Native popup roots receive explicit menu ownership instead of relying on context crossing roots. */
+export function MenuSurface(props: MenuSurfaceProps) @{
+	const context = { closeMenu: () => props.closeMenu(), menuSize: 'md' as const }
+
+	<View className="vx-menu-list" accessibilityRole="menu" accessibilityLabel={props.label}>
+		<MenuProvider value={context}>
+			{props.closeLevel && <Pressable accessibilityLabel="Back to parent menu" onPress={props.closeLevel}><Text>Back</Text></Pressable>}
+			{props.children}
+		</MenuProvider>
+	</View>
+}

package/src/MenuSurface.tsrx

@@ -0,0 +1,18 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { MenuSurfaceProps } from './props'
+import { MenuProvider } from './menu-context'
+import { View } from './View'
+import { Pressable } from './Pressable'
+import { Text } from './Text'
+
+/** Native popup roots receive explicit menu ownership instead of relying on context crossing roots. */
+export function MenuSurface(props: MenuSurfaceProps) @{
+	const context = { closeMenu: () => props.closeMenu(), menuSize: 'md' as const }
+
+	<View className="vx-menu-list" accessibilityRole="menu" accessibilityLabel={props.label}>
+		<MenuProvider value={context}>
+			{props.closeLevel && <Pressable accessibilityLabel="Back to parent menu" onPress={props.closeLevel}><Text>Back</Text></Pressable>}
+			{props.children}
+		</MenuProvider>
+	</View>
+}

package/src/MenuSurface.web.tsrx

@@ -0,0 +1,53 @@
+import { useEffect, useRef } from 'octane'
+import type { MenuSurfaceProps } from './props'
+import { MenuProvider } from './menu-context'
+
+/** Each portaled submenu is its own keyboard boundary. Escape belongs to Popover. */
+export function MenuSurface(props: MenuSurfaceProps) @{
+	const panel = useRef<HTMLDivElement | null>(null)
+	const search = useRef({ text: '', at: 0 })
+	const context = { closeMenu: () => props.closeMenu(), menuSize: 'md' as const }
+	const rows = () => Array.from(panel.current?.querySelectorAll<HTMLElement>('[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"]') ?? [])
+		.filter((row) => row.closest('[role="menu"]') === panel.current)
+
+	useEffect(() => {
+		const items = rows()
+		for (const item of items) item.tabIndex = -1
+		const enabled = items.filter((item) => item.getAttribute('aria-disabled') !== 'true')
+		if (props.initialFocus === 'first' && enabled.length) enabled[0].focus()
+		else if (props.initialFocus === 'last' && enabled.length) enabled.at(-1)?.focus()
+		else panel.current?.focus()
+	}, [])
+
+	const keydown = (event: KeyboardEvent) => {
+		if (event.isComposing || event.keyCode === 229 || event.defaultPrevented) return
+		const items = rows()
+		const index = items.indexOf(document.activeElement as HTMLElement)
+		let next: number | undefined
+		if (event.key === 'ArrowDown') next = (index + 1) % items.length
+		else if (event.key === 'ArrowUp') next = index <= 0 ? items.length - 1 : index - 1
+		else if (event.key === 'Home') next = 0
+		else if (event.key === 'End') next = items.length - 1
+		else if (event.key === (getComputedStyle(panel.current!).direction === 'rtl' ? 'ArrowRight' : 'ArrowLeft') && props.closeLevel) {
+			event.preventDefault(); event.stopPropagation(); props.closeLevel(); return
+		} else if (event.key === 'Tab') { props.closeMenu(); return }
+		else if (event.key.length === 1 && event.key !== ' ' && !event.ctrlKey && !event.altKey && !event.metaKey) {
+			const now = Date.now()
+			search.current.text = (now - search.current.at < 500 ? search.current.text : '') + event.key.toLowerCase()
+			search.current.at = now
+			const query = search.current.text
+			const match = items.map((_, offset) => (index + offset + 1) % items.length)
+				.find((i) => (items[i].getAttribute('aria-label') ?? items[i].textContent ?? '').trim().toLowerCase().startsWith(query))
+
+			next = match
+		}
+
+		if (next !== undefined && items[next]) {
+			event.preventDefault(); event.stopPropagation(); items[next].focus()
+		}
+	}
+
+	<div ref={panel} role="menu" aria-label={props.label} tabIndex={-1} className="vx-menu-list" onKeyDown={keydown}>
+		<MenuProvider value={context}>{props.children}</MenuProvider>
+	</div>
+}

package/src/MetadataList.macos.tsrx

@@ -0,0 +1,80 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { useState } from 'octane';
+import type { MetadataListProps } from './props';
+import { cx } from './cx';
+import { MetadataListProvider } from './metadata-list-context';
+import { Grid } from './layout.macos';
+import { Pressable } from './Pressable.macos.tsrx';
+import { toChildArray } from './child-array';
+
+function gridColumns(columns: 'multi' | 'single' | number, isStacked: boolean): string {
+	if (columns === 'single') {
+		return isStacked ? '*' : 'auto,*';
+	}
+
+	const n = columns === 'multi' ? 2 : Math.max(1, columns);
+	return isStacked
+		? Array.from({ length: n }, () => '*').join(',')
+		: Array.from({ length: n }, () => 'auto,*').join(',');
+}
+
+/** MetadataList — macOS leaf, same structure as the mobile leaf on the
+ *  AppKit host. */
+export function MetadataList(props: MetadataListProps) @{
+	const columns = props.columns ?? 'single';
+	const orientation = props.orientation ?? 'vertical';
+	const isHorizontal = orientation === 'horizontal';
+	const labelPosition =
+		props.label?.position ??
+		(isHorizontal || columns === 'multi' || (typeof columns === 'number' && columns > 1)
+			? 'top'
+			: 'start');
+
+	const isStacked = labelPosition === 'top' || isHorizontal;
+
+	const [isShowAll, setIsShowAll] = useState(false);
+	const childrenArray = toChildArray(props.children);
+	const effectiveMax = isHorizontal ? undefined : props.maxNumOfItems;
+	const isExceedMax = effectiveMax != null && childrenArray.length > effectiveMax;
+	const visibleChildren =
+		isExceedMax && !isShowAll ? childrenArray.slice(0, effectiveMax) : childrenArray;
+
+	<MetadataListProvider
+		value={{ labelPosition, labelWidth: props.label?.width, orientation }}
+	>
+		<flexboxlayout
+			id={props.id}
+			className={cx('vx-metadatalist', props.className)}
+			style={{ flexDirection: 'column', ...props.style }}
+			flexDirection="column"
+		>
+			{props.title != null ? (
+				<flexboxlayout style={{ marginBottom: 12 }}>
+					{typeof props.title === 'string' || typeof props.title === 'number'
+						? <label whiteSpace="normal" style={{ fontWeight: 600 }}>{props.title}</label>
+						: props.title}
+				</flexboxlayout>
+			) : null}
+			{isHorizontal ? (
+				<flexboxlayout className="flex-row" flexDirection="row" gap={16}>
+					{visibleChildren}
+				</flexboxlayout>
+			) : (
+				<Grid columns={gridColumns(columns, isStacked)} className="vx-metadatalist-list">
+					{visibleChildren}
+				</Grid>
+			)}
+			{isExceedMax ? (
+				<Pressable
+					accessibilityRole="button"
+					accessibilityLabel={isShowAll ? 'Show less' : 'Show more'}
+					onPress={() => setIsShowAll((prev) => !prev)}
+				>
+					<label className="text-sm" style={{ paddingTop: 8, paddingBottom: 8, color: '#2563eb' }}>
+						{isShowAll ? 'Show less' : 'Show more'}
+					</label>
+				</Pressable>
+			) : null}
+		</flexboxlayout>
+	</MetadataListProvider>
+}