@remix-run/ui 0.1.1 → 0.2.0

package/src/components/listbox/listbox.ts

@@ -4,7 +4,9 @@ import {
   css,
   on,
   type CSSMixinDescriptor,
+  type ElementProps,
   type Handle,
+  type MixinFactory,
   type RemixNode,
 } from '@remix-run/ui'
 import { theme } from '../../theme/theme.ts'
@@ -17,17 +19,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
@@ -158,9 +151,9 @@ export const optionStyle = itemCss
 export const glyphStyle = itemGlyphCss
 export const labelStyle = itemLabelCss
 
-function ListboxProvider(handle: Handle<ListboxProviderProps, ListboxContext>) {
+function ListboxProvider(handle: Handle<ListboxProviderProps, ListboxContext>): () => RemixNode {
   let options: RegisteredOption[] = []
-  let state = State.Idle
+  let state: State = 'idle'
 
   function getOption(value: ListboxValue) {
     return options.find((option) => option.value === value)
@@ -221,16 +214,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 +254,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 +272,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 +293,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 +302,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
       }
@@ -345,49 +338,51 @@ function ListboxProvider(handle: Handle<ListboxProviderProps, ListboxContext>) {
   }
 }
 
-const listMixin = createMixin<HTMLElement>((handle) => (props) => {
-  let context = handle.context.get(ListboxProvider)
-  return [
-    attrs({
-      tabIndex: props.tabIndex ?? -1,
-      role: props.role ?? 'listbox',
-    }),
-    on('focus', () => {
-      context.scrollActiveOptionIntoView()
-    }),
-    on('keydown', (event) => {
-      switch (event.key) {
-        case 'ArrowDown':
-          event.preventDefault()
-          context.navigate(NavigationStrategy.Next)
-          break
-        case 'ArrowUp':
-          event.preventDefault()
-          context.navigate(NavigationStrategy.Previous)
-          break
-        case 'Tab':
-          event.preventDefault()
-          context.navigate(NavigationStrategy.First)
-          break
-        case 'Enter':
-        case ' ':
-          event.preventDefault()
-          void context.select(context.activeValue)
-          break
-        case 'Home':
-          event.preventDefault()
-          context.navigate(NavigationStrategy.First)
-          break
-        case 'End':
-          event.preventDefault()
-          context.navigate(NavigationStrategy.Last)
-      }
-    }),
-    hiddenTypeahead((text) => {
-      context.highlightSearchMatch(text)
-    }),
-  ]
-})
+const listMixin: MixinFactory<HTMLElement, [], ElementProps> = createMixin<HTMLElement>(
+  (handle) => (props) => {
+    let context = handle.context.get(ListboxProvider)
+    return [
+      attrs({
+        tabIndex: props.tabIndex ?? -1,
+        role: props.role ?? 'listbox',
+      }),
+      on('focus', () => {
+        context.scrollActiveOptionIntoView()
+      }),
+      on('keydown', (event) => {
+        switch (event.key) {
+          case 'ArrowDown':
+            event.preventDefault()
+            context.navigate('next')
+            break
+          case 'ArrowUp':
+            event.preventDefault()
+            context.navigate('previous')
+            break
+          case 'Tab':
+            event.preventDefault()
+            context.navigate('first')
+            break
+          case 'Enter':
+          case ' ':
+            event.preventDefault()
+            void context.select(context.activeValue)
+            break
+          case 'Home':
+            event.preventDefault()
+            context.navigate('first')
+            break
+          case 'End':
+            event.preventDefault()
+            context.navigate('last')
+        }
+      }),
+      hiddenTypeahead((text) => {
+        context.highlightSearchMatch(text)
+      }),
+    ]
+  },
+)
 
 export interface ListboxOption {
   id: string
@@ -397,50 +392,51 @@ export interface ListboxOption {
   textValue?: SearchValue
 }
 
-const optionMixin = createMixin<HTMLElement, [option: Omit<ListboxOption, 'id'>]>((handle) => {
-  let optionRef: HTMLElement | undefined
+const optionMixin: MixinFactory<HTMLElement, [option: Omit<ListboxOption, 'id'>], ElementProps> =
+  createMixin<HTMLElement, [option: Omit<ListboxOption, 'id'>]>((handle) => {
+    let optionRef: HTMLElement | undefined
 
-  handle.queueTask((node) => {
-    optionRef = node
-  })
-
-  return (option) => {
-    let context = handle.context.get(ListboxProvider)
-    context.registerOption({
-      ...option,
-      id: handle.id,
-      get hidden() {
-        return optionRef?.hidden === true
-      },
-      get node() {
-        return optionRef as HTMLElement
-      },
+    handle.queueTask((node) => {
+      optionRef = node
     })
 
-    return [
-      attrs({
-        role: 'option',
+    return (option) => {
+      let context = handle.context.get(ListboxProvider)
+      context.registerOption({
+        ...option,
         id: handle.id,
-        'aria-selected': context.value === option.value ? 'true' : 'false',
-        'aria-disabled': option.disabled ? 'true' : 'false',
-        'data-highlighted': context.activeValue === option.value ? 'true' : 'false',
-      }),
-      !option.disabled && [
-        on('click', () => {
-          context.select(option.value)
-        }),
-        on('mousemove', () => {
-          if (context.activeValue === option.value) return
-          context.highlight(option.value)
+        get hidden() {
+          return optionRef?.hidden === true
+        },
+        get node() {
+          return optionRef as HTMLElement
+        },
+      })
+
+      return [
+        attrs({
+          role: 'option',
+          id: handle.id,
+          'aria-selected': context.value === option.value ? 'true' : 'false',
+          'aria-disabled': option.disabled ? 'true' : 'false',
+          'data-highlighted': context.activeValue === option.value ? 'true' : 'false',
         }),
-        on('mouseleave', () => {
-          if (context.activeValue !== option.value) return
-          context.highlight(null)
-        }),
-      ],
-    ]
-  }
-})
+        !option.disabled && [
+          on('click', () => {
+            context.select(option.value)
+          }),
+          on('mousemove', () => {
+            if (context.activeValue === option.value) return
+            context.highlight(option.value)
+          }),
+          on('mouseleave', () => {
+            if (context.activeValue !== option.value) return
+            context.highlight(null)
+          }),
+        ],
+      ]
+    }
+  })
 
 export const Context = ListboxProvider
 export const list = listMixin

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>
+  )
+}