@estiva-app/ui 0.1.0 → 0.3.0

package/src/Breadcrumb.tsx

@@ -0,0 +1,106 @@
+import { Fragment, useCallback, useLayoutEffect, useRef, useState } from 'react'
+import { cn } from './cn'
+import { WithTooltip } from './Tooltip'
+
+/**
+ * A trail: "Documents / Quarterly plan / DOC-12". Ship's Breadcrumb
+ * (2026-09-01), which knows nothing about what the places are.
+ *
+ * An item with an `href` is a link, even when it is last — a page may end its
+ * trail on somewhere to go. The last item is where you are when it has none,
+ * and may be `mono` (a ref, an id) or plain. The separator is a slash, muted,
+ * never read aloud.
+ *
+ * A crumb that truncates shows its whole label in a tooltip on hover
+ * (Katerina, 2026-09-01); one that fits shows nothing extra. Truncation is
+ * re-measured when the trail resizes, so the tooltip appears and disappears
+ * with the room the trail actually has.
+ */
+export interface Crumb {
+  label: string
+  href?: string
+  /** Set the item in the mono face — a ref, an id. */
+  mono?: boolean
+  /** Quieter — a label that is not a place. */
+  muted?: boolean
+}
+
+export interface BreadcrumbProps {
+  items: Crumb[]
+  className?: string
+}
+
+export function Breadcrumb({ items, className }: BreadcrumbProps) {
+  const navRef = useRef<HTMLElement>(null)
+  const labelRefs = useRef<(HTMLElement | null)[]>([])
+  const [truncated, setTruncated] = useState<ReadonlySet<number>>(new Set())
+
+  const measure = useCallback(() => {
+    const next = new Set<number>()
+    labelRefs.current.forEach((el, index) => {
+      if (el && el.scrollWidth > el.clientWidth) next.add(index)
+    })
+    setTruncated((prev) => (prev.size === next.size && [...next].every((i) => prev.has(i)) ? prev : next))
+  }, [])
+
+  useLayoutEffect(() => {
+    measure()
+    const nav = navRef.current
+    // jsdom has neither layout nor ResizeObserver; without this guard a
+    // consumer app cannot render a page with a trail in its tests.
+    if (!nav || typeof ResizeObserver === 'undefined') return
+    const observer = new ResizeObserver(measure)
+    observer.observe(nav)
+    return () => observer.disconnect()
+  }, [measure, items])
+
+  return (
+    <nav ref={navRef} aria-label="Breadcrumb" className={cn('flex min-w-0 items-center gap-1.5 text-[14px] leading-[140%]', className)}>
+      {items.map((item, index) => {
+        const last = index === items.length - 1
+        // The mono size is an arbitrary value (the caption token) because this
+        // string goes through cn() and a token size before a colour class is
+        // dropped (the tailwind-merge pitfall).
+        const text = cn(
+          'truncate',
+          // A mono crumb is a ref — the identity. It never gives up width to a
+          // long name beside it (the LongName story always claimed "the ref
+          // stays"; flexbox was squeezing it anyway until this line).
+          item.mono && 'shrink-0 font-mono text-[12px] leading-[120%]',
+          item.muted || (last && item.mono) ? 'text-text-muted' : last ? 'text-text-primary' : 'text-text-secondary',
+        )
+        const setLabelRef = (el: HTMLElement | null) => {
+          labelRefs.current[index] = el
+        }
+        const crumb = item.href ? (
+          <a ref={setLabelRef} href={item.href} className={cn(text, 'hover:text-text-primary')}>
+            {item.label}
+          </a>
+        ) : (
+          <span ref={setLabelRef} className={text} aria-current={last ? 'page' : undefined}>
+            {item.label}
+          </span>
+        )
+        return (
+          <Fragment key={`${item.label}-${index}`}>
+            {index > 0 && (
+              <span aria-hidden="true" className="shrink-0 text-text-muted">
+                /
+              </span>
+            )}
+            {truncated.has(index) ? (
+              // `min-w-0 shrink` undoes the wrapper's own shrink-0 — the crumb
+              // must keep truncating inside it, or wrapping it would widen the
+              // trail and the tooltip would never be needed again.
+              <WithTooltip label={item.label} wrapperClassName="min-w-0 shrink">
+                {crumb}
+              </WithTooltip>
+            ) : (
+              crumb
+            )}
+          </Fragment>
+        )
+      })}
+    </nav>
+  )
+}

package/src/Button.mdx

@@ -0,0 +1,57 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as ButtonStories from './Button.stories'
+
+<Meta of={ButtonStories} />
+
+# Button
+
+The push-button for an action: a verb, clicked once — "Create", "Save",
+"Delete project". Four variants on one geometry: 32px default / 24px small,
+6px radius, medium weight.
+
+<Canvas of={ButtonStories.AllVariants} />
+
+## When
+
+- **`primary`** — the one action the surface exists for. At most one per
+  surface. It reads in `text-inverse` on the accent; the theme decides what
+  both of those are.
+- **`outlined`** — a real alternative standing beside the primary ("Cancel"
+  next to "Save"), or a lone action that needs an edge to be found at all.
+- **`muted`** — the default, and most buttons. Anything that should not
+  compete for attention: dialog dismissals, secondary page actions.
+- **`destructive`** — "Delete …" and its kind: the muted button in the
+  error colour. A destructive action is a button like any other, not a
+  dotted link — it is guarded by a ConfirmDialog, not by being hard to see.
+
+## When not
+
+- An icon with no label → **IconButton**.
+- Going somewhere rather than doing something → **Tabs**, **Breadcrumb**,
+  or a plain link.
+- Choosing a value → **Select**. Acting from a popover list → **MenuItem**.
+- A control the person may never be allowed to use is **absent, not
+  disabled**. `disabled` is for *momentarily* unavailable — and it says why,
+  with a Tooltip ("Available after sign-in").
+
+## How
+
+```tsx
+import { Button } from '@estiva-app/ui'
+import { IconPlus } from '@tabler/icons-react'
+
+<Button variant="primary" leadingIcon={<IconPlus stroke={1.5} className="size-4" />} onClick={create}>
+  New document
+</Button>
+```
+
+- `leadingIcon` is 16px at stroke 1.5 (14px, `size-3.5`, on `small`); the
+  button balances its own padding around it.
+- `type` defaults to `"button"` — inside a form it submits only when you
+  say `type="submit"`.
+- It is a native `<button>`, and every native prop passes through; the
+  visible label is the accessible name, so no `aria-label` is needed.
+
+## Props
+
+<Controls of={ButtonStories.Primary} />

package/src/Checkbox.mdx

@@ -0,0 +1,44 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as CheckboxStories from './Checkbox.stories'
+
+<Meta of={CheckboxStories} />
+
+# Checkbox
+
+A 16px square that fills with the accent when checked. Controlled only —
+the parent owns the state.
+
+<Canvas of={CheckboxStories.Toggles} />
+
+## When
+
+- A yes/no the person sets: an option in a form, an include/exclude in a
+  list.
+- Inside a clickable row: pass **no `onChange`** and the square goes inert
+  — the row's own click does the toggling, and the checkbox just shows the
+  state.
+
+<Canvas of={CheckboxStories.InsideARow} />
+
+## When not
+
+- One choice out of several → **Select** (a value) or **Tabs** (a view).
+- Inside a **Menu** — a checkbox inside a `menuitem` is invalid HTML;
+  a checkable list lives in a DialogShell.
+
+## How
+
+```tsx
+import { Checkbox } from '@estiva-app/ui'
+
+<Checkbox checked={done} onChange={setDone} aria-label="Mark as done" />
+```
+
+- It renders as a button with the `checkbox` role, so it works standalone
+  or inside clickable rows; its click never bubbles to the row.
+- Give it an `aria-label` unless visible text right beside it names it.
+- Space or Enter toggles it, as any button.
+
+## Props
+
+<Controls of={CheckboxStories.Unchecked} />

package/src/Checkbox.stories.tsx

@@ -0,0 +1,49 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+import { Checkbox } from './Checkbox'
+
+const meta = {
+  title: 'Inputs/Checkbox',
+  component: Checkbox,
+  args: { checked: false, 'aria-label': 'Example' },
+  argTypes: { onChange: { control: false } },
+} satisfies Meta<typeof Checkbox>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Unchecked: Story = {}
+export const Checked: Story = { args: { checked: true } }
+export const Disabled: Story = { args: { disabled: true } }
+export const DisabledChecked: Story = { args: { checked: true, disabled: true } }
+
+/** Controlled, as always — the parent owns the state. */
+export const Toggles: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [checked, setChecked] = useState(false)
+    return <Checkbox checked={checked} onChange={setChecked} aria-label="Toggle me" />
+  },
+}
+
+/**
+ * Inside a clickable row the row owns the toggle: the checkbox gets no
+ * `onChange` and goes inert, so the whole row is one target rather than two
+ * fighting ones.
+ */
+export const InsideARow: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [checked, setChecked] = useState(true)
+    return (
+      <button
+        type="button"
+        onClick={() => setChecked((v) => !v)}
+        className="flex w-64 items-center gap-3 rounded-lg px-3 py-2 text-left transition-colors hover:bg-bg-hover"
+      >
+        <Checkbox checked={checked} aria-label="Row state" />
+        <span className="text-[14px] leading-[1.4] text-text-primary">The row is the control</span>
+      </button>
+    )
+  },
+}

package/src/Checkbox.tsx

@@ -0,0 +1,46 @@
+import { IconCheck } from '@tabler/icons-react'
+import { cn } from './cn'
+
+/**
+ * A 16px square that fills with the accent when checked — Peek's Checkbox
+ * (2026-09-01), verbatim.
+ *
+ * Controlled only; parents own the state. Rendered as a button with the
+ * checkbox role so it works standalone or inside clickable rows: a caller
+ * that toggles on the row's own click passes no `onChange`, and the square
+ * goes inert rather than stealing the click.
+ */
+export interface CheckboxProps {
+  checked: boolean
+  onChange?: (checked: boolean) => void
+  disabled?: boolean
+  'aria-label'?: string
+  className?: string
+}
+
+export function Checkbox({ checked, onChange, disabled = false, className, ...aria }: CheckboxProps) {
+  return (
+    <button
+      type="button"
+      role="checkbox"
+      aria-checked={checked}
+      aria-label={aria['aria-label']}
+      disabled={disabled}
+      onClick={(e) => {
+        e.stopPropagation()
+        onChange?.(!checked)
+      }}
+      className={cn(
+        'inline-flex items-center justify-center size-4 shrink-0 rounded-[4px] border transition-colors',
+        checked
+          ? 'bg-accent-primary border-accent-primary text-text-inverse'
+          : 'bg-transparent border-border-strong hover:border-text-muted',
+        disabled && 'opacity-50 pointer-events-none',
+        onChange ? 'cursor-pointer' : 'pointer-events-none',
+        className,
+      )}
+    >
+      {checked && <IconCheck size={12} stroke={3} />}
+    </button>
+  )
+}

package/src/Chip.mdx

@@ -0,0 +1,43 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as ChipStories from './Chip.stories'
+
+<Meta of={ChipStories} />
+
+# Chip
+
+A 20px pill for a small piece of standing information — a status, a count,
+a category — in one of six colour types. The semantic four sit on their
+muted tints; the label is the `chip` type token, 11px / 500.
+
+<Canvas of={ChipStories.AllTypes} />
+
+## When
+
+- **`neutral`** — a count or tag with no verdict attached.
+- **`brand`** — the accent's voice: a highlight, a "you are here".
+- **`info` / `warning` / `success` / `error`** — a state with a meaning;
+  the colour is the message, the label makes it legible.
+
+## When not
+
+- Something clickable → **Button** (small) or **MenuItem** — a Chip is not
+  a control.
+- A removable token in a multi-select → **InputChip** (see ChipInput).
+- A count beside a tab label → **Tabs** draws its own mono number, not a
+  Chip.
+
+## How
+
+```tsx
+import { Chip } from '@estiva-app/ui'
+
+<Chip type="success" label="Done" />
+```
+
+- `leadingIcon` / `trailingIcon` take a 12px icon; the slots centre it, so
+  it never rides the text baseline.
+- A count alone works too — `label="3"`, no icon.
+
+## Props
+
+<Controls of={ChipStories.Neutral} />

package/src/ChipInput.mdx

@@ -0,0 +1,68 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as ChipInputStories from './ChipInput.stories'
+
+<Meta of={ChipInputStories} />
+
+# ChipInput
+
+A multi-select input: chips for the chosen, a typeahead for the rest.
+Nothing in it knows what is being picked — people, labels, files — the
+caller hands in `options` and, when the entries have faces, the two
+leading slots.
+
+<Canvas of={ChipInputStories.WithChips} />
+
+## When
+
+- Choosing several entries from a directory: members for a group,
+  recipients, tags.
+- **InputChip** is exported on its own for the display-only case — chosen
+  things shown somewhere no editing happens.
+
+<Canvas of={ChipInputStories.TheChipItself} />
+
+## When not
+
+- One value → **Select**.
+- Free text that becomes an entry — it only picks from `options`; if
+  typing must create things, that is your surface's logic around it.
+
+## How
+
+```tsx
+import { ChipInput } from '@estiva-app/ui'
+
+<ChipInput
+  value={chosen}
+  onChange={setChosen}
+  options={directory}
+  chipLeading={(o) => <Avatar name={o.label} src={o.picture} size={16} />}
+  rowLeading={(o) => <Avatar name={o.label} src={o.picture} size={32} />}
+  excludeIds={[viewer.id]}
+/>
+```
+
+- An option is `{ id, label, description? }` — the description is the
+  suggestion row's second line, and is searched too. The component is
+  **generic over your option type**: `onChange` hands back your own
+  objects, extra fields and all, no re-mapping.
+- `chipLeading` is 16px in a chip; `rowLeading` is 32px in a suggestion
+  row. The chip's padding follows its contents — a face sits 2px from the
+  edge, a bare label gets 8px.
+- Suggestions appear **only once the user types** — focusing must not drop
+  the whole directory over the surface below.
+
+## Keys
+
+| Input | What happens |
+|---|---|
+| typing | filters; suggestions appear |
+| ↑ / ↓ | move the highlight |
+| Enter | adds the highlighted entry |
+| Backspace, empty query | removes the last chip — consumed, never the surface's "back" |
+| Escape, with a query | clears the query — consumed |
+| Escape, idle | bubbles, so the dialog or launcher around it can act |
+
+## Props
+
+<Controls of={ChipInputStories.TypeToSearch} />

package/src/ChipInput.stories.tsx

@@ -0,0 +1,99 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+import { Avatar } from './Avatar'
+import { ChipInput, InputChip, type ChipInputOption } from './ChipInput'
+
+const PEOPLE: ChipInputOption[] = [
+  { id: '1', name: 'Ana Duarte', description: 'Design' },
+  { id: '2', name: 'Ravi Mehta', description: 'Engineering' },
+  { id: '3', name: 'Marta Silva', description: 'Product' },
+  { id: '4', name: 'Jonas Weber', description: 'Engineering' },
+  { id: '5', name: 'Lea Novak', description: 'Research' },
+].map(({ id, name, description }) => ({ id, label: name, description }))
+
+const LABELS: ChipInputOption[] = [
+  { id: 'a', label: 'Amber' },
+  { id: 'b', label: 'Cobalt' },
+  { id: 'c', label: 'Moss' },
+  { id: 'd', label: 'Slate' },
+]
+
+/** The person flavour: faces in the chips and the rows, from the two leading
+ *  slots — the Avatar at its own corners, never forced into a circle. */
+const personLeading = {
+  chipLeading: (o: ChipInputOption) => <Avatar size={16} name={o.label} alt={o.label} />,
+  rowLeading: (o: ChipInputOption) => <Avatar size={32} name={o.label} alt={o.label} />,
+}
+
+const meta = {
+  title: 'Inputs/ChipInput',
+  component: ChipInput,
+  parameters: {
+    // The suggestion list portals to document.body at fixed coordinates —
+    // render docs usage in an iframe so it lands where the field is.
+    docs: { story: { inline: false, height: '320px' } },
+  },
+  args: { value: [], onChange: () => {}, options: PEOPLE },
+  argTypes: {
+    value: { control: false },
+    onChange: { control: false },
+    options: { control: false },
+    chipLeading: { control: false },
+    rowLeading: { control: false },
+  },
+  decorators: [(Story) => <div className="w-96">{Story()}</div>],
+} satisfies Meta<typeof ChipInput>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Type a name — suggestions appear only once there is a query. */
+export const TypeToSearch: Story = {
+  parameters: { controls: { disable: true } },
+  render: (args) => {
+    const [value, setValue] = useState<ChipInputOption[]>([])
+    return <ChipInput {...args} {...personLeading} value={value} onChange={setValue} placeholder="Search people…" />
+  },
+}
+
+/** Chosen people are chips. Backspace on an empty query removes the last one. */
+export const WithChips: Story = {
+  parameters: { controls: { disable: true } },
+  render: (args) => {
+    const [value, setValue] = useState<ChipInputOption[]>([PEOPLE[0], PEOPLE[1]])
+    return <ChipInput {...args} {...personLeading} value={value} onChange={setValue} placeholder="Search people…" />
+  },
+}
+
+/** `excludeIds` keeps someone out of the suggestions — the current user, say. */
+export const ExcludingSomeone: Story = {
+  parameters: { controls: { disable: true } },
+  render: (args) => {
+    const [value, setValue] = useState<ChipInputOption[]>([])
+    return <ChipInput {...args} {...personLeading} value={value} onChange={setValue} excludeIds={['1']} placeholder="Search people…" />
+  },
+}
+
+/**
+ * Nothing about people: no leading slots, and the chips are plain labels.
+ * The same input picks anything multi-select.
+ */
+export const PlainLabels: Story = {
+  parameters: { controls: { disable: true } },
+  render: (args) => {
+    const [value, setValue] = useState<ChipInputOption[]>([LABELS[0]])
+    return <ChipInput {...args} value={value} onChange={setValue} options={LABELS} placeholder="Add a label…" />
+  },
+}
+
+/** The chip on its own: with a face, with nothing, and display-only (no ✕). */
+export const TheChipItself: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-2">
+      <InputChip label="Ana Duarte" leading={<Avatar size={16} name="Ana Duarte" alt="Ana Duarte" />} onRemove={() => {}} />
+      <InputChip label="Amber" onRemove={() => {}} />
+      <InputChip label="Display only" />
+    </div>
+  ),
+}