@estiva-app/ui 0.1.0 → 0.2.0

package/src/Person.mdx

@@ -0,0 +1,44 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as PersonStories from './Person.stories'
+
+<Meta of={PersonStories} />
+
+# Person
+
+A face beside a name — the inline mention of a human. The gap between face
+and name is one rule, 8px, wherever a person appears.
+
+<Canvas of={PersonStories.Sizes} />
+
+## When
+
+- A person named inline: an assignee, an author, a participant, a value in
+  a property row.
+- Someone with no published name shows the `fallback` — an em dash by
+  default, the same mark an empty property uses. Pass `"Anonymous"` where
+  the unnamed person is the viewer themself.
+
+## When not
+
+- The face alone → **Avatar**.
+- The person as a button that opens a menu → **PersonTrigger**.
+- A person as a row of a picker → **MenuItem** with an Avatar in `leading`
+  and a `description`.
+
+## How
+
+```tsx
+import { Person } from '@estiva-app/ui'
+
+<Person name={p.name} picture={p.picture} size={20} />
+```
+
+- Hand it strings — a name and a picture URL. It takes no key on purpose:
+  a component that accepted one would eventually show one.
+- It sets no text size of its own; the words inherit the caller's, so face
+  and words are always set together (the Sizes story shows the pairings).
+- The name truncates; give the container `min-w-0` room to let it.
+
+## Props
+
+<Controls of={PersonStories.Named} />

package/src/Person.stories.tsx

@@ -0,0 +1,43 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Person } from './Person'
+
+/** A face beside a name — never a key. */
+const meta = {
+  title: 'Primitives/Person',
+  component: Person,
+  args: { name: 'Ana Duarte', size: 20 },
+} satisfies Meta<typeof Person>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Named: Story = {}
+
+/** Nobody has published a name: the silhouette and the em dash, muted — the same mark a property with no value uses. */
+export const Unnamed: Story = {
+  args: { name: undefined },
+}
+
+/** Where the unnamed person is *you*, pass a word instead of the dash. */
+export const OwnFallback: Story = {
+  args: { name: undefined, fallback: 'Anonymous' },
+}
+
+/** The text size is the caller's, so face and words are set together. */
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col items-start gap-3">
+      <Person name="Ana Duarte" size={16} className="text-caption" />
+      <Person name="Ana Duarte" size={20} className="text-body-2" />
+      <Person name="Ravi Mehta" size={22} className="text-body-2" />
+      <Person name="Ravi Mehta" size={28} className="text-body-1" />
+    </div>
+  ),
+}
+
+/** A narrow spot: the name truncates, the face never does. */
+export const Truncating: Story = {
+  decorators: [(Story) => <div className="w-[120px]"><Story /></div>],
+  args: { name: 'Ana Duarte de Almeida e Costa' },
+}

package/src/Person.tsx

@@ -0,0 +1,39 @@
+import { cn } from './cn'
+import { Avatar } from './Avatar'
+
+/**
+ * A face beside a name. Ship's Person (2026-09-01), which was Peek's minus
+ * the projection type it took its profile from: this one is handed the two
+ * strings and nothing else, so it cannot be handed a key. Peek keeps a
+ * wrapper that resolves the profile, the way its Avatar wrapper resolves the
+ * picture.
+ *
+ * A face beside a name needs no caption (Peek's rulings), and someone nobody
+ * has published a name for gets the `fallback` — an em dash by default, the
+ * same mark a property with no value uses — rather than the key back on
+ * screen to say it. Pass "Anonymous" where the unnamed person is *you*, and
+ * you know who that is.
+ *
+ * The text size is the caller's, so the face and the words are always set
+ * together — see the Sizes story.
+ */
+export interface PersonProps {
+  name?: string
+  picture?: string
+  /** Shown in place of a missing name. */
+  fallback?: string
+  size?: number
+  className?: string
+}
+
+export function Person({ name, picture, fallback = '—', size = 20, className }: PersonProps) {
+  return (
+    // gap-2: the face-to-name distance is one rule (8px) wherever a person
+    // appears — Katerina, 2026-09-01, set on Person so PersonTrigger and every
+    // row agree by construction.
+    <span className={cn('flex min-w-0 items-center gap-2', className)}>
+      <Avatar name={name} src={picture} size={size} />
+      <span className={cn('truncate', !name && 'text-text-muted')}>{name ?? fallback}</span>
+    </span>
+  )
+}

package/src/PersonTrigger.mdx

@@ -0,0 +1,51 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as PersonTriggerStories from './PersonTrigger.stories'
+
+<Meta of={PersonTriggerStories} />
+
+# PersonTrigger
+
+The person, as the button that opens a menu. Two shapes, one component:
+the **row** — face · name · 14px chevron on a 32px button with a hover
+fill — and **`compact`** — the face alone, 36px, no chevron and no hover
+fill, because the face fills the whole control.
+
+<Canvas of={PersonTriggerStories.Row} />
+
+<Canvas of={PersonTriggerStories.Compact} />
+
+## When
+
+- The account trigger in a top bar — either shape.
+- Any control whose meaning is "this person, opened".
+- What it opens is not its business: pair it with **IdentityMenu** for the
+  ready-made account menu, or your own **Menu**.
+
+## When not
+
+- Showing a person without opening anything → **Person**.
+- Choosing a person from a list → **Select** or **ChipInput**.
+
+## How
+
+```tsx
+import { PersonTrigger } from '@estiva-app/ui'
+
+<PersonTrigger name={me.name} picture={me.picture} open={open}
+  onMouseDown={(e) => e.stopPropagation()} onClick={() => setOpen((v) => !v)} />
+```
+
+- `open` holds the row's hover fill while the menu is up, and feeds
+  `aria-expanded`.
+- **The accessible name**: the row shape is named by the visible name —
+  do **not** add an `aria-label`, it would override the person. The
+  `compact` face has no visible text, so there an `aria-label` is
+  required.
+- A toggle trigger must swallow its `mousedown` (as above) or the menu's
+  outside-click dismiss turns each press into close-then-reopen — the
+  trap is spelled out on the Menu page.
+- It takes a `ref` and every native button prop — anchor your menu on it.
+
+## Props
+
+<Controls of={PersonTriggerStories.Row} />

package/src/PersonTrigger.stories.tsx

@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { PersonTrigger } from './PersonTrigger'
+
+/** The person, as the button that opens the account menu. The menu itself stays in the app. */
+const meta = {
+  title: 'Primitives/PersonTrigger',
+  component: PersonTrigger,
+  args: { name: 'Ana Duarte', open: false, compact: false },
+} satisfies Meta<typeof PersonTrigger>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** The row shape — face · name · chevron on a 32px button, Ship's top bar. */
+export const Row: Story = {}
+
+/** While what it opens is open, the row holds its hover fill. */
+export const RowOpen: Story = {
+  args: { open: true },
+}
+
+/** The row for someone with no published name. */
+export const RowUnnamed: Story = {
+  args: { name: undefined, fallback: 'Anonymous' },
+}
+
+/** The face alone — Peek's top-bar shape. No chevron, no padding, and no hover fill: the face fills the whole control, so a fill would have nowhere to show. */
+export const Compact: Story = {
+  args: { compact: true },
+}

package/src/PersonTrigger.tsx

@@ -0,0 +1,62 @@
+import type { ComponentPropsWithRef } from 'react'
+import { IconChevronDown } from '@tabler/icons-react'
+import { cn } from './cn'
+import { Avatar } from './Avatar'
+import { Person, type PersonProps } from './Person'
+
+/**
+ * The person, as the button that opens the account menu.
+ *
+ * Two shapes, one component (Katerina, 2026-09-01):
+ *
+ * - the row — face · name · chevron on a 32px button with a hover fill, as
+ *   Ship's top bar draws it. The chevron is 14px, the small-control size.
+ * - `compact` — the face alone, as Peek's top bar draws it: no chevron, no
+ *   padding, and no hover fill, because the face fills the whole control and
+ *   a fill would have nowhere to show.
+ *
+ * What it opens — the menu and everything in it — stays in the app.
+ */
+export interface PersonTriggerProps
+  extends Omit<PersonProps, 'className'>,
+    Omit<ComponentPropsWithRef<'button'>, 'children'> {
+  /** Whether what it opens is open — the row shape holds its hover fill while so. */
+  open?: boolean
+  /** Face only — no chevron, no hover fill. Defaults the face to 36px; the row shape to 22px. */
+  compact?: boolean
+}
+
+export function PersonTrigger({ name, picture, fallback, size, open = false, compact = false, className, ...props }: PersonTriggerProps) {
+  if (compact) {
+    return (
+      <button
+        type="button"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        className={cn('cursor-pointer rounded-full focus:outline-none', className)}
+        {...props}
+      >
+        <Avatar name={name} src={picture} size={size ?? 36} />
+      </button>
+    )
+  }
+  return (
+    <button
+      type="button"
+      aria-haspopup="menu"
+      aria-expanded={open}
+      className={cn(
+        // The size is an arbitrary value (the body-2 token): this list goes through
+        // cn(), and tw-merge silently drops a custom text-{size} once a
+        // text-{colour} follows it. Measured: the name rendered 16px.
+        'flex h-8 cursor-pointer items-center gap-1.5 rounded-md pl-1.5 pr-1.5 text-[14px] leading-[140%] text-text-primary transition-colors hover:bg-bg-hover',
+        open && 'bg-bg-hover',
+        className,
+      )}
+      {...props}
+    >
+      <Person name={name} picture={picture} fallback={fallback} size={size ?? 22} />
+      <IconChevronDown size={14} stroke={1.5} className="shrink-0 text-text-muted" />
+    </button>
+  )
+}

package/src/Property.mdx

@@ -0,0 +1,51 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as PropertyStories from './Property.stories'
+
+<Meta of={PropertyStories} />
+
+# Property
+
+A labelled property — "Status", "Lead", and whatever else a surface
+declares. Two layouts, one component.
+
+<Canvas of={PropertyStories.APanel} />
+
+## When
+
+- **`row`** — a details panel: a 68px `caption` label column that lines
+  the values up into a column of their own. The label reads `secondary` —
+  a property label is content, not a placeholder.
+- **`stacked`** — a rail or form-like column: the label above a
+  full-width control, in the 9px `menu` token, uppercase and
+  letter-spaced, 12px above its content.
+- An empty value is a muted em dash — show the property, not a blank.
+
+<Canvas of={PropertyStories.Stacked} />
+
+## When not
+
+- A **section title** → **SectionLabel** / **SectionHeader**. The stacked
+  label is deliberately not a SectionLabel — a field label and a section
+  title are different voices at different sizes.
+- A labelled **input** in a form → **Field** (label, required mark).
+
+## How
+
+```tsx
+import { Property } from '@estiva-app/ui'
+
+<Property label="Status">
+  <Chip type="success" label="Done" />
+</Property>
+
+<Property label="Assignee" layout="stacked">
+  <Select value={assignee} options={people} onChange={setAssignee} />
+</Property>
+```
+
+Any control sits inside — a Chip, a Person, a Select, plain text (the
+WithControls story shows the pairings).
+
+## Props
+
+<Controls of={PropertyStories.Row} />

package/src/Property.stories.tsx

@@ -0,0 +1,91 @@
+import { useState } from 'react'
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Chip } from './Chip'
+import { Person } from './Person'
+import { Property } from './Property'
+import { Select } from './Select'
+
+/** A labelled property — the 68px label column is what lines the values up. */
+const meta = {
+  title: 'Primitives/Property',
+  component: Property,
+  decorators: [(Story) => <div className="w-[260px]"><Story /></div>],
+  args: { label: 'Status', children: <Chip type="success" label="Done" /> },
+  argTypes: { children: { control: false } },
+} satisfies Meta<typeof Property>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Row: Story = {}
+
+/** A column of rows — the label column keeps the values aligned. */
+export const APanel: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <Property label="Status">
+        <Chip type="success" label="Done" />
+      </Property>
+      <Property label="Lead">
+        <Person name="Ana Duarte" size={16} className="text-[12px] leading-[120%] text-text-primary" />
+      </Property>
+      <Property label="Updated">
+        <span className="text-[12px] leading-[120%] text-text-secondary">2d ago</span>
+      </Property>
+    </div>
+  ),
+}
+
+/** Ship's rail layout: the 9px uppercase label above a full-width value. */
+export const Stacked: Story = {
+  args: {
+    label: 'Assignee',
+    layout: 'stacked',
+    children: <Person name="Ravi Mehta" size={20} className="text-[14px] leading-[140%] text-text-primary" />,
+  },
+}
+
+function ControlsDemo() {
+  const [status, setStatus] = useState('doing')
+  const [owner, setOwner] = useState('ana')
+  return (
+    <div className="flex flex-col gap-4">
+      <Property label="Status" layout="stacked">
+        <Select
+          ariaLabel="Status"
+          value={status}
+          onChange={setStatus}
+          options={[
+            { value: 'todo', label: 'To do' },
+            { value: 'doing', label: 'In progress' },
+            { value: 'done', label: 'Done' },
+          ]}
+        />
+      </Property>
+      <Property label="Owner">
+        <Select
+          ariaLabel="Owner"
+          size="small"
+          value={owner}
+          onChange={setOwner}
+          options={[
+            { value: 'ana', label: 'Ana Duarte' },
+            { value: 'ravi', label: 'Ravi Mehta' },
+          ]}
+        />
+      </Property>
+    </div>
+  )
+}
+
+/** The property holding a control — a full-width Select under a stacked label (the rail), a small one in a row. */
+export const WithControls: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => <ControlsDemo />,
+}
+
+/** No value: the em dash, muted — the same mark Person uses for the unnamed. */
+export const Empty: Story = {
+  args: { label: 'Folder', children: <span className="text-[12px] leading-[120%] text-text-muted">—</span> },
+}

package/src/Property.tsx

@@ -0,0 +1,44 @@
+import type { ReactNode } from 'react'
+import { cn } from './cn'
+
+/**
+ * A labelled property row — "Status", "Lead", and whatever else a page
+ * declares (2026-09-01). Both apps carried one, and they had already
+ * drifted: Peek's label was `text-xs` — a Tailwind default with the wrong
+ * line-height, not the caption token — and Ship's had grown a layout Peek's
+ * lacked. One component, both layouts, the token:
+ *
+ * - `row` — Peek's: a 68px label column that lines the values up into a
+ *   column of their own; `text-secondary` rather than muted because a
+ *   property label is content, not a placeholder.
+ * - `stacked` — Ship's rail: the label above a full-width control. The label
+ *   is the `menu` token (9px / 115% / 500), uppercase and letter-spaced —
+ *   its own voice, deliberately not SectionLabel's (unmerged, Katerina
+ *   2026-09-01). A literal string, not merged, so the token size survives.
+ */
+export interface PropertyProps {
+  label: string
+  layout?: 'row' | 'stacked'
+  children: ReactNode
+  className?: string
+}
+
+export function Property({ label, layout = 'row', children, className }: PropertyProps) {
+  if (layout === 'stacked') {
+    return (
+      // gap-3 — the one label-above-content distance (Katerina, 2026-09-01):
+      // Peek's topic-details sections already sit at 12px, Ship's rail was
+      // 6px, and unifying means the bigger, calmer one.
+      <div className={cn('flex flex-col gap-3', className)}>
+        <span className="text-menu uppercase tracking-[0.08em] text-text-secondary">{label}</span>
+        {children}
+      </div>
+    )
+  }
+  return (
+    <div className={cn('flex items-center gap-2', className)}>
+      <span className="w-[68px] shrink-0 text-caption text-text-secondary">{label}</span>
+      {children}
+    </div>
+  )
+}

package/src/Rail.tsx

@@ -0,0 +1,26 @@
+import type { ReactNode } from 'react'
+import { cn } from './cn'
+
+/**
+ * The icon rail: a 64px strip of RailItems (the shell of Peek's NavRail,
+ * 2026-09-02 — its entries and their routes stayed in the app).
+ *
+ * It has no border and no surface of its own — it stands on the app
+ * background, beside whatever card or column the app draws. Collapsing
+ * is the caller's: the rail does not know about the burger, it only gets
+ * given less room (or none) to stand in. Desktop only.
+ */
+export interface RailProps {
+  /** Names the navigation region for assistive tech. */
+  'aria-label'?: string
+  children: ReactNode
+  className?: string
+}
+
+export function Rail({ 'aria-label': ariaLabel = 'Navigation', children, className }: RailProps) {
+  return (
+    <nav aria-label={ariaLabel} className={cn('flex w-16 shrink-0 flex-col items-start gap-2 px-2 py-3', className)}>
+      {children}
+    </nav>
+  )
+}

package/src/RailItem.mdx

@@ -0,0 +1,50 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as RailItemStories from './RailItem.stories'
+
+<Meta of={RailItemStories} />
+
+# RailItem
+
+One tile of an icon rail: the icon in its hover tile, a 9px label under
+it. **Rail** is its shell — the 64px strip the tiles stand in, with no
+border and no surface of its own.
+
+<Canvas of={RailItemStories.InTheRail} />
+
+## When
+
+- An app whose navigation is a narrow icon strip beside the content, with
+  a handful of top-level places.
+- `active` fills the tile (and some themes give the icon their
+  interactive colour), plus `aria-current="page"`.
+- The rail pairs with the **floating TopBar** (AppShell's `floating`
+  variant): the menu button in the bar's `menu` slot collapses it, the
+  app's name or mark rides in `logo` beside it. Collapsing is the
+  caller's — the rail only gets given less room (or none) to stand in.
+
+## When not
+
+- Entries that need readable labels or counts → **NavItem** in a
+  **Sidebar**.
+- More places than a handful — a rail without room stops being glanceable;
+  use the Sidebar.
+
+## How
+
+```tsx
+import { Rail, RailItem } from '@estiva-app/ui'
+
+<Rail>
+  <RailItem href="#/desk" label="Desk" icon={<IconNote size={16} stroke={1.5} />} active={at('desk')} />
+  <RailItem href="#/people" label="People" icon={<IconUsers size={16} stroke={1.5} />} active={at('people')} />
+</Rail>
+```
+
+- Both render plain anchors and a `nav` region. A router app keeps a thin
+  wrapper per item: compute `active` from the location, intercept the
+  click, navigate.
+- Icons are 16px at stroke 1.5.
+
+## Props
+
+<Controls of={RailItemStories.Default} />

package/src/RailItem.stories.tsx

@@ -0,0 +1,37 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconSquareRounded } from '@tabler/icons-react'
+import { Rail } from './Rail'
+import { RailItem } from './RailItem'
+
+const placeholder = <IconSquareRounded size={16} stroke={1.5} />
+
+const meta = {
+  title: 'Frame/RailItem',
+  component: RailItem,
+  args: { label: 'Item', href: '#', active: false, icon: placeholder },
+  argTypes: { icon: { control: false } },
+} satisfies Meta<typeof RailItem>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const tile = [(Story: () => React.ReactNode) => <div className="w-16">{Story()}</div>]
+
+export const Default: Story = { decorators: tile }
+
+/** Active fills the tile — and some themes give the icon their interactive colour. */
+export const Active: Story = { args: { active: true }, decorators: tile }
+
+/** The Rail shell as it stands in a frame: on the left, full height, tiles at the top. */
+export const InTheRail: Story = {
+  parameters: { layout: 'fullscreen', controls: { disable: true } },
+  render: () => (
+    <div className="flex h-screen bg-bg-base">
+      <Rail>
+        <RailItem href="#" label="Item" icon={placeholder} active />
+        <RailItem href="#" label="Item" icon={placeholder} />
+        <RailItem href="#" label="Item" icon={placeholder} />
+      </Rail>
+    </div>
+  ),
+}

package/src/RailItem.tsx

@@ -0,0 +1,53 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react'
+import { cn } from './cn'
+
+/**
+ * One tile of an icon rail: the icon in its hover tile, a 9px label
+ * under it (Peek's NavItem, 2026-09-02, verbatim — minus the router).
+ *
+ * The original computed its own active state from the route and rendered
+ * a router link; neither belongs in a shared component. This one takes
+ * `active` and renders an anchor — a router app keeps a thin wrapper
+ * that does its own matching and intercepts the click.
+ *
+ * Active is `bg-selected` on the tile — some themes also give the icon
+ * their interactive colour.
+ */
+export interface RailItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'> {
+  href: string
+  /** 16px, stroke 1.5. */
+  icon: ReactNode
+  label: string
+  active?: boolean
+  className?: string
+}
+
+export function RailItem({ href, icon, label, active = false, className, ...props }: RailItemProps) {
+  return (
+    <a
+      href={href}
+      aria-current={active ? 'page' : undefined}
+      className={cn('group flex w-full shrink-0 flex-col items-center gap-0.5 px-2 py-0.5', className)}
+      {...props}
+    >
+      <div
+        className={cn(
+          'flex items-center justify-center rounded-lg p-2 transition-colors',
+          active ? 'bg-bg-selected' : 'group-hover:bg-bg-hover',
+        )}
+      >
+        <span
+          className={cn(
+            'flex items-center transition-colors',
+            active ? 'text-text-primary signal:text-[color:var(--text-interactive)]' : 'text-text-secondary',
+          )}
+        >
+          {icon}
+        </span>
+      </div>
+      <span className={cn('text-center text-[9px] font-medium leading-[115%]', active ? 'text-text-primary' : 'text-text-secondary')}>
+        {label}
+      </span>
+    </a>
+  )
+}

package/src/SearchInput.mdx

@@ -0,0 +1,39 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as SearchInputStories from './SearchInput.stories'
+
+<Meta of={SearchInputStories} />
+
+# SearchInput
+
+An inset field with a hairline border that strengthens on focus, and an
+optional keyboard hint at the right edge.
+
+<Canvas of={SearchInputStories.WithShortcut} />
+
+## When
+
+- Filtering a list, live, above the list it filters.
+- As a **launcher affordance**: keep the input `pointer-events-none` and
+  open your command surface from a click on the surround — the component
+  is the same either way, and `shortcut` shows the way in ("⌘ K").
+
+## When not
+
+- General text entry → **TextInput**.
+- Picking entries from a directory → **ChipInput** or **Select**.
+
+## How
+
+```tsx
+import { SearchInput } from '@estiva-app/ui'
+
+<SearchInput value={query} onChange={(e) => setQuery(e.target.value)} shortcut="⌘ K" />
+```
+
+- The default placeholder is "Search…" — override it with your own.
+- Every native input prop passes through; give it an `aria-label`
+  ("Search") since the placeholder is not a name.
+
+## Props
+
+<Controls of={SearchInputStories.Default} />