diff --git a/bun.lock b/bun.lock index 8bfedb7ffc..6570d7fd39 100644 --- a/bun.lock +++ b/bun.lock @@ -561,6 +561,7 @@ "@zag-js/menu": "2.0.0-next.4", "@zag-js/menubar": "2.0.0-next.4", "@zag-js/meter": "2.0.0-next.4", + "@zag-js/navigation-menu": "2.0.0-next.4", "@zag-js/number-flow": "2.0.0-next.4", "@zag-js/number-input": "2.0.0-next.4", "@zag-js/pagination": "2.0.0-next.4", diff --git a/packages/web/README.md b/packages/web/README.md index a78ff8556e..36e160fae5 100644 --- a/packages/web/README.md +++ b/packages/web/README.md @@ -5,10 +5,10 @@ ordinary CSS. No framework runtime is required. This package is a prerelease. It includes accordion, angle slider, avatar, carousel, checkbox and checkbox group, clipboard, collapsible, combobox, command, date input, date picker, dialog, drawer, editable, field, fieldset, file -upload, floating panel, highlight, hover card, listbox, marquee, menu, menubar, meter, number flow, number input, -pagination, password input, pin input, popover, progress, qr code, radio group, rating group, scroll area, segment -group, select, signature pad, slider, splitter, steps, swap, switch, table of contents, tabs, tags input, timer, toast, -toggle, toggle group, tooltip, tour, tree view, and virtualizer. +upload, floating panel, highlight, hover card, listbox, marquee, menu, menubar, meter, navigation menu, number flow, +number input, pagination, password input, pin input, popover, progress, qr code, radio group, rating group, scroll area, +segment group, select, signature pad, slider, splitter, steps, swap, switch, table of contents, tabs, tags input, timer, +toast, toggle, toggle group, tooltip, tour, tree view, and virtualizer. ## Usage diff --git a/packages/web/examples/navigation-menu/basic.ts b/packages/web/examples/navigation-menu/basic.ts new file mode 100644 index 0000000000..0803f1b842 --- /dev/null +++ b/packages/web/examples/navigation-menu/basic.ts @@ -0,0 +1,99 @@ +import { + Accessibility, + ChevronDown, + Clapperboard, + createElement, + Layers, + ListChecks, + Palette, + Rocket, + Sparkles, +} from 'lucide' + +import '@ark-ui/web/navigation-menu' + +import styles from 'styles/navigation-menu.module.css' + +type Icon = typeof Rocket + +const icon = (node: Icon) => createElement(node, { 'aria-hidden': 'true' }).outerHTML + +const overviewSections = [ + { + label: 'Get started', + links: [ + { href: '#quick-start', title: 'Quick Start', description: 'Install and assemble', icon: Rocket }, + { href: '#styling', title: 'Styling', description: 'CSS, CSS-in-JS, or utilities', icon: Palette }, + ], + }, + { + label: 'Learn', + links: [ + { href: '#accessibility', title: 'Accessibility', description: 'Keyboard and ARIA support', icon: Accessibility }, + { href: '#releases', title: 'Releases', description: "What's new in Ark UI", icon: Sparkles }, + ], + }, +] + +const guideLinks = [ + { href: '#animation', title: 'Animation', description: 'CSS or JavaScript', icon: Clapperboard }, + { href: '#composition', title: 'Composition', description: 'Replace and compose parts', icon: Layers }, + { href: '#forms', title: 'Forms', description: 'Native and library forms', icon: ListChecks }, +] + +const linkCard = (item: { href: string; title: string; description: string; icon: Icon }) => /* html */ ` + + + ${icon(item.icon)} + + ${item.title} + ${item.description} + + + ` + +const trigger = (label: string) => /* html */ ` + + + ` + +const items = () => /* html */ ` + + ${trigger('Overview')} + +
+ ${overviewSections + .map( + (section) => /* html */ ` +
+ ${section.label} + ${section.links.map(linkCard).join('')} +
`, + ) + .join('')} +
+
+
+ + ${trigger('Guides')} + +
+ Guides + ${guideLinks.map(linkCard).join('')} +
+
+
+ + Documentation + ` + +export function mount(root: HTMLElement) { + root.innerHTML = /* html */ ` + + ${items()} + + ` +} diff --git a/packages/web/examples/navigation-menu/controlled.ts b/packages/web/examples/navigation-menu/controlled.ts new file mode 100644 index 0000000000..b60cfd8861 --- /dev/null +++ b/packages/web/examples/navigation-menu/controlled.ts @@ -0,0 +1,108 @@ +import { + Accessibility, + ChevronDown, + Clapperboard, + createElement, + Layers, + ListChecks, + Palette, + Rocket, + Sparkles, +} from 'lucide' + +import '@ark-ui/web/navigation-menu' + +import styles from 'styles/navigation-menu.module.css' + +type Icon = typeof Rocket + +const icon = (node: Icon) => createElement(node, { 'aria-hidden': 'true' }).outerHTML + +const overviewSections = [ + { + label: 'Get started', + links: [ + { href: '#quick-start', title: 'Quick Start', description: 'Install and assemble', icon: Rocket }, + { href: '#styling', title: 'Styling', description: 'CSS, CSS-in-JS, or utilities', icon: Palette }, + ], + }, + { + label: 'Learn', + links: [ + { href: '#accessibility', title: 'Accessibility', description: 'Keyboard and ARIA support', icon: Accessibility }, + { href: '#releases', title: 'Releases', description: "What's new in Ark UI", icon: Sparkles }, + ], + }, +] + +const guideLinks = [ + { href: '#animation', title: 'Animation', description: 'CSS or JavaScript', icon: Clapperboard }, + { href: '#composition', title: 'Composition', description: 'Replace and compose parts', icon: Layers }, + { href: '#forms', title: 'Forms', description: 'Native and library forms', icon: ListChecks }, +] + +const linkCard = (item: { href: string; title: string; description: string; icon: Icon }) => /* html */ ` + + + ${icon(item.icon)} + + ${item.title} + ${item.description} + + + ` + +const trigger = (label: string) => /* html */ ` + + + ` + +const items = () => /* html */ ` + + ${trigger('Overview')} + +
+ ${overviewSections + .map( + (section) => /* html */ ` +
+ ${section.label} + ${section.links.map(linkCard).join('')} +
`, + ) + .join('')} +
+
+
+ + ${trigger('Guides')} + +
+ Guides + ${guideLinks.map(linkCard).join('')} +
+
+
+ + Documentation + ` + +export function mount(root: HTMLElement) { + root.innerHTML = /* html */ ` +
+ Open: none + + ${items()} + + +
` + + const menu = root.querySelector('ark-navigation-menu')! + const output = root.querySelector('output')! + menu.addEventListener('valuechange', (event) => { + output.textContent = `Open: ${event.detail.value || 'none'}` + }) +} diff --git a/packages/web/examples/navigation-menu/vertical.ts b/packages/web/examples/navigation-menu/vertical.ts new file mode 100644 index 0000000000..f73fee1476 --- /dev/null +++ b/packages/web/examples/navigation-menu/vertical.ts @@ -0,0 +1,99 @@ +import { + Accessibility, + ChevronDown, + Clapperboard, + createElement, + Layers, + ListChecks, + Palette, + Rocket, + Sparkles, +} from 'lucide' + +import '@ark-ui/web/navigation-menu' + +import styles from 'styles/navigation-menu.module.css' + +type Icon = typeof Rocket + +const icon = (node: Icon) => createElement(node, { 'aria-hidden': 'true' }).outerHTML + +const overviewSections = [ + { + label: 'Get started', + links: [ + { href: '#quick-start', title: 'Quick Start', description: 'Install and assemble', icon: Rocket }, + { href: '#styling', title: 'Styling', description: 'CSS, CSS-in-JS, or utilities', icon: Palette }, + ], + }, + { + label: 'Learn', + links: [ + { href: '#accessibility', title: 'Accessibility', description: 'Keyboard and ARIA support', icon: Accessibility }, + { href: '#releases', title: 'Releases', description: "What's new in Ark UI", icon: Sparkles }, + ], + }, +] + +const guideLinks = [ + { href: '#animation', title: 'Animation', description: 'CSS or JavaScript', icon: Clapperboard }, + { href: '#composition', title: 'Composition', description: 'Replace and compose parts', icon: Layers }, + { href: '#forms', title: 'Forms', description: 'Native and library forms', icon: ListChecks }, +] + +const linkCard = (item: { href: string; title: string; description: string; icon: Icon }) => /* html */ ` + + + ${icon(item.icon)} + + ${item.title} + ${item.description} + + + ` + +const trigger = (label: string) => /* html */ ` + + + ` + +const items = () => /* html */ ` + + ${trigger('Overview')} + +
+ ${overviewSections + .map( + (section) => /* html */ ` +
+ ${section.label} + ${section.links.map(linkCard).join('')} +
`, + ) + .join('')} +
+
+
+ + ${trigger('Guides')} + +
+ Guides + ${guideLinks.map(linkCard).join('')} +
+
+
+ + Documentation + ` + +export function mount(root: HTMLElement) { + root.innerHTML = /* html */ ` + + ${items()} + + ` +} diff --git a/packages/web/examples/navigation-menu/viewport.ts b/packages/web/examples/navigation-menu/viewport.ts new file mode 100644 index 0000000000..387cdd5967 --- /dev/null +++ b/packages/web/examples/navigation-menu/viewport.ts @@ -0,0 +1,107 @@ +import { + Accessibility, + ChevronDown, + Clapperboard, + createElement, + Layers, + ListChecks, + Palette, + Rocket, + Sparkles, +} from 'lucide' + +import '@ark-ui/web/navigation-menu' + +import styles from 'styles/navigation-menu-viewport.module.css' + +type Icon = typeof Rocket + +const icon = (node: Icon) => createElement(node, { 'aria-hidden': 'true' }).outerHTML + +const overviewSections = [ + { + label: 'Get started', + links: [ + { href: '#quick-start', title: 'Quick Start', description: 'Install and assemble', icon: Rocket }, + { href: '#styling', title: 'Styling', description: 'CSS, CSS-in-JS, or utilities', icon: Palette }, + ], + }, + { + label: 'Learn', + links: [ + { href: '#accessibility', title: 'Accessibility', description: 'Keyboard and ARIA support', icon: Accessibility }, + { href: '#releases', title: 'Releases', description: "What's new in Ark UI", icon: Sparkles }, + ], + }, +] + +const guideLinks = [ + { href: '#animation', title: 'Animation', description: 'CSS or JavaScript', icon: Clapperboard }, + { href: '#composition', title: 'Composition', description: 'Replace and compose parts', icon: Layers }, + { href: '#forms', title: 'Forms', description: 'Native and library forms', icon: ListChecks }, +] + +const linkCard = (item: { href: string; title: string; description: string; icon: Icon }) => /* html */ ` + + + ${icon(item.icon)} + + ${item.title} + ${item.description} + + + ` + +const trigger = (label: string) => /* html */ ` + + + ` + +const items = () => /* html */ ` + + ${trigger('Overview')} + +
+ ${overviewSections + .map( + (section) => /* html */ ` +
+ ${section.label} + ${section.links.map(linkCard).join('')} +
`, + ) + .join('')} +
+
+
+ + ${trigger('Guides')} + +
+ Guides + ${guideLinks.map(linkCard).join('')} +
+
+
+ + Documentation + ` + +export function mount(root: HTMLElement) { + root.innerHTML = /* html */ ` +
+ + ${items()} + + + + + + + + +
` +} diff --git a/packages/web/package.json b/packages/web/package.json index a7f1d3b2ef..8dc0156392 100644 --- a/packages/web/package.json +++ b/packages/web/package.json @@ -44,6 +44,7 @@ "@zag-js/menu": "2.0.0-next.4", "@zag-js/menubar": "2.0.0-next.4", "@zag-js/meter": "2.0.0-next.4", + "@zag-js/navigation-menu": "2.0.0-next.4", "@zag-js/number-flow": "2.0.0-next.4", "@zag-js/number-input": "2.0.0-next.4", "@zag-js/pagination": "2.0.0-next.4", @@ -350,6 +351,10 @@ "./number-flow": { "types": "./dist/components/number-flow/index.d.ts", "import": "./dist/components/number-flow/index.js" + }, + "./navigation-menu": { + "types": "./dist/components/navigation-menu/index.d.ts", + "import": "./dist/components/navigation-menu/index.js" } }, "sideEffects": true, diff --git a/packages/web/src/components/navigation-menu/index.ts b/packages/web/src/components/navigation-menu/index.ts new file mode 100644 index 0000000000..7600a374a3 --- /dev/null +++ b/packages/web/src/components/navigation-menu/index.ts @@ -0,0 +1,20 @@ +import type { CallbackEvents } from '../../utils/events.js' +import './root.js' +import './parts.js' +import type { Api, Props } from '@zag-js/navigation-menu' +import type { RootElement, StateProperties } from '../../utils/define.js' + +export type { + Api as NavigationMenuApi, + ValueChangeDetails as NavigationMenuValueChangeDetails, +} from '@zag-js/navigation-menu' +export interface NavigationMenuElement + extends RootElement, Pick, StateProperties {} + +declare global { + interface HTMLElementTagNameMap { + 'ark-navigation-menu': NavigationMenuElement + } +} + +export type NavigationMenuEventMap = CallbackEvents diff --git a/packages/web/src/components/navigation-menu/navigation-menu.stories.ts b/packages/web/src/components/navigation-menu/navigation-menu.stories.ts new file mode 100644 index 0000000000..e276e069d4 --- /dev/null +++ b/packages/web/src/components/navigation-menu/navigation-menu.stories.ts @@ -0,0 +1,17 @@ +import { renderExample } from '../../../.storybook/render-example.js' +import type { Meta, StoryObj } from '@storybook/html-vite' +import { mount as BasicExample } from '../../../examples/navigation-menu/basic.js' +import { mount as ViewportExample } from '../../../examples/navigation-menu/viewport.js' +import { mount as VerticalExample } from '../../../examples/navigation-menu/vertical.js' +import { mount as ControlledExample } from '../../../examples/navigation-menu/controlled.js' + +const meta: Meta = { title: 'Components / Navigation Menu' } +export default meta + +export const Basic: StoryObj = { name: 'Basic', render: renderExample(BasicExample) } + +export const Viewport: StoryObj = { name: 'Viewport', render: renderExample(ViewportExample) } + +export const Vertical: StoryObj = { name: 'Vertical', render: renderExample(VerticalExample) } + +export const Controlled: StoryObj = { name: 'Controlled', render: renderExample(ControlledExample) } diff --git a/packages/web/src/components/navigation-menu/parts.ts b/packages/web/src/components/navigation-menu/parts.ts new file mode 100644 index 0000000000..293c6ade77 --- /dev/null +++ b/packages/web/src/components/navigation-menu/parts.ts @@ -0,0 +1,111 @@ +import type * as navigationMenu from '@zag-js/navigation-menu' +import { spreadProps } from '@zag-js/vanilla' + +import { definePart, wrapped, wrappedButton } from '../../utils/define.js' +import { definePresencePart } from '../../utils/presence.js' +import { contentValueOf, itemTag, itemValueOf, root } from './shared.js' + +type Align = navigationMenu.ViewportProps['align'] + +const itemPropsOf = (el: Element) => { + const item = el.closest(itemTag) + return { value: itemValueOf(el), disabled: item?.hasAttribute('disabled') || undefined } +} + +const linkValueOf = (el: HTMLElement) => { + const content = el.closest('ark-navigation-menu-content') + return content ? contentValueOf(content) : itemValueOf(el) +} + +const alignOf = (el: Element) => + (el.closest('ark-navigation-menu-viewport-positioner')?.getAttribute('align') ?? undefined) as Align + +definePart({ + tag: 'ark-navigation-menu-list', + root, + props: (api) => api.getListProps(), +}) + +definePart({ + tag: itemTag, + root, + props: (api, el) => api.getItemProps(itemPropsOf(el)), +}) + +definePart({ + tag: 'ark-navigation-menu-trigger', + root, + target: wrappedButton, + props: (api, el) => api.getTriggerProps(itemPropsOf(el)), +}) + +definePart({ + tag: 'ark-navigation-menu-link', + root, + target: wrapped('a'), + props: (api, el) => + api.getLinkProps({ + value: el.getAttribute('value') ?? linkValueOf(el), + current: el.hasAttribute('current'), + closeOnClick: el.hasAttribute('close-on-click') ? el.getAttribute('close-on-click') !== 'false' : undefined, + }), +}) + +definePart({ + tag: 'ark-navigation-menu-item-indicator', + root, + props: (api, el) => api.getItemIndicatorProps(itemPropsOf(el)), +}) + +definePart({ + tag: 'ark-navigation-menu-arrow', + root, + props: (api) => api.getArrowProps(), +}) + +definePresencePart({ + tag: 'ark-navigation-menu-indicator', + root, + present: (api) => api.open, + props: (api) => api.getIndicatorProps(), +}) + +definePart({ + tag: 'ark-navigation-menu-viewport-positioner', + root, + props: (api, el) => api.getViewportPositionerProps({ align: alignOf(el) }), +}) + +definePresencePart({ + tag: 'ark-navigation-menu-viewport', + root, + present: (api) => api.open, + props: (api, el) => api.getViewportProps({ align: alignOf(el) }), +}) + +const proxies = new WeakMap() + +const moveIntoViewport = (api: navigationMenu.Api, el: HTMLElement, id: string) => { + const viewport = api.isViewportRendered ? api.getViewportNode() : null + if (!viewport) return + const value = contentValueOf(el) + let pair = proxies.get(el) + if (!pair) { + pair = [document.createElement('div'), document.createElement('div')] + proxies.set(el, pair) + } + if (el.parentElement !== viewport) { + el.before(...pair) + viewport.append(el) + } + spreadProps(pair[0], api.getViewportProxyProps({ value }), id) + spreadProps(pair[1], api.getTriggerProxyProps({ value }), id) +} + +definePresencePart({ + tag: 'ark-navigation-menu-content', + root, + present: (api, el) => api.value === contentValueOf(el), + props: (api, el) => api.getContentProps({ value: contentValueOf(el) }), + render: (api, el) => moveIntoViewport(api, el, el.closest(root)?.id ?? ''), +}) diff --git a/packages/web/src/components/navigation-menu/root.ts b/packages/web/src/components/navigation-menu/root.ts new file mode 100644 index 0000000000..feeb2d8f1d --- /dev/null +++ b/packages/web/src/components/navigation-menu/root.ts @@ -0,0 +1,46 @@ +import * as navigationMenu from '@zag-js/navigation-menu' + +import { num, str } from '../../utils/attrs.js' +import { defineRoot } from '../../utils/define.js' +import { dirOf, root } from './shared.js' + +defineRoot({ + tag: root, + machine: navigationMenu.machine, + connect: navigationMenu.connect, + + attributes: [ + 'value', + 'default-value', + 'orientation', + 'open-delay', + 'close-delay', + 'disable-click-trigger', + 'disable-hover-trigger', + 'disable-pointer-leave-close', + ], + properties: ['ids', 'translations'], + state: { + value: { + get: (api) => api.value, + set: (api, value) => api.setValue(String(value ?? '')), + }, + }, + props: (el) => ({ + value: el.hasAttribute('value') ? (el.getAttribute('value') ?? '') : undefined, + defaultValue: str(el, 'default-value'), + orientation: str<'horizontal' | 'vertical'>(el, 'orientation'), + openDelay: num(el, 'open-delay'), + closeDelay: num(el, 'close-delay'), + disableClickTrigger: el.hasAttribute('disable-click-trigger'), + disableHoverTrigger: el.hasAttribute('disable-hover-trigger'), + disablePointerLeaveClose: el.hasAttribute('disable-pointer-leave-close'), + dir: dirOf(el), + }), + + events: { + onValueChange: 'valuechange', + }, + + rootProps: (api) => api.getRootProps(), +}) diff --git a/packages/web/src/components/navigation-menu/shared.ts b/packages/web/src/components/navigation-menu/shared.ts new file mode 100644 index 0000000000..823debd23b --- /dev/null +++ b/packages/web/src/components/navigation-menu/shared.ts @@ -0,0 +1,18 @@ +export const root = 'ark-navigation-menu' +export const itemTag = 'ark-navigation-menu-item' + +const contentValues = new WeakMap() + +export const itemValueOf = (el: Element) => el.closest(itemTag)?.getAttribute('value') ?? '' + +export function contentValueOf(el: HTMLElement) { + let value = contentValues.get(el) + if (value == null) { + value = el.getAttribute('value') ?? itemValueOf(el) + contentValues.set(el, value) + } + return value +} + +export const dirOf = (el: Element) => + (el.parentElement?.closest('[dir]')?.getAttribute('dir') ?? undefined) as 'ltr' | 'rtl' | undefined diff --git a/packages/web/src/components/navigation-menu/tests/navigation-menu.test.ts b/packages/web/src/components/navigation-menu/tests/navigation-menu.test.ts new file mode 100644 index 0000000000..3ce5ab8a2e --- /dev/null +++ b/packages/web/src/components/navigation-menu/tests/navigation-menu.test.ts @@ -0,0 +1,51 @@ +import { screen, waitFor } from '@testing-library/dom' +import userEvent from '@testing-library/user-event' + +import { mount as Basic } from '../../../../examples/navigation-menu/basic.js' +import { mount as Controlled } from '../../../../examples/navigation-menu/controlled.js' +import { mount as Viewport } from '../../../../examples/navigation-menu/viewport.js' +import { mount } from '../../../test-utils.js' + +const user = userEvent.setup() + +afterEach(() => { + document.body.innerHTML = '' +}) + +const content = (value: string) => + Array.from(document.querySelectorAll('ark-navigation-menu-content')).find((el) => + el.querySelector(`a[href="${value}"]`), + )! + +test('navigation menu opens an item content from its trigger', async () => { + mount(Basic) + const trigger = await screen.findByRole('button', { name: 'Overview' }) + await waitFor(() => expect(trigger).toHaveAttribute('aria-expanded', 'false')) + expect(content('#quick-start')).not.toBeVisible() + await user.click(trigger) + await waitFor(() => expect(trigger).toHaveAttribute('aria-expanded', 'true')) + await waitFor(() => expect(content('#quick-start')).toBeVisible()) + expect(trigger.getAttribute('aria-controls')).toBe(content('#quick-start').id) + await user.click(trigger) + await waitFor(() => expect(trigger).toHaveAttribute('aria-expanded', 'false')) +}) + +test('navigation menu emits valuechange and exposes value as a property', async () => { + mount(Controlled) + const menu = document.querySelector('ark-navigation-menu')! + await user.click(await screen.findByRole('button', { name: 'Guides' })) + await waitFor(() => expect(document.querySelector('output')).toHaveTextContent('Open: guides')) + expect(menu.value).toBe('guides') + menu.value = 'overview' + await waitFor(() => expect(screen.getByRole('button', { name: 'Overview' })).toHaveAttribute('aria-expanded', 'true')) +}) + +test('navigation menu moves content into the viewport and keeps its item value', async () => { + mount(Viewport) + const viewport = document.querySelector('ark-navigation-menu-viewport')! + await user.click(await screen.findByRole('button', { name: 'Overview' })) + await waitFor(() => expect(viewport.contains(content('#quick-start'))).toBe(true)) + await waitFor(() => expect(content('#quick-start')).toBeVisible()) + expect(document.querySelector('ark-navigation-menu-item[value=overview] [data-trigger-proxy]')).toBeInTheDocument() + expect(content('#quick-start').querySelector('a')).toHaveAttribute('data-navigation-menu-link') +}) diff --git a/packages/web/src/index.ts b/packages/web/src/index.ts index 37119e0ce0..5f82c73c80 100644 --- a/packages/web/src/index.ts +++ b/packages/web/src/index.ts @@ -24,6 +24,7 @@ export * from './components/marquee/index.js' export * from './components/menu/index.js' export * from './components/menubar/index.js' export * from './components/meter/index.js' +export * from './components/navigation-menu/index.js' export * from './components/number-flow/index.js' export * from './components/number-input/index.js' export * from './components/pagination/index.js'