@proteos/ui 0.31.0

package/src/components/input/input.tsx

@@ -0,0 +1,76 @@
+import type { ReactNode } from 'react'
+import {
+  Input as AriaInput,
+  type InputProps as AriaInputProps,
+  type TextFieldProps as AriaTextFieldProps,
+  FieldError,
+  Label,
+  Text,
+  TextField,
+} from 'react-aria-components'
+import { cn } from '../../lib/cn'
+import {
+  type FieldAppearance,
+  fieldControlStyles,
+  fieldErrorStyles,
+  type FieldSize,
+  fieldHintStyles,
+  fieldLabelStyles,
+} from '../field/field'
+
+export type InputProps = AriaTextFieldProps & {
+  label?: ReactNode
+  description?: ReactNode
+  errorMessage?: ReactNode
+  placeholder?: string
+  /** Field size. Defaults to `md`. Use `sm` for compact rows (filter builder, toolbars). */
+  size?: FieldSize
+  /** Chrome variant. Defaults to `field`. `cell` flattens the box for
+   *  spreadsheet-style inline editing (2px radius, no halo / resting shadow). */
+  appearance?: FieldAppearance
+  /** Extra props forwarded to the underlying <input>. */
+  inputProps?: Omit<AriaInputProps, 'className'>
+  /** Visual override for the input control only. */
+  inputClassName?: string
+}
+
+export function Input({
+  label,
+  description,
+  errorMessage,
+  placeholder,
+  size,
+  appearance,
+  inputProps,
+  inputClassName,
+  className,
+  ...props
+}: InputProps) {
+  const styles = fieldControlStyles({ size, appearance })
+  return (
+    <TextField
+      {...props}
+      className={(renderProps) =>
+        cn(
+          'grid grid-cols-1 gap-1.5',
+          typeof className === 'function' ? className(renderProps) : className,
+        )
+      }
+    >
+      {label ? <Label className={fieldLabelStyles}>{label}</Label> : null}
+      <AriaInput
+        {...inputProps}
+        placeholder={placeholder ?? ''}
+        className={cn(styles.box(), styles.content(), inputClassName)}
+      />
+      {description ? (
+        <Text slot="description" className={fieldHintStyles}>
+          {description}
+        </Text>
+      ) : null}
+      {errorMessage && appearance !== 'cell' ? (
+        <FieldError className={fieldErrorStyles}>{errorMessage}</FieldError>
+      ) : null}
+    </TextField>
+  )
+}

package/src/components/kbd/index.ts

@@ -0,0 +1,2 @@
+export type { KbdProps } from './kbd'
+export { Kbd } from './kbd'

package/src/components/kbd/kbd.stories.tsx

@@ -0,0 +1,34 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { Kbd } from './kbd'
+
+const meta: Meta<typeof Kbd> = {
+  title: 'Components/Kbd',
+  component: Kbd,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof Kbd>
+
+export const Playground: Story = { args: { children: '⌘K' } }
+
+export const Inline: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <p className="text-sm text-ink-3">
+      Press <Kbd>⌘</Kbd> + <Kbd>K</Kbd> to open the command palette.
+    </p>
+  ),
+}
+
+export const Sequence: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="flex items-center gap-1.5">
+      <Kbd>⌘</Kbd>
+      <Kbd>⇧</Kbd>
+      <Kbd>P</Kbd>
+    </div>
+  ),
+}

package/src/components/kbd/kbd.tsx

@@ -0,0 +1,27 @@
+import type { HTMLAttributes } from 'react'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   Kbd — small mono key-cap. Renders a real <kbd> element so screen readers
+   announce it as keyboard input. Pure cosmetics; no behavior.
+   ========================================================================= */
+
+export type KbdProps = HTMLAttributes<HTMLElement>
+
+export function Kbd({ className, children, ...props }: KbdProps) {
+  return (
+    <kbd
+      {...props}
+      className={cn(
+        'inline-flex items-center justify-center',
+        'font-mono text-[10.5px] leading-none text-ink-4',
+        'bg-surface-2 border border-rule rounded-[4px]',
+        'px-1.5 py-1',
+        className,
+      )}
+    >
+      {children}
+    </kbd>
+  )
+}

package/src/components/menu/index.ts

@@ -0,0 +1,2 @@
+export type { MenuItemProps, MenuPopoverProps, MenuProps } from './menu'
+export { Menu, MenuItem, MenuPopover, MenuTrigger, SubmenuTrigger } from './menu'

package/src/components/menu/menu.tsx

@@ -0,0 +1,121 @@
+import type { ReactNode } from 'react'
+import { ChevronRight } from 'lucide-react'
+import {
+  Menu as AriaMenu,
+  MenuItem as AriaMenuItem,
+  type MenuItemProps as AriaMenuItemProps,
+  type MenuProps as AriaMenuProps,
+  MenuTrigger as AriaMenuTrigger,
+  Popover as AriaPopover,
+  type PopoverProps as AriaPopoverProps,
+  SubmenuTrigger as AriaSubmenuTrigger,
+} from 'react-aria-components'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   Menu — a dropdown menu with Windows-style cascading submenus, built on
+   React Aria Components (keyboard nav, focus, typeahead, ARIA handled by RAC).
+
+     <MenuTrigger>
+       <Button>Open</Button>              // first child = the trigger
+       <MenuPopover>
+         <Menu>
+           <MenuItem onAction={…}>Edit</MenuItem>
+           <SubmenuTrigger>
+             <MenuItem hasSubmenu>More…</MenuItem>   // the parent row
+             <MenuPopover placement="end top">       // the flyout
+               <Menu>
+                 <MenuItem onAction={…}>Nested</MenuItem>
+               </Menu>
+             </MenuPopover>
+           </SubmenuTrigger>
+         </Menu>
+       </MenuPopover>
+     </MenuTrigger>
+
+   MenuTrigger / SubmenuTrigger are RAC primitives re-exported unchanged;
+   MenuPopover / Menu / MenuItem carry the design-system chrome.
+   ========================================================================= */
+
+/** Stateful root (RAC). Wraps the trigger element + the MenuPopover. */
+export const MenuTrigger = AriaMenuTrigger
+
+/**
+ * Submenu wrapper (RAC). Wraps a parent MenuItem and the nested MenuPopover so
+ * the flyout opens on hover/right-arrow. Use `placement="end top"` on the nested
+ * MenuPopover so it cascades to the side, Windows-style.
+ */
+export const SubmenuTrigger = AriaSubmenuTrigger
+
+export type MenuPopoverProps = AriaPopoverProps
+
+/** The floating panel. Defaults to opening below-start; pass `placement="end top"` for a submenu flyout. */
+export function MenuPopover({ className, offset = 4, placement = 'bottom start', ...props }: MenuPopoverProps) {
+  return (
+    <AriaPopover
+      offset={offset}
+      placement={placement}
+      {...props}
+      className={(renderProps) =>
+        cn(
+          'min-w-[200px] p-1 bg-surface border border-rule rounded-md',
+          'shadow-[var(--shadow-float)] outline-none z-[1200]',
+          'entering:animate-in entering:fade-in-0 entering:zoom-in-95',
+          'exiting:animate-out exiting:fade-out-0 exiting:zoom-out-95',
+          typeof className === 'function' ? className(renderProps) : className,
+        )
+      }
+    />
+  )
+}
+
+export type MenuProps<T extends object> = AriaMenuProps<T>
+
+/** The menu list. Holds MenuItem / SubmenuTrigger children. */
+export function Menu<T extends object>({ className, ...props }: MenuProps<T>) {
+  return (
+    <AriaMenu
+      {...props}
+      className={(renderProps) =>
+        cn(
+          'flex flex-col gap-px outline-none',
+          typeof className === 'function' ? className(renderProps) : className,
+        )
+      }
+    />
+  )
+}
+
+export type MenuItemProps = Omit<AriaMenuItemProps, 'children'> & {
+  /** Leading icon slot. */
+  icon?: ReactNode
+  /** Renders a trailing chevron marking this row as a submenu parent. */
+  hasSubmenu?: boolean
+  children?: ReactNode
+}
+
+const menuItemStyles = cn(
+  'flex items-center gap-2.5 px-2.5 py-1.5 rounded-md cursor-pointer outline-none',
+  'font-sans text-[13px] text-ink-2 select-none',
+  'hover:bg-surface-2 hover:text-ink focus:bg-surface-2 focus:text-ink',
+  'data-[open]:bg-surface-2 data-[open]:text-ink', // submenu-parent stays lit while its flyout is open
+  'aria-disabled:opacity-50 aria-disabled:cursor-default aria-disabled:hover:bg-transparent aria-disabled:hover:text-ink-2',
+  '[&_svg]:size-3.5 [&_svg]:text-ink-3 hover:[&_svg]:text-ink focus:[&_svg]:text-ink',
+)
+
+/** A single menu row. Pass `onAction` to handle selection; `isDisabled` to dim it. */
+export function MenuItem({ icon, hasSubmenu, children, className, ...props }: MenuItemProps) {
+  return (
+    <AriaMenuItem
+      {...props}
+      className={(renderProps) =>
+        cn(menuItemStyles, typeof className === 'function' ? className(renderProps) : className)
+      }
+    >
+      {icon ? <span className="flex shrink-0 items-center">{icon}</span> : null}
+      <span className="flex-1 truncate">{children}</span>
+      {hasSubmenu ? <ChevronRight className="ml-2 size-3 shrink-0 text-ink-4" /> : null}
+    </AriaMenuItem>
+  )
+}

package/src/components/modal/index.ts

@@ -0,0 +1,10 @@
+export type { ModalContentProps } from './modal'
+export {
+  Modal,
+  ModalBody,
+  ModalContent,
+  ModalDescription,
+  ModalFooter,
+  ModalHeader,
+  ModalTitle,
+} from './modal'

package/src/components/modal/modal.stories.tsx

@@ -0,0 +1,153 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { Button } from '@/components/button/button'
+import { Input } from '@/components/input/input'
+import { Separator } from '@/components/separator/separator'
+
+import {
+  Modal,
+  ModalBody,
+  ModalContent,
+  ModalDescription,
+  ModalFooter,
+  ModalHeader,
+  ModalTitle,
+} from './modal'
+
+const meta: Meta<typeof Modal> = {
+  title: 'Components/Modal',
+  component: Modal,
+  tags: ['autodocs'],
+  parameters: {
+    // Modal portals its content. `layout: "padded"` gives the trigger some
+    // breathing room in the story frame.
+    layout: 'padded',
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof Modal>
+
+/* =========================================================================
+   Basic — trigger opens a modal with title, description, body, and actions.
+   ========================================================================= */
+
+export const Basic: Story = {
+  render: () => (
+    <Modal>
+      <Button>Open modal</Button>
+      <ModalContent>
+        <ModalHeader>
+          <ModalTitle>Compose system</ModalTitle>
+          <ModalDescription>
+            Describe your business in plain language. Proteos will infer entities, workflows and
+            reports.
+          </ModalDescription>
+        </ModalHeader>
+        <ModalBody>
+          A mid-size freight broker. Quotes, loads, carriers, lanes. Dispatchers assign drivers
+          daily; finance reconciles invoices weekly.
+        </ModalBody>
+        <Separator />
+        <ModalFooter>
+          <Button slot="close" variant="ghost">
+            Cancel
+          </Button>
+          <Button variant="accent">Compose</Button>
+        </ModalFooter>
+      </ModalContent>
+    </Modal>
+  ),
+}
+
+/* =========================================================================
+   Confirmation — compact modal for destructive / binary choices.
+   ========================================================================= */
+
+export const Confirmation: Story = {
+  render: () => (
+    <Modal>
+      <Button variant="secondary">Delete shipment</Button>
+      <ModalContent modalClassName="max-w-md">
+        <ModalHeader>
+          <ModalTitle>Delete SH-10482?</ModalTitle>
+          <ModalDescription>
+            This removes the shipment and all related events. You can't undo this.
+          </ModalDescription>
+        </ModalHeader>
+        <Separator />
+        <ModalFooter>
+          <Button slot="close" variant="ghost">
+            Keep it
+          </Button>
+          <Button slot="close" variant="primary">
+            Delete
+          </Button>
+        </ModalFooter>
+      </ModalContent>
+    </Modal>
+  ),
+}
+
+/* =========================================================================
+   With form — a Proteos-style input lives inside ModalBody.
+   ========================================================================= */
+
+export const WithForm: Story = {
+  render: () => (
+    <Modal>
+      <Button>New carrier</Button>
+      <ModalContent>
+        <ModalHeader>
+          <ModalTitle>Add carrier</ModalTitle>
+          <ModalDescription>Link a new carrier to your dispatch board.</ModalDescription>
+        </ModalHeader>
+        <ModalBody>
+          <Input label="Carrier name" placeholder="Blue Ridge Logistics" />
+          <Input label="DOT number" placeholder="USDOT 1234567" />
+          <Input
+            label="Rate per mile"
+            description="In USD. Proteos will use this for margin estimates."
+            placeholder="$2.85"
+          />
+        </ModalBody>
+        <Separator />
+        <ModalFooter>
+          <Button slot="close" variant="ghost">
+            Cancel
+          </Button>
+          <Button variant="accent">Save carrier</Button>
+        </ModalFooter>
+      </ModalContent>
+    </Modal>
+  ),
+}
+
+/* =========================================================================
+   Not dismissable — backdrop click and Escape are disabled.
+   ========================================================================= */
+
+export const NotDismissable: Story = {
+  render: () => (
+    <Modal>
+      <Button>Open (must click an action)</Button>
+      <ModalContent isDismissable={false}>
+        <ModalHeader>
+          <ModalTitle>Accept terms</ModalTitle>
+          <ModalDescription>
+            You can't back out of this dialog — one of the actions below is required.
+          </ModalDescription>
+        </ModalHeader>
+        <Separator />
+        <ModalFooter>
+          <Button slot="close" variant="ghost">
+            Decline
+          </Button>
+          <Button slot="close" variant="primary">
+            Accept
+          </Button>
+        </ModalFooter>
+      </ModalContent>
+    </Modal>
+  ),
+}

package/src/components/modal/modal.test.tsx

@@ -0,0 +1,93 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+
+import { Button } from '@/components/button/button'
+
+import {
+  Modal,
+  ModalBody,
+  ModalContent,
+  ModalDescription,
+  ModalFooter,
+  ModalHeader,
+  ModalTitle,
+} from './modal'
+
+function Harness({ onOpenChange }: { onOpenChange?: (isOpen: boolean) => void }) {
+  return (
+    <Modal {...(onOpenChange ? { onOpenChange } : {})}>
+      <Button>Open</Button>
+      <ModalContent>
+        <ModalHeader>
+          <ModalTitle>Compose system</ModalTitle>
+          <ModalDescription>Describe your business in plain language.</ModalDescription>
+        </ModalHeader>
+        <ModalBody>Body content</ModalBody>
+        <ModalFooter>
+          <Button slot="close" variant="ghost">
+            Cancel
+          </Button>
+          <Button>Compose</Button>
+        </ModalFooter>
+      </ModalContent>
+    </Modal>
+  )
+}
+
+describe('Modal', () => {
+  it('stays closed by default', () => {
+    render(<Harness />)
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+  })
+
+  it('opens when the trigger is clicked', async () => {
+    const user = userEvent.setup()
+    render(<Harness />)
+
+    await user.click(screen.getByRole('button', { name: 'Open' }))
+    expect(await screen.findByRole('dialog')).toBeInTheDocument()
+  })
+
+  it('wires aria-labelledby to the ModalTitle', async () => {
+    const user = userEvent.setup()
+    render(<Harness />)
+
+    await user.click(screen.getByRole('button', { name: 'Open' }))
+    const dialog = await screen.findByRole('dialog', { name: 'Compose system' })
+    expect(dialog).toBeInTheDocument()
+  })
+
+  it('closes on Escape', async () => {
+    const user = userEvent.setup()
+    const onOpenChange = vi.fn()
+    render(<Harness onOpenChange={onOpenChange} />)
+
+    await user.click(screen.getByRole('button', { name: 'Open' }))
+    expect(await screen.findByRole('dialog')).toBeInTheDocument()
+
+    await user.keyboard('{Escape}')
+    expect(onOpenChange).toHaveBeenCalledWith(false)
+  })
+
+  it('closes when a Button with slot="close" is pressed', async () => {
+    const user = userEvent.setup()
+    const onOpenChange = vi.fn()
+    render(<Harness onOpenChange={onOpenChange} />)
+
+    await user.click(screen.getByRole('button', { name: 'Open' }))
+    await screen.findByRole('dialog')
+
+    await user.click(screen.getByRole('button', { name: 'Cancel' }))
+    expect(onOpenChange).toHaveBeenLastCalledWith(false)
+  })
+
+  it('renders description and body content', async () => {
+    const user = userEvent.setup()
+    render(<Harness />)
+
+    await user.click(screen.getByRole('button', { name: 'Open' }))
+    expect(await screen.findByText('Describe your business in plain language.')).toBeInTheDocument()
+    expect(screen.getByText('Body content')).toBeInTheDocument()
+  })
+})

package/src/components/modal/modal.tsx

@@ -0,0 +1,149 @@
+import type { HTMLAttributes } from 'react'
+import {
+  Dialog as AriaDialog,
+  type DialogProps as AriaDialogProps,
+  DialogTrigger as AriaDialogTrigger,
+  type DialogTriggerProps as AriaDialogTriggerProps,
+  Modal as AriaModal,
+  ModalOverlay as AriaModalOverlay,
+  type ModalOverlayProps as AriaModalOverlayProps,
+  Heading,
+  type HeadingProps,
+} from 'react-aria-components'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   Modal — shadcn-shaped API over RAC's DialogTrigger + ModalOverlay + Modal
+   + Dialog primitives. Composition mirrors:
+
+     <Modal>                           // stateful root (uncontrolled or controlled)
+       <Button>Open</Button>           // first child = trigger
+       <ModalContent>                  // portaled overlay + panel
+         <ModalHeader>
+           <ModalTitle>…</ModalTitle>  // auto-wires aria-labelledby
+           <ModalDescription>…</ModalDescription>
+         </ModalHeader>
+         <ModalBody>…</ModalBody>
+         <ModalFooter>
+           <Button slot="close" variant="ghost">Cancel</Button>
+           <Button>Confirm</Button>
+         </ModalFooter>
+       </ModalContent>
+     </Modal>
+   ========================================================================= */
+
+/** Stateful root. Pass `isOpen` + `onOpenChange` for controlled usage. */
+export function Modal(props: AriaDialogTriggerProps) {
+  return <AriaDialogTrigger {...props} />
+}
+
+export type ModalContentProps = AriaModalOverlayProps & {
+  /** Disable backdrop click to close. Default: backdrop closes. */
+  isDismissable?: boolean
+  /** Children of the Dialog element. Supports render-prop form `({ close }) => …`. */
+  children: AriaDialogProps['children']
+  /** Visual override for the panel wrapper (affects width, padding, etc.). */
+  modalClassName?: string
+}
+
+/**
+ * Portaled overlay + floating panel + dialog role. Backdrop darkens the page
+ * with a warm ink tint; panel uses vellum bg + rule border + the float shadow.
+ */
+export function ModalContent({
+  children,
+  className,
+  modalClassName,
+  isDismissable = true,
+  ...props
+}: ModalContentProps) {
+  return (
+    <AriaModalOverlay
+      isDismissable={isDismissable}
+      {...props}
+      className={(renderProps) =>
+        cn(
+          'fixed inset-0 z-50 flex items-center justify-center p-4',
+          // Warm ink scrim — stays in the Proteos palette (no pure black).
+          'bg-[color-mix(in_oklab,var(--color-ink)_40%,transparent)]',
+          'entering:animate-in entering:fade-in-0 entering:duration-150',
+          'exiting:animate-out exiting:fade-out-0 exiting:duration-100',
+          typeof className === 'function' ? className(renderProps) : className,
+        )
+      }
+    >
+      <AriaModal
+        className={cn(
+          'w-full max-w-lg',
+          // Cap the panel at the viewport (minus the overlay's p-4) and lay it
+          // out as a column so a tall body scrolls instead of overflowing the
+          // screen. Short modals are unaffected — height still tracks content.
+          'flex flex-col max-h-[calc(100dvh-2rem)]',
+          'bg-surface border border-rule rounded-lg',
+          'shadow-[var(--shadow-float)]',
+          'entering:animate-in entering:zoom-in-95 entering:slide-in-from-top-2 entering:duration-150',
+          'exiting:animate-out exiting:zoom-out-95 exiting:duration-100',
+          modalClassName,
+        )}
+      >
+        <AriaDialog className="outline-none flex flex-col min-h-0 overflow-hidden">
+          {children}
+        </AriaDialog>
+      </AriaModal>
+    </AriaModalOverlay>
+  )
+}
+
+/* ---------- slots (each owns its padding, like Card) ----------------------- */
+
+/** Padded top block. Contains `<ModalTitle>` and optionally `<ModalDescription>`. */
+export function ModalHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div {...props} className={cn('shrink-0 px-5 pt-5 pb-3 flex flex-col gap-1.5', className)} />
+}
+
+/** The modal's accessible name. Uses RAC `<Heading slot="title">` so the
+ *  Dialog's `aria-labelledby` points here automatically. */
+export function ModalTitle({ className, ...props }: Omit<HeadingProps, 'slot'>) {
+  return (
+    <Heading
+      slot="title"
+      {...props}
+      className={cn(
+        'font-sans font-medium text-[20px] leading-[1.25] tracking-[-0.015em] text-ink',
+        className,
+      )}
+    />
+  )
+}
+
+/** Supporting copy under the title. */
+export function ModalDescription({ className, ...props }: HTMLAttributes<HTMLParagraphElement>) {
+  return <p {...props} className={cn('text-[14px] leading-[1.55] text-ink-3', className)} />
+}
+
+/** Padded main content block — put forms, text, lists, etc. here. */
+export function ModalBody({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      {...props}
+      className={cn(
+        // The scroll region: caps at the panel's spare height and scrolls when
+        // the content is taller, leaving header + footer pinned.
+        'min-h-0 overflow-y-auto px-5 py-3 flex flex-col gap-3 text-[14px] text-ink-2',
+        className,
+      )}
+    />
+  )
+}
+
+/** Action row at the bottom. Right-aligned. Place a `<Separator />` above
+ *  it when you want the dashed divider between body and footer. */
+export function ModalFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      {...props}
+      className={cn('shrink-0 flex justify-end items-center gap-2', 'px-5 pt-3 pb-5', className)}
+    />
+  )
+}

package/src/components/multi-select/index.ts

@@ -0,0 +1,2 @@
+export type { MultiSelectOption, MultiSelectProps } from './multi-select'
+export { MultiSelect } from './multi-select'