@remix-run/ui 0.1.0 → 0.1.2

package/src/components/listbox/demos/overview.demo.tsx

@@ -0,0 +1,101 @@
+import { css, on, type Handle } from '@remix-run/ui'
+import { Glyph } from '@remix-run/ui/glyph'
+import * as listbox from '@remix-run/ui/listbox'
+import type { ListboxValue } from '@remix-run/ui/listbox'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @name Listbox Overview
+ * @description A keyboard-navigable listbox with selection, highlighting, and an optional flash-selection animation.
+ */
+export default function Example(handle: Handle) {
+  let value: ListboxValue = options[0]!.value
+  let activeValue: ListboxValue = options[0]!.value
+  let flashSelection = false
+
+  return () => {
+    return (
+      <div mix={stackCss}>
+        <listbox.Context
+          value={value}
+          activeValue={activeValue}
+          flashSelection={flashSelection}
+          onSelect={(nextValue) => {
+            value = nextValue
+            handle.update()
+          }}
+          onHighlight={(nextActiveValue) => {
+            activeValue = nextActiveValue
+            handle.update()
+          }}
+        >
+          <div tabIndex={0} mix={[listbox.listStyle, listbox.list(), containerCss]}>
+            {options.map((option) => (
+              <div key={option.value} mix={[listbox.optionStyle, listbox.option(option)]}>
+                <Glyph mix={listbox.glyphStyle} name="check" />
+                <span mix={listbox.labelStyle}>{option.label}</span>
+              </div>
+            ))}
+          </div>
+        </listbox.Context>
+        <div mix={controlsCss}>
+          <label mix={checkboxLabelCss}>
+            <input
+              type="checkbox"
+              defaultChecked={flashSelection}
+              mix={on('change', (event) => {
+                flashSelection = event.currentTarget.checked
+                handle.update()
+              })}
+            />{' '}
+            Flash selection
+          </label>
+          <p mix={valueCss}>{`value=${value ?? 'null'}`}</p>
+        </div>
+      </div>
+    )
+  }
+}
+
+const options = [
+  { label: 'Apple', value: 'apple' },
+  { label: 'Banana', value: 'banana' },
+  { label: 'Cherry', value: 'cherry' },
+  { label: 'Date', value: 'date' },
+  { label: 'Elderberry', value: 'elderberry' },
+  { label: 'Fig', value: 'fig' },
+  { label: 'Grape', value: 'grape' },
+] as const
+
+const containerCss = css({
+  borderColor: theme.colors.border.subtle,
+  padding: theme.space.xs,
+  borderRadius: theme.radius.lg,
+  borderStyle: 'solid',
+})
+
+const stackCss = css({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: theme.space.md,
+  width: '100%',
+})
+
+const controlsCss = css({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: theme.space.xs,
+})
+
+const checkboxLabelCss = css({
+  fontSize: theme.fontSize.sm,
+  lineHeight: theme.lineHeight.normal,
+  color: theme.colors.text.secondary,
+})
+
+const valueCss = css({
+  margin: 0,
+  fontFamily: theme.fontFamily.mono,
+  fontSize: theme.fontSize.xs,
+  color: theme.colors.text.secondary,
+})

package/src/components/listbox/listbox.ts

@@ -17,17 +17,8 @@ import { flashAttribute } from '../../utils/flash-attribute.ts'
 
 export type ListboxValue = string | null
 
-enum NavigationStrategy {
-  Next = 0,
-  Previous = 1,
-  First = 2,
-  Last = 3,
-}
-
-enum State {
-  Idle = 'idle',
-  Selecting = 'selecting',
-}
+type NavigationStrategy = 'next' | 'previous' | 'first' | 'last'
+type State = 'idle' | 'selecting'
 
 interface Values {
   value: ListboxValue
@@ -160,7 +151,7 @@ export const labelStyle = itemLabelCss
 
 function ListboxProvider(handle: Handle<ListboxProviderProps, ListboxContext>) {
   let options: RegisteredOption[] = []
-  let state = State.Idle
+  let state: State = 'idle'
 
   function getOption(value: ListboxValue) {
     return options.find((option) => option.value === value)
@@ -221,16 +212,16 @@ function ListboxProvider(handle: Handle<ListboxProviderProps, ListboxContext>) {
       return findSearchMatch(text, fromValue)
     },
     navigateFirst() {
-      context.navigate(NavigationStrategy.First)
+      context.navigate('first')
     },
     navigateLast() {
-      context.navigate(NavigationStrategy.Last)
+      context.navigate('last')
     },
     navigateNext() {
-      context.navigate(NavigationStrategy.Next)
+      context.navigate('next')
     },
     navigatePrevious() {
-      context.navigate(NavigationStrategy.Previous)
+      context.navigate('previous')
     },
     scrollActiveOptionIntoView() {
       context.scrollActiveOptionIntoView()
@@ -261,13 +252,13 @@ function ListboxProvider(handle: Handle<ListboxProviderProps, ListboxContext>) {
     },
 
     async select(value) {
-      if (state === State.Selecting) {
+      if (state === 'selecting') {
         return
       }
-      state = State.Selecting
+      state = 'selecting'
       let option = getOption(value)
       if (!isInteractableOption(option)) {
-        state = State.Idle
+        state = 'idle'
         return
       }
       handle.props.onSelect(value, option)
@@ -279,17 +270,17 @@ function ListboxProvider(handle: Handle<ListboxProviderProps, ListboxContext>) {
         )
       }
       await handle.props.onSelectSettled?.(value, option)
-      state = State.Idle
+      state = 'idle'
     },
 
     highlight(value) {
-      if (state === State.Selecting) return
+      if (state === 'selecting') return
       let option = getOption(value)
       handle.props.onHighlight(value, option)
     },
 
     highlightSearchMatch(text) {
-      if (state === State.Selecting) return
+      if (state === 'selecting') return
 
       let option = findSearchMatch(text, handle.props.activeValue)
 
@@ -300,7 +291,7 @@ function ListboxProvider(handle: Handle<ListboxProviderProps, ListboxContext>) {
     },
 
     navigate(strategy: NavigationStrategy) {
-      if (state === State.Selecting) return
+      if (state === 'selecting') return
 
       let option: RegisteredOption | undefined
       let interactableOptions = getInteractableOptions()
@@ -309,19 +300,19 @@ function ListboxProvider(handle: Handle<ListboxProviderProps, ListboxContext>) {
       )
 
       switch (strategy) {
-        case NavigationStrategy.Next:
+        case 'next':
           option = interactableOptions[activeIndex + 1] ?? interactableOptions[0]
           break
-        case NavigationStrategy.Previous:
+        case 'previous':
           option =
             activeIndex === -1
               ? interactableOptions[interactableOptions.length - 1]
               : interactableOptions[activeIndex - 1]
           break
-        case NavigationStrategy.First:
+        case 'first':
           option = interactableOptions[0]
           break
-        case NavigationStrategy.Last:
+        case 'last':
           option = interactableOptions[interactableOptions.length - 1]
           break
       }
@@ -359,15 +350,15 @@ const listMixin = createMixin<HTMLElement>((handle) => (props) => {
       switch (event.key) {
         case 'ArrowDown':
           event.preventDefault()
-          context.navigate(NavigationStrategy.Next)
+          context.navigate('next')
           break
         case 'ArrowUp':
           event.preventDefault()
-          context.navigate(NavigationStrategy.Previous)
+          context.navigate('previous')
           break
         case 'Tab':
           event.preventDefault()
-          context.navigate(NavigationStrategy.First)
+          context.navigate('first')
           break
         case 'Enter':
         case ' ':
@@ -376,11 +367,11 @@ const listMixin = createMixin<HTMLElement>((handle) => (props) => {
           break
         case 'Home':
           event.preventDefault()
-          context.navigate(NavigationStrategy.First)
+          context.navigate('first')
           break
         case 'End':
           event.preventDefault()
-          context.navigate(NavigationStrategy.Last)
+          context.navigate('last')
       }
     }),
     hiddenTypeahead((text) => {

package/src/components/menu/README.md

@@ -0,0 +1,96 @@
+# menu
+
+`Menu` renders a button-triggered menu with keyboard navigation, checked items, selection events, and nested submenus. Use it for action menus and command groups.
+
+## Usage
+
+```tsx
+import type { Handle } from 'remix/ui'
+import { Menu, MenuItem, Submenu, onMenuSelect } from 'remix/ui/menu'
+import { separatorStyle } from 'remix/ui/separator'
+
+export function ViewMenu(handle: Handle) {
+  let wordWrap = false
+  let density = 'comfortable'
+
+  return () => (
+    <Menu
+      label="View"
+      mix={onMenuSelect((event) => {
+        if (event.item.name === 'wordWrap') {
+          wordWrap = event.item.checked ?? false
+        } else if (event.item.name === 'density' && event.item.value) {
+          density = event.item.value
+        }
+
+        void handle.update()
+      })}
+    >
+      <MenuItem checked={wordWrap} name="wordWrap" type="checkbox">
+        Word wrap
+      </MenuItem>
+      <MenuItem disabled name="minimap">
+        Minimap
+      </MenuItem>
+      <hr mix={separatorStyle} />
+      <MenuItem checked={density === 'compact'} name="density" type="radio" value="compact">
+        Compact
+      </MenuItem>
+      <MenuItem checked={density === 'comfortable'} name="density" type="radio" value="comfortable">
+        Comfortable
+      </MenuItem>
+      <Submenu label="Zoom">
+        <MenuItem name="zoomIn" value="zoom-in">
+          Zoom in
+        </MenuItem>
+        <MenuItem name="zoomOut" value="zoom-out">
+          Zoom out
+        </MenuItem>
+      </Submenu>
+    </Menu>
+  )
+}
+```
+
+Use `label` or `searchValue` when the rendered item content is not the text that should be used for event labels or typeahead.
+
+```tsx
+<MenuItem label="Open command palette" name="commandPalette" searchValue="palette">
+  Command palette
+</MenuItem>
+```
+
+Use `menuLabel` when the menu surface needs a different accessible label from the visible trigger.
+
+```tsx
+<Menu label="..." menuLabel="Project actions">
+  <MenuItem name="rename">Rename project</MenuItem>
+</Menu>
+```
+
+## `menu.*`
+
+- `Menu`: composed trigger, popover, and list component for the common menu case.
+- `MenuItem`: menu item wrapper. Supports regular, checkbox, and radio item roles through `type`, `checked`, `name`, `value`, `label`, `disabled`, and `searchValue`.
+- `Submenu`: nested menu wrapper with its own trigger and child menu surface.
+- `MenuList`: lower-level list wrapper for custom composition.
+- `onMenuSelect(...)`: event mixin for the bubbling `MenuSelectEvent`.
+- `MenuSelectEvent`: bubbling event class whose `item` describes the selected item.
+- `MenuSelectItem`: selected item shape with `checked`, `id`, `label`, `name`, `type`, and `value`.
+- `menu.Context`, `menu.trigger()`, `menu.popover()`, `menu.list()`, `menu.item(...)`, and `menu.submenuTrigger(...)`: lower-level composition primitives.
+- `buttonStyle`, `popoverStyle`, `listStyle`, `itemStyle`, `itemSlotStyle`, `itemLabelStyle`, `itemGlyphStyle`, and `triggerGlyphStyle`: flat style mixins used by the wrappers.
+- `MenuProps`, `MenuItemProps`, `MenuListProps`, `MenuProviderProps`, `MenuTriggerOptions`, `MenuItemOptions`, and `SubmenuProps`: public TypeScript props and option types.
+
+## Behavior Notes
+
+- Click opens the root menu and focuses the list; clicking the trigger again closes it and restores focus.
+- `ArrowDown` opens from the trigger at the first enabled item. `ArrowUp` opens at the last enabled item. Enter and Space open the menu with focus on the list.
+- Keyboard navigation skips disabled items and does not wrap past the first or last enabled item.
+- `Home` and `End` move to the first and last enabled item. Enter and Space activate the highlighted item.
+- Printable keys use typeahead. Typeahead matches `searchValue` when provided and otherwise uses the item label.
+- Submenus open with `ArrowRight`, close with `ArrowLeft`, and are anchored to the submenu trigger with `right-start` placement.
+- Pointer movement highlights enabled items. Submenus open after a short focus/pointer delay and use hover aim so they stay open while moving toward the child surface.
+- Selecting a regular item flashes that item. Selecting a checkbox or radio item flashes the committed checked state.
+- Selection dispatches one bubbled `MenuSelectEvent`, closes the full menu tree, and restores focus to the root trigger.
+- The composed `Menu` re-dispatches selection from its trigger so handlers on the `Menu` button and shared ancestors see the event once.
+- `menuLabel`, `Submenu.menuLabel`, and `Submenu.listProps` let composed menus label and customize menu surfaces separately from trigger content.

package/src/components/menu/demos/bubbling.demo.tsx

@@ -0,0 +1,34 @@
+import { on } from '@remix-run/ui'
+import { Menu, MenuItem, onMenuSelect } from '@remix-run/ui/menu'
+
+/**
+ * @name Menu Event Bubbling
+ * @description Item-level handlers fire before the root handler, letting individual items intercept events while others bubble up.
+ */
+export default function Example() {
+  return () => (
+    <Menu
+      label="Project"
+      menuLabel="Project actions"
+      mix={onMenuSelect((event) => {
+        console.log('Menu root handler:', event.item)
+      })}
+    >
+      <MenuItem name="open" value="open-project">
+        Open project
+      </MenuItem>
+      <MenuItem
+        name="rename"
+        value="rename-project"
+        mix={onMenuSelect((event) => {
+          console.log('Menu item handler:', event.item)
+        })}
+      >
+        Rename project
+      </MenuItem>
+      <MenuItem name="duplicate" value="duplicate-project">
+        Duplicate project
+      </MenuItem>
+    </Menu>
+  )
+}

package/src/components/menu/demos/overview.demo.tsx

@@ -0,0 +1,76 @@
+import { type Handle } from '@remix-run/ui'
+import { Menu, MenuItem, onMenuSelect, Submenu } from '@remix-run/ui/menu'
+import { separatorStyle } from '@remix-run/ui/separator'
+
+/**
+ * @name Menu Overview
+ * @description A hierarchical menu with checkboxes, radio groups, submenus, and separators.
+ */
+export default function Example(handle: Handle) {
+  type Density = 'comfortable' | 'compact'
+  let wordWrap = true
+  let minimap = false
+  let showGutter = true
+  let density: Density = 'comfortable'
+
+  return () => (
+    <Menu
+      label="View"
+      menuLabel="View options"
+      mix={onMenuSelect((event) => {
+        switch (event.item.name) {
+          case 'wordWrap':
+            wordWrap = !wordWrap
+            break
+          case 'minimap':
+            minimap = !minimap
+            break
+          case 'showGutter':
+            showGutter = !showGutter
+            break
+          case 'density':
+            density = event.item.value as Density
+            break
+        }
+        handle.update()
+      })}
+    >
+      <MenuItem name="wordWrap" type="checkbox" checked={wordWrap}>
+        Word wrap
+      </MenuItem>
+      <MenuItem name="minimap" type="checkbox" checked={minimap}>
+        Minimap
+      </MenuItem>
+      <MenuItem name="showGutter" type="checkbox" checked={showGutter}>
+        Show gutter
+      </MenuItem>
+
+      <hr mix={separatorStyle} />
+      <Submenu label="Zoom">
+        <MenuItem name="zoomIn" value="zoom-in">
+          Zoom In
+        </MenuItem>
+        <MenuItem name="zoomOut" value="zoom-out">
+          Zoom Out
+        </MenuItem>
+        <MenuItem name="resetZoom" value="reset-zoom">
+          Reset Zoom
+        </MenuItem>
+      </Submenu>
+
+      <Submenu label="Density">
+        <MenuItem
+          name="density"
+          type="radio"
+          value="comfortable"
+          checked={density === 'comfortable'}
+        >
+          Comfortable
+        </MenuItem>
+        <MenuItem name="density" type="radio" value="compact" checked={density === 'compact'}>
+          Compact
+        </MenuItem>
+      </Submenu>
+    </Menu>
+  )
+}

package/src/components/menu/menu.tsx

@@ -1,5 +1,3 @@
-// @jsxRuntime classic
-// @jsx createElement
 import {
   attrs,
   createElement,
@@ -8,6 +6,7 @@ import {
   on,
   ref,
   type CSSMixinDescriptor,
+  type Dispatched,
   type ElementProps,
   type Handle,
   type Props,
@@ -32,7 +31,10 @@ const MENU_FLASH_DURATION_MS = 60
 const SUBMENU_OPEN_DELAY_MS = 300
 const SUBMENU_ANCHOR_RELATIVE_TO = '[role="menu"] > [role^="menuitem"]'
 
-type MenuSelectHandler = (event: MenuSelectEvent, signal: AbortSignal) => void | Promise<void>
+type MenuSelectHandler<target extends HTMLElement> = (
+  event: Dispatched<MenuSelectEvent, target>,
+  signal: AbortSignal,
+) => void | Promise<void>
 
 const menuButtonCss: CSSMixinDescriptor = css({
   display: 'grid',
@@ -219,19 +221,8 @@ declare global {
 type MenuItemType = 'item' | 'checkbox' | 'radio'
 type CloseAnimation = 'fade' | 'none'
 type OpenStrategy = 'first' | 'last' | 'list' | 'none'
-
-enum NavigationStrategy {
-  Next = 0,
-  Previous = 1,
-  First = 2,
-  Last = 3,
-}
-
-enum State {
-  Idle = 'idle',
-  Dismissing = 'dismissing',
-  Selecting = 'selecting',
-}
+type NavigationStrategy = 'next' | 'previous' | 'first' | 'last'
+type State = 'idle' | 'dismissing' | 'selecting'
 
 export interface MenuSelectItem {
   checked?: boolean
@@ -435,7 +426,7 @@ function MenuProvider(handle: Handle<MenuProviderProps, MenuContextValue>) {
   let items: RegisteredMenuItem[] = []
   let listRef: HTMLElement | undefined
   let open = false
-  let state = State.Idle
+  let state: State = 'idle'
   let suppressNextPointerLeaveClear = false
   let surfaceRef: HTMLElement | undefined
   let triggerId: string | undefined
@@ -487,7 +478,7 @@ function MenuProvider(handle: Handle<MenuProviderProps, MenuContextValue>) {
     strategy = 'list',
     focus = strategy !== 'none',
   }: OpenMenuOptions = {}) {
-    if (state !== State.Idle) {
+    if (state !== 'idle') {
       return
     }
 
@@ -538,9 +529,9 @@ function MenuProvider(handle: Handle<MenuProviderProps, MenuContextValue>) {
     open = false
     if (animation === 'none') {
       activeId = null
-      state = State.Idle
-    } else if (wasOpen && state === State.Idle) {
-      state = State.Dismissing
+      state = 'idle'
+    } else if (wasOpen && state === 'idle') {
+      state = 'dismissing'
     }
     updates.push(handle.update())
   }
@@ -561,8 +552,8 @@ function MenuProvider(handle: Handle<MenuProviderProps, MenuContextValue>) {
       shouldUpdate = true
     }
 
-    if (state !== State.Idle) {
-      state = State.Idle
+    if (state !== 'idle') {
+      state = 'idle'
       shouldUpdate = true
     }
 
@@ -630,7 +621,7 @@ function MenuProvider(handle: Handle<MenuProviderProps, MenuContextValue>) {
   }
 
   function highlight(id: string | null, { focus = false }: HighlightOptions = {}) {
-    if (state !== State.Idle) {
+    if (state !== 'idle') {
       return
     }
 
@@ -673,7 +664,7 @@ function MenuProvider(handle: Handle<MenuProviderProps, MenuContextValue>) {
   }
 
   function navigate(strategy: NavigationStrategy) {
-    if (state !== State.Idle) {
+    if (state !== 'idle') {
       return
     }
 
@@ -682,22 +673,22 @@ function MenuProvider(handle: Handle<MenuProviderProps, MenuContextValue>) {
     let nextItem: RegisteredMenuItem | undefined
 
     switch (strategy) {
-      case NavigationStrategy.Next:
+      case 'next':
         nextItem =
           activeIndex === -1
             ? interactableItems[0]
             : (interactableItems[activeIndex + 1] ?? interactableItems[activeIndex])
         break
-      case NavigationStrategy.Previous:
+      case 'previous':
         nextItem =
           activeIndex === -1
             ? interactableItems[interactableItems.length - 1]
             : interactableItems[activeIndex - 1]
         break
-      case NavigationStrategy.First:
+      case 'first':
         nextItem = interactableItems[0]
         break
-      case NavigationStrategy.Last:
+      case 'last':
         nextItem = interactableItems[interactableItems.length - 1]
         break
     }
@@ -708,7 +699,7 @@ function MenuProvider(handle: Handle<MenuProviderProps, MenuContextValue>) {
   }
 
   function highlightSearchMatch(text: string) {
-    if (state !== State.Idle) {
+    if (state !== 'idle') {
       return
     }
 
@@ -727,7 +718,7 @@ function MenuProvider(handle: Handle<MenuProviderProps, MenuContextValue>) {
   }
 
   async function activateItem(id: string) {
-    if (state !== State.Idle) {
+    if (state !== 'idle') {
       return
     }
 
@@ -744,7 +735,7 @@ function MenuProvider(handle: Handle<MenuProviderProps, MenuContextValue>) {
     let committedChecked =
       item.type === 'checkbox' ? !item.checked : item.type === 'radio' ? true : undefined
 
-    state = State.Selecting
+    state = 'selecting'
     activeId = item.id
     flashState = item.type === 'item' ? { id: item.id } : { checked: committedChecked, id: item.id }
     let signal = await handle.update()
@@ -776,7 +767,7 @@ function MenuProvider(handle: Handle<MenuProviderProps, MenuContextValue>) {
 
     await closeAll()
 
-    state = State.Idle
+    state = 'idle'
     signal = await handle.update()
     if (signal.aborted) {
       return
@@ -792,7 +783,7 @@ function MenuProvider(handle: Handle<MenuProviderProps, MenuContextValue>) {
   }
 
   async function openActiveSubmenu() {
-    if (state !== State.Idle) {
+    if (state !== 'idle') {
       return
     }
 
@@ -1102,22 +1093,22 @@ const listMixin = createMixin<HTMLElement, [], ElementProps>((handle) => {
         case 'ArrowDown':
           event.preventDefault()
           event.stopPropagation()
-          context.navigate(NavigationStrategy.Next)
+          context.navigate('next')
           return
         case 'ArrowUp':
           event.preventDefault()
           event.stopPropagation()
-          context.navigate(NavigationStrategy.Previous)
+          context.navigate('previous')
           return
         case 'Home':
           event.preventDefault()
           event.stopPropagation()
-          context.navigate(NavigationStrategy.First)
+          context.navigate('first')
           return
         case 'End':
           event.preventDefault()
           event.stopPropagation()
-          context.navigate(NavigationStrategy.Last)
+          context.navigate('last')
           return
         case 'Enter':
         case ' ':
@@ -1312,7 +1303,7 @@ const submenuTriggerMixin = createMixin<
         'aria-disabled': options.disabled ? 'true' : undefined,
         'aria-expanded': childMenu.isOpen ? 'true' : 'false',
         'aria-haspopup': 'menu',
-        'data-submenu-state': childMenu.state === State.Idle ? undefined : childMenu.state,
+        'data-submenu-state': childMenu.state === 'idle' ? undefined : childMenu.state,
         'data-highlighted': parent.activeId === handle.id ? 'true' : undefined,
       }),
       ref((node: HTMLElement, signal) => {
@@ -1406,8 +1397,11 @@ const menu = {
   trigger,
 } as const
 
-export function onMenuSelect(handler: MenuSelectHandler, captureBoolean?: boolean) {
-  return on<HTMLElement, typeof MENU_SELECT_EVENT>(MENU_SELECT_EVENT, handler, captureBoolean)
+export function onMenuSelect<target extends HTMLElement>(
+  handler: MenuSelectHandler<target>,
+  captureBoolean?: boolean,
+) {
+  return on(MENU_SELECT_EVENT, handler, captureBoolean)
 }
 
 export interface MenuProps extends Omit<Props<'button'>, 'children'> {