@remix-run/ui 0.3.0 → 0.5.0

package/src/{components/menu → menu}/README.md

@@ -2,12 +2,13 @@
 
 `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
+## Component Usage
 
 ```tsx
 import type { Handle } from 'remix/ui'
-import { Menu, MenuItem, Submenu, onMenuSelect } from 'remix/ui/menu'
-import { separatorStyle } from 'remix/ui/separator'
+import { css } from 'remix/ui'
+import { Menu, MenuItem, Submenu } from 'remix/ui/menu'
+import { onMenuSelect } from 'remix/ui/menu/primitives'
 
 export function ViewMenu(handle: Handle) {
   let wordWrap = false
@@ -50,6 +51,12 @@ export function ViewMenu(handle: Handle) {
     </Menu>
   )
 }
+
+let separatorStyle = css({
+  border: 0,
+  borderBlockStart: '1px solid #e5e7eb',
+  marginBlock: '4px',
+})
 ```
 
 Use `label` or `searchValue` when the rendered item content is not the text that should be used for event labels or typeahead.
@@ -71,8 +78,8 @@ Use `menuLabel` when the menu surface needs a different accessible label from th
 Use `menu.contextTrigger()` with `menu.Context` and `MenuList` when a menu should open at the right-click location of an element.
 
 ```tsx
-import * as menu from 'remix/ui/menu'
 import { MenuItem, MenuList } from 'remix/ui/menu'
+import * as menu from 'remix/ui/menu/primitives'
 
 export function FileContextMenu(handle: Handle) {
   return () => (
@@ -89,20 +96,54 @@ export function FileContextMenu(handle: Handle) {
 }
 ```
 
-Attach `onMenuSelect(...)` to `MenuList` or a shared ancestor when using lower-level context menu composition.
+Attach `onMenuSelect(...)` from `remix/ui/menu/primitives` to `MenuList` or a shared ancestor when using lower-level context menu composition.
+
+## Primitive Usage
+
+Use only the lower-level primitives when app code owns the trigger, surface, and item markup:
+
+```tsx
+import * as menu from 'remix/ui/menu/primitives'
+import { itemStyle, listStyle, popoverStyle, triggerStyle } from './menu.styles'
+
+export function PrimitiveMenu() {
+  return (
+    <menu.Context label="Project actions">
+      <button mix={[triggerStyle, menu.trigger()]} type="button">
+        Actions
+      </button>
+      <div mix={[popoverStyle, menu.popover()]}>
+        <div mix={[listStyle, menu.list()]}>
+          <div mix={[itemStyle, menu.item({ name: 'rename' })]}>Rename</div>
+          <div mix={[itemStyle, menu.item({ disabled: true, name: 'archive' })]}>Archive</div>
+        </div>
+      </div>
+    </menu.Context>
+  )
+}
+```
 
-## `menu.*`
+## `remix/ui/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.
+- `MenuItem`: menu item component. Supports regular, checkbox, and radio item roles through `type`, `checked`, `name`, `value`, `label`, `disabled`, and `searchValue`.
+- `Submenu`: nested menu component with its own trigger and child menu surface.
+- `MenuList`: lower-level styled list component for custom composition inside `menu.Context`.
+- `buttonStyle`, `popoverStyle`, `listStyle`, `itemStyle`, `itemSlotStyle`, `itemLabelStyle`, `itemIndicatorStyle`, and `triggerIndicatorStyle`: flat style mixins used by the component markup.
+- `MenuProps`, `MenuItemProps`, `MenuListProps`, and `SubmenuProps`: public TypeScript props for the composed APIs.
+
+## `remix/ui/menu/primitives`
+
+- `Context`: lower-level provider for custom menu composition.
+- `trigger()`: wires a button-style trigger to open the root menu.
+- `contextTrigger()`: opens the root menu from a `contextmenu` event at pointer coordinates, or from keyboard context-menu shortcuts.
+- `popover()`: wires the menu popover surface.
+- `list()`: wires the menu list root, focus handling, keyboard navigation, and typeahead.
+- `item(...)`: registers one menu item. Supports regular, checkbox, and radio roles through `type`, `checked`, `name`, `value`, `label`, `disabled`, and `searchValue`.
+- `submenuTrigger(...)`: registers a menu item that opens a child menu.
 - `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.contextTrigger()`, `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`, `MenuContextTriggerOptions`, `MenuItemOptions`, and `SubmenuProps`: public TypeScript props and option types.
+- `MenuSelectEvent`: bubbling event whose `item` describes the selected item.
+- `MenuSelectItem`, `MenuProviderProps`, `MenuTriggerOptions`, `MenuContextTriggerOptions`, `MenuItemOptions`, and `SubmenuTriggerOptions`: public TypeScript event, prop, and option types for the primitives.
 
 ## Behavior Notes
 

package/src/menu/index.tsx

@@ -0,0 +1,354 @@
+import { createElement, css, ref } from '@remix-run/ui'
+import type { CSSMixinDescriptor, Handle, Props, RemixNode } from '@remix-run/ui'
+
+import button from '@remix-run/ui/button'
+import * as menu from '@remix-run/ui/menu/primitives'
+import type { SearchValue } from '../shared/typeahead.ts'
+import { CheckIcon, ChevronDownIcon, ChevronRightIcon } from '../shared/icons.tsx'
+import { popoverSurfaceStyle } from '../shared/listbox-popover-styles.ts'
+import { componentStyleValues as styles } from '../shared/style-values.ts'
+
+const menuButtonCss: CSSMixinDescriptor = css({
+  display: 'grid',
+  gridTemplateColumns: 'minmax(0, 1fr) auto',
+  alignItems: 'center',
+  borderRadius: styles.radius.md,
+  paddingInlineEnd: styles.space.sm,
+  textAlign: 'left',
+  '&[aria-expanded="true"], &[aria-expanded="true"]:hover, &[aria-expanded="true"]:focus-visible': {
+    backgroundColor: styles.surface.lvl3,
+    color: styles.colors.text.primary,
+  },
+})
+
+const menuButtonLabelCss: CSSMixinDescriptor = css({
+  display: 'inline-flex',
+  alignItems: 'center',
+  minWidth: 0,
+})
+
+const menuButtonIconCss: CSSMixinDescriptor = css({
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  width: styles.fontSize.md,
+  height: styles.fontSize.md,
+  color: 'currentColor',
+  flexShrink: 0,
+  '& > svg': {
+    display: 'block',
+    width: '100%',
+    height: '100%',
+  },
+})
+
+const menuPopoverCss: CSSMixinDescriptor = css({
+  '&[data-menu-submenu="true"][data-anchor-placement^="right"]': {
+    marginLeft: `calc(${styles.space.xs} * -1)`,
+  },
+  '&[data-menu-submenu="true"][data-anchor-placement^="left"]': {
+    marginLeft: styles.space.xs,
+  },
+  '&[data-close-animation="none"]:not(:popover-open)': {
+    transition: 'none',
+    transitionBehavior: 'normal',
+  },
+})
+
+const menuListCss: CSSMixinDescriptor = css({
+  display: 'flex',
+  flexDirection: 'column',
+  flex: '1 1 auto',
+  minHeight: 0,
+  paddingBlock: styles.space.xs,
+  paddingInline: styles.space.none,
+  overflow: 'auto',
+  overscrollBehavior: 'contain',
+  outline: 'none',
+  userSelect: 'none',
+  WebkitUserSelect: 'none',
+  '--rmx-ui-item-inset': `calc(${styles.space.sm} + ${styles.space.xs})`,
+  '--rmx-ui-item-indicator-gap': 'var(--rmx-menu-item-slot-gap)',
+  '--rmx-ui-item-indicator-width': 'var(--rmx-menu-item-slot-width)',
+  '--rmx-menu-item-slot-gap': styles.space.none,
+  '--rmx-menu-item-slot-width': styles.space.none,
+  '&:has(> [role="menuitemcheckbox"])': {
+    '--rmx-menu-item-slot-gap': styles.space.xs,
+    '--rmx-menu-item-slot-width': styles.fontSize.md,
+  },
+  '&:has(> [role="menuitemradio"])': {
+    '--rmx-menu-item-slot-gap': styles.space.xs,
+    '--rmx-menu-item-slot-width': styles.fontSize.md,
+  },
+})
+
+const menuItemCss: CSSMixinDescriptor = css({
+  display: 'flex',
+  alignItems: 'center',
+  width: '100%',
+  minWidth: 0,
+  minHeight: styles.control.height.md,
+  boxSizing: 'border-box',
+  position: 'relative',
+  isolation: 'isolate',
+  paddingInline: `calc(${styles.space.sm} + ${styles.space.xs})`,
+  color: styles.colors.text.primary,
+  fontFamily: styles.fontFamily.sans,
+  fontSize: styles.fontSize.sm,
+  fontWeight: styles.fontWeight.normal,
+  lineHeight: styles.lineHeight.normal,
+  textAlign: 'left',
+  userSelect: 'none',
+  WebkitUserSelect: 'none',
+  '--rmx-menu-item-indicator-opacity': '0',
+  '&::before': {
+    content: '""',
+    position: 'absolute',
+    insetBlock: 0,
+    insetInline: styles.space.xs,
+    borderRadius: styles.radius.md,
+    backgroundColor: 'transparent',
+    pointerEvents: 'none',
+    zIndex: -1,
+  },
+  '&:focus': {
+    outline: 'none',
+  },
+  '&[data-highlighted="true"]': {
+    color: styles.colors.action.primary.foreground,
+  },
+  '&[data-highlighted="true"]::before': {
+    backgroundColor: styles.colors.action.primary.background,
+  },
+  '&[aria-haspopup="menu"][aria-expanded="true"]:not(:focus)': {
+    color: styles.colors.text.primary,
+  },
+  '&[aria-haspopup="menu"][aria-expanded="true"]:not(:focus)::before': {
+    backgroundColor: styles.surface.lvl2,
+  },
+  '&[data-submenu-state="selecting"], &[data-submenu-state="dismissing"]': {
+    color: styles.colors.text.primary,
+  },
+  '&[data-submenu-state="selecting"]::before, &[data-submenu-state="dismissing"]::before': {
+    backgroundColor: styles.surface.lvl2,
+  },
+  '&[data-menu-flash="true"]': {
+    color: styles.colors.text.primary,
+  },
+  '&[data-menu-flash="true"]::before': {
+    backgroundColor: 'transparent',
+  },
+  '&[aria-disabled="true"]': {
+    opacity: 0.5,
+  },
+  '&[aria-checked="true"], &[aria-selected="true"]': {
+    '--rmx-menu-item-indicator-opacity': '1',
+  },
+})
+
+const menuItemSlotCss: CSSMixinDescriptor = css({
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  flex: '0 0 var(--rmx-menu-item-slot-width)',
+  width: 'var(--rmx-menu-item-slot-width)',
+  minWidth: 0,
+  marginInlineEnd: 'var(--rmx-menu-item-slot-gap)',
+  overflow: 'hidden',
+})
+
+const menuItemLabelCss: CSSMixinDescriptor = css({
+  display: 'inline-flex',
+  alignItems: 'center',
+  flex: '1 1 auto',
+  minWidth: 0,
+})
+
+const menuItemIndicatorCss: CSSMixinDescriptor = css({
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  width: styles.fontSize.md,
+  height: styles.fontSize.md,
+  color: 'currentColor',
+  flexShrink: 0,
+  '& > svg': {
+    display: 'block',
+    width: '100%',
+    height: '100%',
+  },
+  opacity: 'var(--rmx-menu-item-indicator-opacity)',
+})
+
+const menuTriggerIndicatorCss: CSSMixinDescriptor = css({
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  width: styles.fontSize.md,
+  height: styles.fontSize.md,
+  color: 'currentColor',
+  flexShrink: 0,
+  marginInlineStart: 'auto',
+  '& > svg': {
+    display: 'block',
+    width: '100%',
+    height: '100%',
+  },
+})
+
+export const buttonStyle = menuButtonCss
+export const popoverStyle = menuPopoverCss
+export const listStyle = menuListCss
+export const itemStyle = menuItemCss
+export const itemSlotStyle = menuItemSlotCss
+export const itemLabelStyle = menuItemLabelCss
+export const itemIndicatorStyle = menuItemIndicatorCss
+export const triggerIndicatorStyle = menuTriggerIndicatorCss
+
+export interface MenuListProps extends Props<'div'> {}
+
+type MenuListChildProps = Omit<
+  JSX.LibraryManagedAttributes<typeof MenuList, MenuListProps>,
+  'children'
+>
+
+export interface MenuProps extends Omit<Props<'button'>, 'children'> {
+  children?: RemixNode
+  label: RemixNode
+  menuLabel?: string
+}
+
+export interface MenuItemProps extends Omit<Props<'div'>, 'children' | 'name' | 'type' | 'value'> {
+  checked?: boolean
+  children?: RemixNode
+  disabled?: boolean
+  label?: string
+  name: string
+  searchValue?: SearchValue
+  type?: 'checkbox' | 'radio'
+  value?: string
+}
+
+export interface SubmenuProps extends Omit<Props<'div'>, 'children' | 'name' | 'type' | 'value'> {
+  children?: RemixNode
+  disabled?: boolean
+  label: RemixNode
+  listProps?: MenuListChildProps
+  menuLabel?: string
+  searchValue?: SearchValue
+  value?: string
+}
+
+export function Menu(handle: Handle<MenuProps>): () => RemixNode {
+  let buttonRef: HTMLButtonElement | undefined
+
+  return () => {
+    let { children, label, menuLabel, mix, type, ...buttonProps } = handle.props
+
+    return (
+      <menu.Context label={menuLabel}>
+        <button
+          {...buttonProps}
+          type={type ?? 'button'}
+          mix={[
+            button(),
+            buttonStyle,
+            menu.trigger(),
+            ref((node: HTMLButtonElement, signal) => {
+              buttonRef = node
+              signal.addEventListener('abort', () => {
+                if (buttonRef === node) {
+                  buttonRef = undefined
+                }
+              })
+            }),
+            mix,
+          ]}
+        >
+          <span mix={menuButtonLabelCss}>{label}</span>
+          <ChevronDownIcon mix={menuButtonIconCss} />
+        </button>
+        <MenuList
+          mix={menu.onMenuSelect((event) => {
+            if (!buttonRef) {
+              return
+            }
+
+            event.stopPropagation()
+            buttonRef.dispatchEvent(new menu.MenuSelectEvent(event.item))
+          })}
+        >
+          {children}
+        </MenuList>
+      </menu.Context>
+    )
+  }
+}
+
+export function MenuList(handle: Handle<MenuListProps>): () => RemixNode {
+  return () => {
+    let { children, mix, ...divProps } = handle.props
+
+    return (
+      <div mix={[popoverSurfaceStyle, popoverStyle, menu.popover()]}>
+        <div {...divProps} mix={[listStyle, menu.list(), mix]}>
+          {children}
+        </div>
+      </div>
+    )
+  }
+}
+
+export function MenuItem(handle: Handle<MenuItemProps>): () => RemixNode {
+  return () => {
+    let { checked, children, disabled, label, mix, name, searchValue, type, value, ...divProps } =
+      handle.props
+
+    return (
+      <div
+        {...divProps}
+        mix={[
+          itemStyle,
+          menu.item({ checked, disabled, label, name, searchValue, type, value }),
+          mix,
+        ]}
+      >
+        <span mix={itemSlotStyle}>
+          <CheckIcon mix={itemIndicatorStyle} />
+        </span>
+        <span mix={itemLabelStyle}>{children ?? label}</span>
+      </div>
+    )
+  }
+}
+
+export function Submenu(handle: Handle<SubmenuProps>): () => RemixNode {
+  return () => {
+    let { children, disabled, label, listProps, menuLabel, mix, searchValue, value, ...divProps } =
+      handle.props
+
+    return (
+      <menu.Context label={menuLabel}>
+        <div
+          {...divProps}
+          mix={[
+            itemStyle,
+            menu.submenuTrigger({
+              disabled,
+              searchValue,
+              value,
+            }),
+            mix,
+          ]}
+        >
+          <span mix={itemSlotStyle}>
+            <CheckIcon mix={itemIndicatorStyle} />
+          </span>
+          <span mix={itemLabelStyle}>{label}</span>
+          <ChevronRightIcon mix={triggerIndicatorStyle} />
+        </div>
+        <MenuList {...listProps}>{children}</MenuList>
+      </menu.Context>
+    )
+  }
+}