@estiva-app/ui 0.1.0 → 0.2.0

package/src/ChipInput.tsx

@@ -0,0 +1,247 @@
+import { useState, useRef, useMemo, useEffect, useLayoutEffect, type KeyboardEvent, type ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import { IconX } from '@tabler/icons-react'
+import { cn } from './cn'
+import { MenuItem } from './Menu'
+
+/**
+ * The chip a `ChipInput` is made of: a 24px pill with an optional 16px
+ * leading (a face, an icon), a 12px label, and the ✕ that removes it.
+ * Exported on its own (Katerina, 2026-09-01) under a name that promises
+ * nothing about people — a chip like this may one day hold a label, a file,
+ * a filter.
+ */
+export interface InputChipProps {
+  label: string
+  /** Before the label, 16px — an Avatar, an icon. */
+  leading?: ReactNode
+  /** Draws the ✕; absent, the chip is display-only. */
+  onRemove?: () => void
+  className?: string
+}
+
+export function InputChip({ label, leading, onRemove, className }: InputChipProps) {
+  return (
+    <div
+      className={cn(
+        // Curved, not a pill (Katerina, 2026-09-01): the Avatar keeps its own
+        // rounded-sm corners — never a forced circle — and the chip's corner
+        // follows concentrically: 4px face + 2px inset = rounded-md.
+        'inline-flex items-center gap-1.5 bg-bg-elevated border border-border-subtle rounded-md py-0.5 max-h-[24px]',
+        // The padding follows the contents (Katerina, 2026-09-01): a face
+        // sits 2px from the edge, a bare label needs 8px of air; the ✕
+        // brings its own box, so 4px behind it — 8px when there isn't one.
+        leading ? 'pl-[2px]' : 'pl-2',
+        onRemove ? 'pr-1' : 'pr-2',
+        className,
+      )}
+    >
+      {leading && <span className="flex shrink-0 items-center">{leading}</span>}
+      <span className="text-caption font-medium text-text-primary">{label}</span>
+      {onRemove && (
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation()
+            onRemove()
+          }}
+          className="size-4 flex items-center justify-center rounded-full hover:bg-bg-hover text-text-secondary"
+          aria-label={`Remove ${label}`}
+        >
+          <IconX size={10} stroke={1.5} />
+        </button>
+      )}
+    </div>
+  )
+}
+
+/**
+ * A multi-select input: chips for the chosen, a typeahead for the rest —
+ * Peek's PersonChipInput (2026-09-01), generalised on the way in. Peek's
+ * version knew it was picking people: it read the directory from Peek's own
+ * data layer and drew every face itself. Here the caller hands in `options`,
+ * and — when the entries have faces or icons — the two leading slots: 16px
+ * in a chip, 32px in a suggestion row. Nothing in this file knows what is
+ * being picked.
+ *
+ * Suggestions appear only once the user types — focusing (or auto-focus on
+ * dialog open) must not drop the full directory over the surface below.
+ * Backspace on an empty query removes the last chip; Escape clears the query
+ * when there is one and bubbles when there is not, so the surface around it
+ * (dialog, launcher) can act.
+ *
+ * Generic over the option type: the objects handed back through `onChange`
+ * are the caller's own, extra fields and all — no re-mapping on the way out.
+ */
+export interface ChipInputOption {
+  id: string
+  label: string
+  /** The suggestion row's second line — a role, an address. Also searched. */
+  description?: string
+}
+
+export interface ChipInputProps<T extends ChipInputOption = ChipInputOption> {
+  value: T[]
+  onChange: (next: T[]) => void
+  /** The directory the typeahead searches. */
+  options: T[]
+  placeholder?: string
+  autoFocus?: boolean
+  /** Option ids excluded from the suggestion list (e.g., the current user). */
+  excludeIds?: string[]
+  /** Before a chip's label, 16px — a face, an icon. */
+  chipLeading?: (option: T) => ReactNode
+  /** Before a suggestion row's label, 32px. */
+  rowLeading?: (option: T) => ReactNode
+}
+
+export function ChipInput<T extends ChipInputOption = ChipInputOption>({
+  value,
+  onChange,
+  options,
+  placeholder = 'Search…',
+  autoFocus,
+  excludeIds = [],
+  chipLeading,
+  rowLeading,
+}: ChipInputProps<T>) {
+  const [query, setQuery] = useState('')
+  const [highlight, setHighlight] = useState(0)
+  const [isFocused, setIsFocused] = useState(false)
+  const [anchorRect, setAnchorRect] = useState<DOMRect | null>(null)
+  const wrapperRef = useRef<HTMLDivElement>(null)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  const matches = useMemo(() => {
+    const selectedIds = new Set(value.map((o) => o.id))
+    const excludedIds = new Set(excludeIds)
+    const q = query.trim().toLowerCase()
+    return options.filter((o) => {
+      if (selectedIds.has(o.id)) return false
+      if (excludedIds.has(o.id)) return false
+      if (!q) return true
+      return o.label.toLowerCase().includes(q) || (o.description ?? '').toLowerCase().includes(q)
+    })
+  }, [query, value, excludeIds, options])
+
+  useEffect(() => {
+    setHighlight(0)
+  }, [query, matches.length])
+
+  const showDropdown = isFocused && query.trim().length > 0 && matches.length > 0
+
+  useLayoutEffect(() => {
+    if (!showDropdown) return
+    const update = () => {
+      if (wrapperRef.current) setAnchorRect(wrapperRef.current.getBoundingClientRect())
+    }
+    update()
+    window.addEventListener('resize', update)
+    window.addEventListener('scroll', update, true)
+    return () => {
+      window.removeEventListener('resize', update)
+      window.removeEventListener('scroll', update, true)
+    }
+  }, [showDropdown, value.length])
+
+  function addOption(option: T) {
+    onChange([...value, option])
+    setQuery('')
+    inputRef.current?.focus()
+  }
+
+  function removeOption(id: string) {
+    onChange(value.filter((o) => o.id !== id))
+  }
+
+  function handleKeyDown(e: KeyboardEvent<HTMLInputElement>) {
+    if (e.key === 'Backspace' && query === '' && value.length > 0) {
+      // Consumed: removing a chip must not double as the surface's "back".
+      e.preventDefault()
+      removeOption(value[value.length - 1].id)
+      return
+    }
+    if (e.key === 'ArrowDown') {
+      e.preventDefault()
+      setHighlight((h) => Math.min(h + 1, Math.max(0, matches.length - 1)))
+      return
+    }
+    if (e.key === 'ArrowUp') {
+      e.preventDefault()
+      setHighlight((h) => Math.max(h - 1, 0))
+      return
+    }
+    if (e.key === 'Enter') {
+      e.preventDefault()
+      const target = matches[highlight]
+      if (target) addOption(target)
+      return
+    }
+    if (e.key === 'Escape') {
+      // Consume it only when there is something to clear; an idle input lets
+      // Escape bubble so the surface around it (dialog, launcher) can act.
+      if (query !== '') {
+        e.preventDefault()
+        setQuery('')
+      }
+    }
+  }
+
+  return (
+    <div className="relative">
+      <div
+        ref={wrapperRef}
+        className="bg-bg-inset border border-border-default hover:border-border-strong focus-within:border-border-focus focus-within:hover:border-border-focus rounded-lg px-3 py-1.5 flex flex-wrap items-center gap-1.5 transition-colors min-h-[38px] cursor-text signal:transition-shadow signal:focus-within:shadow-focus-ring"
+        onClick={() => inputRef.current?.focus()}
+      >
+        {value.map((o) => (
+          <InputChip key={o.id} label={o.label} leading={chipLeading?.(o)} onRemove={() => removeOption(o.id)} />
+        ))}
+
+        <input
+          ref={inputRef}
+          autoFocus={autoFocus}
+          type="text"
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          onKeyDown={handleKeyDown}
+          onFocus={() => setIsFocused(true)}
+          onBlur={() => {
+            setTimeout(() => setIsFocused(false), 150)
+          }}
+          placeholder={value.length === 0 ? placeholder : ''}
+          className="flex-1 min-w-[120px] bg-transparent text-body-2 text-text-primary placeholder:text-text-muted outline-none border-none"
+        />
+      </div>
+
+      {showDropdown && anchorRect && createPortal(
+        <div
+          className="fixed z-[60] max-h-[240px] overflow-y-auto bg-bg-elevated border border-border-default rounded-lg shadow-lg"
+          style={{
+            top: anchorRect.bottom + 4,
+            left: anchorRect.left,
+            width: anchorRect.width,
+          }}
+        >
+          {matches.map((o, i) => (
+            <MenuItem
+              key={o.id}
+              size="tall"
+              className="h-12 rounded-none"
+              leading={rowLeading?.(o)}
+              label={o.label}
+              description={o.description}
+              selected={i === highlight}
+              onMouseEnter={() => setHighlight(i)}
+              onMouseDown={(e) => {
+                e.preventDefault()
+                addOption(o)
+              }}
+            />
+          ))}
+        </div>,
+        document.body
+      )}
+    </div>
+  )
+}

package/src/ConfirmDialog.mdx

@@ -0,0 +1,51 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as ConfirmDialogStories from './ConfirmDialog.stories'
+
+<Meta of={ConfirmDialogStories} />
+
+# ConfirmDialog
+
+A question with two answers, asked before something a person would want
+back. Built on DialogShell; the body is plain sentences in `body-2`.
+
+<Canvas of={ConfirmDialogStories.Destructive} />
+
+## When
+
+- Before a deletion, an archive, a handover — anything hard to undo. The
+  confirm button is `destructive` when the action is.
+- A non-destructive but consequential step confirms with `primary`.
+
+## When not
+
+- Gathering input first → **DialogShell** with a form.
+- Telling someone what already happened → **Toast**.
+- Guarding something trivially reversible — don't; an undo beats a
+  question.
+
+## How
+
+```tsx
+import { ConfirmDialog } from '@estiva-app/ui'
+
+{confirming && (
+  <ConfirmDialog
+    title="Delete this?"
+    confirmLabel="Delete"
+    destructive
+    onConfirm={() => remove()}
+    onClose={() => setConfirming(false)}
+  >
+    <p>This removes it for everyone. There is no undo.</p>
+  </ConfirmDialog>
+)}
+```
+
+- While `onConfirm` runs, both buttons wait. Resolving `false` keeps the
+  dialog open — your surface has said why; a resolved `void`/`true`
+  closes it.
+- Escape and the backdrop click cancel, via the shell.
+
+## Props
+
+<Controls of={ConfirmDialogStories.Destructive} />

package/src/ConfirmDialog.stories.tsx

@@ -0,0 +1,63 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+import { Button } from './Button'
+import { ConfirmDialog } from './ConfirmDialog'
+
+const meta = {
+  title: 'Overlays/ConfirmDialog',
+  component: ConfirmDialog,
+  parameters: {
+    layout: 'fullscreen',
+    // Portals a fixed overlay to document.body — render in an iframe on the
+    // Docs page so it doesn't escape over the docs content.
+    docs: { story: { inline: false, height: '400px' } },
+  },
+  argTypes: { children: { control: false }, onConfirm: { control: false } },
+  args: {
+    title: 'Delete this?',
+    confirmLabel: 'Delete',
+    destructive: true,
+    onConfirm: () => {},
+    onClose: () => {},
+    children: 'This permanently removes it. It cannot be undone.',
+  },
+} satisfies Meta<typeof ConfirmDialog>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Destructive: Story = {}
+
+/** A confirmation that isn't a loss — the confirm button stays primary. */
+export const NonDestructive: Story = {
+  args: {
+    title: 'Hand this over?',
+    confirmLabel: 'Hand over',
+    destructive: false,
+    children: 'They become the owner. You keep reading rights.',
+  },
+}
+
+/**
+ * An action that resolves `false` keeps the dialog open — the caller has
+ * shown why, and closing over an unexplained failure would lose the moment
+ * to read it. Confirm here refuses forever; Cancel is the way out.
+ */
+export const RefusalKeepsItOpen: Story = {
+  parameters: { controls: { disable: true } },
+  render: (args) => {
+    const [open, setOpen] = useState(true)
+    return (
+      <div className="flex h-screen items-center justify-center">
+        <Button variant="primary" onClick={() => setOpen(true)}>
+          Open dialog
+        </Button>
+        {open && (
+          <ConfirmDialog {...args} onConfirm={() => false} onClose={() => setOpen(false)}>
+            Confirm resolves false, so the dialog stays. Cancel closes it.
+          </ConfirmDialog>
+        )}
+      </div>
+    )
+  },
+}

package/src/ConfirmDialog.tsx

@@ -0,0 +1,55 @@
+import { useState, type ReactNode } from 'react'
+import { Button } from './Button'
+import { DialogShell } from './DialogShell'
+
+/**
+ * A question with two answers, before something a person would want back —
+ * Ship's ConfirmDialog (2026-09-01), verbatim. Its own comment always called
+ * it a package candidate: nothing here knows what is being confirmed.
+ *
+ * The confirm button is `destructive` when the action is (a deletion, an
+ * archive); `primary` otherwise. While the action runs the buttons wait;
+ * an action that resolves `false` keeps the dialog open, so the caller's
+ * banner can say why.
+ */
+export interface ConfirmDialogProps {
+  title: string
+  /** The body — plain sentences, body-2. */
+  children: ReactNode
+  confirmLabel: string
+  destructive?: boolean
+  onConfirm: () => Promise<boolean | void> | boolean | void
+  onClose: () => void
+}
+
+export function ConfirmDialog({ title, children, confirmLabel, destructive = false, onConfirm, onClose }: ConfirmDialogProps) {
+  const [busy, setBusy] = useState(false)
+  const confirm = async () => {
+    setBusy(true)
+    try {
+      const ok = await onConfirm()
+      if (ok !== false) onClose()
+    } finally {
+      setBusy(false)
+    }
+  }
+  return (
+    <DialogShell
+      title={title}
+      onClose={onClose}
+      bodyClassName="flex flex-col gap-3 text-body-2 text-text-primary"
+      footer={
+        <>
+          <Button variant="muted" onClick={onClose} disabled={busy}>
+            Cancel
+          </Button>
+          <Button variant={destructive ? 'destructive' : 'primary'} onClick={() => void confirm()} disabled={busy}>
+            {confirmLabel}
+          </Button>
+        </>
+      }
+    >
+      {children}
+    </DialogShell>
+  )
+}

package/src/DialogShell.mdx

@@ -0,0 +1,68 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as DialogShellStories from './DialogShell.stories'
+
+<Meta of={DialogShellStories} />
+
+# DialogShell
+
+The dialog, minus what it says: the portal, the backdrop, a 502px card,
+a 48px header with the title and a close button, a body, and a 48px
+footer for the buttons. A dialog is just what goes in the three slots.
+
+<Canvas of={DialogShellStories.Default} />
+
+## When
+
+- Anything with a title, a body, and buttons: a form, a picker, a roster.
+- `footer` absent removes the footer row entirely — a list that simply
+  ends keeps the card's own bottom edge.
+- `headerContent` replaces the title text — a back button beside the
+  title, a count chip after it. The close button stays.
+
+## When not
+
+- A short list of verbs from a trigger → **Menu**.
+- "Are you sure?" → **ConfirmDialog** — it is this shell with the question
+  already wired.
+- Telling someone what happened → **Toast**.
+
+## How
+
+```tsx
+import { DialogShell, Button } from '@estiva-app/ui'
+
+{open && (
+  <DialogShell
+    title="New document"
+    onClose={() => setOpen(false)}
+    footer={
+      <>
+        <Button onClick={() => setOpen(false)}>Cancel</Button>
+        <Button variant="primary" onClick={submit}>Create</Button>
+      </>
+    }
+  >
+    …fields…
+  </DialogShell>
+)}
+```
+
+- Render it only while open — mounting is opening.
+- `bodyClassName` shapes the body (`flex flex-col gap-6`, or a max height
+  with `overflow-y-auto` for long lists). Rows in a height-capped flex
+  body need `shrink-0`, or overflow crushes them.
+- The card names itself to assistive tech (`role="dialog"`, labelled by
+  `title`). Focus is not trapped or moved — give the first field
+  `autoFocus` where typing is the point.
+
+## Keys
+
+| Input | What happens |
+|---|---|
+| Escape | closes |
+| backdrop click | closes |
+| close button | closes (it is an IconButton with its label) |
+
+## Props
+
+<Controls of={DialogShellStories.Default} />

package/src/DialogShell.tsx

@@ -12,16 +12,23 @@ import { IconButton } from './IconButton'
  * says what it is to assistive tech.
  */
 export interface DialogShellProps {
+  /** Labels the dialog for assistive tech, and renders as the header text
+   *  unless `headerContent` replaces it. */
   title: string
   onClose: () => void
-  footer: ReactNode
+  /** Replaces the title text in the header — a back button beside the title,
+   *  a count chip after it. The close button stays. */
+  headerContent?: ReactNode
+  /** Absent: no footer row, and the body keeps the card's own bottom edge
+   *  (a roster that simply ends). */
+  footer?: ReactNode
   children: ReactNode
   /** Extra classes on the body (e.g. `flex flex-col gap-6`, or a max height with `overflow-y-auto`). */
   bodyClassName?: string
   width?: number
 }
 
-export function DialogShell({ title, onClose, footer, children, bodyClassName, width = 502 }: DialogShellProps) {
+export function DialogShell({ title, onClose, headerContent, footer, children, bodyClassName, width = 502 }: DialogShellProps) {
   useEffect(() => {
     const onKey = (event: KeyboardEvent) => {
       if (event.key === 'Escape') onClose()
@@ -46,17 +53,17 @@ export function DialogShell({ title, onClose, footer, children, bodyClassName, w
         >
           {/* Header */}
           <div className="h-12 flex items-center justify-between pl-5 pr-4 border-b border-border-subtle shrink-0">
-            <span className="text-h4 text-text-primary">{title}</span>
+            {headerContent ?? <span className="text-h4 text-text-primary">{title}</span>}
             <IconButton tooltip="Close" aria-label="Close" onClick={onClose}>
               <IconX size={16} stroke={1.5} />
             </IconButton>
           </div>
 
           {/* Body */}
-          <div className={cn('pl-5 pr-4 py-4 border-b border-border-subtle', bodyClassName)}>{children}</div>
+          <div className={cn('pl-5 pr-4 py-4', footer != null && 'border-b border-border-subtle', bodyClassName)}>{children}</div>
 
           {/* Footer */}
-          <div className="h-12 flex items-center justify-end gap-2 pl-5 pr-4 shrink-0">{footer}</div>
+          {footer != null && <div className="h-12 flex items-center justify-end gap-2 pl-5 pr-4 shrink-0">{footer}</div>}
         </div>
       </div>
     </>,

package/src/Divider.mdx

@@ -0,0 +1,41 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as DividerStories from './Divider.stories'
+
+<Meta of={DividerStories} />
+
+# Divider
+
+A hairline in `border-subtle`. Horizontal it is inset 12px each side;
+`orientation="vertical"` stands it up to its row's height, no inset. It
+carries the `separator` role for assistive tech.
+
+<Canvas of={DividerStories.Default} />
+
+## When
+
+- Between groups in a **Menu** (`className="my-1"` gives it its breathing
+  room there).
+- Between sections of a panel or rail.
+- Vertical: between clusters in a toolbar or a dense row.
+
+<Canvas of={DividerStories.Vertical} />
+
+## When not
+
+- Between every row of a list — spacing does that; a hairline per row is
+  noise.
+- To title what follows → **SectionLabel** or **SectionHeader**; a heading
+  separates better than a line.
+
+## How
+
+```tsx
+import { Divider } from '@estiva-app/ui'
+
+<Divider />
+<Divider orientation="vertical" />
+```
+
+## Props
+
+<Controls of={DividerStories.Default} />

package/src/EditableText.mdx

@@ -0,0 +1,59 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as EditableTextStories from './EditableText.stories'
+
+<Meta of={EditableTextStories} />
+
+# EditableText
+
+Text you click to edit. It reads as text until clicked; then it is a
+field. A commit that fails keeps the field open with the text in it, so an
+edit is never silently lost.
+
+<Canvas of={EditableTextStories.Title} />
+
+## When
+
+- A title or description edited where it is shown — no dialog, no separate
+  form.
+- A reader who cannot write gets `readOnly` — the value without the edit
+  affordance, because an action appears only where it can succeed.
+
+## When not
+
+- A field in a form or dialog → **TextInput** / **Textarea** in a
+  **Field**.
+- Composing something new → the field, not an edit-in-place of nothing.
+
+## How
+
+```tsx
+import { EditableText } from '@estiva-app/ui'
+
+<EditableText
+  value={title}
+  placeholder="Untitled"
+  label="Title"
+  onCommit={async (next) => save(next)}
+/>
+```
+
+- `onCommit` resolves `true` to close; `false` (or a throw) keeps the
+  field open — you have already told the person why. An unchanged value is
+  not committed at all.
+- `label` is required — it is the field's accessible name.
+- `display` shows something other than what is edited (a value carrying
+  raw references, rendered richer when read) without losing the original
+  on commit.
+
+## Keys
+
+| Input | What happens |
+|---|---|
+| click the text | opens the field, selects the value |
+| Enter | commits (`multiline`: Shift+Enter is a new line) |
+| Escape | cancels, restores the value |
+| blur | commits |
+
+## Props
+
+<Controls of={EditableTextStories.Title} />