@estiva-app/ui 0.1.0 → 0.3.0

package/src/Select.tsx

@@ -1,5 +1,5 @@
 import { IconCheck, IconChevronDown } from '@tabler/icons-react'
-import { useCallback, useEffect, useId, useMemo, useRef, useState, type KeyboardEvent, type ReactNode } from 'react'
+import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type KeyboardEvent, type ReactNode } from 'react'
 import { createPortal } from 'react-dom'
 import { cn } from './cn'
 
@@ -8,11 +8,17 @@ import { cn } from './cn'
  * carry a `leading` node — an avatar beside a person's name — shown in the
  * trigger and in the list.
  *
- * A button that opens a portalled listbox under itself: arrows move, Home
- * and End jump, Enter and Space pick, Escape closes and returns focus to the
- * trigger, Tab closes, a click outside closes, a scroll or resize closes
- * (the list is fixed to where the trigger was). Two sizes; `disabled`
- * explains nothing by itself — wrap it in a tooltip that does.
+ * A button that opens a portalled listbox under itself: arrows move (and keep
+ * the active option scrolled into view), Home and End jump, Enter and Space
+ * pick, Escape closes and returns focus to the trigger, Tab closes, a click
+ * outside closes, a PAGE scroll or resize closes (the list is fixed to where
+ * the trigger was) — a scroll *inside* the list is the list's own business
+ * and must not dismiss it. The menu keeps itself on screen: clamped to the
+ * viewport's sides, height capped to the space it actually has, opening
+ * upward when the room below is worse than the room above (Katerina,
+ * 2026-09-01 — the files-panel picker was cut right and bottom, and its own
+ * scroll closed it). Two sizes; `disabled` explains nothing by itself — wrap
+ * it in a tooltip that does.
  */
 export interface SelectOption {
   value: string
@@ -32,11 +38,52 @@ export interface SelectProps {
   className?: string
 }
 
+/**
+ * Where a menu of this size goes, given its anchor and the viewport — pure,
+ * so the geometry is testable without a browser.
+ *
+ * Left is clamped inside the viewport with an 8px margin. Height is capped
+ * at 288px (the old `max-h-72`) but never taller than the space it opens
+ * into; when the room below the anchor is smaller than both the content and
+ * the room above, the menu opens UPWARD (anchored to the trigger's top via
+ * `bottom`). The 120px floor keeps a menu usable even in a cramped corner —
+ * scrollable beats invisible.
+ */
+export function fitMenu({
+  anchor,
+  menu,
+  viewport,
+}: {
+  anchor: { left: number; top: number; bottom: number }
+  menu: { width: number; contentHeight: number }
+  viewport: { width: number; height: number }
+}): { left: number; top?: number; bottom?: number; maxHeight: number } {
+  const MARGIN = 8
+  const GAP = 4
+  const CAP = 288
+  const left = Math.max(MARGIN, Math.min(anchor.left, viewport.width - menu.width - MARGIN))
+  const below = viewport.height - anchor.bottom - GAP - MARGIN
+  const above = anchor.top - GAP - MARGIN
+  const openUp = below < Math.min(menu.contentHeight, CAP) && above > below
+  const maxHeight = Math.max(Math.min(CAP, openUp ? above : below), 120)
+  return openUp
+    ? { left, bottom: viewport.height - anchor.top + GAP, maxHeight }
+    : { left, top: anchor.bottom + GAP, maxHeight }
+}
+
 export function Select({ value, onChange, options, size = 'default', ariaLabel, placeholder = 'Select…', disabled, className }: SelectProps) {
   const id = useId()
   const triggerRef = useRef<HTMLButtonElement>(null)
   const menuRef = useRef<HTMLDivElement>(null)
   const [rect, setRect] = useState<DOMRect | null>(null)
+  /** Where the menu actually goes — measured against the viewport after the
+   *  provisional render, so it is never cut off by an edge. */
+  const [placement, setPlacement] = useState<{
+    left: number
+    top?: number
+    bottom?: number
+    maxHeight: number
+  } | null>(null)
   const open = rect !== null
 
   const selectedIndex = useMemo(() => Math.max(0, options.findIndex((o) => o.value === value)), [options, value])
@@ -52,6 +99,39 @@ export function Select({ value, onChange, options, size = 'default', ariaLabel,
     setRect(triggerRef.current?.getBoundingClientRect() ?? null)
   }, [selectedIndex])
 
+  /*
+   * Fit the menu to the viewport, before paint.
+   *
+   * The provisional render sits at the trigger's corner and is invisible;
+   * this measures it and decides the real box: left clamped inside the
+   * viewport, height capped to the space available, and the whole thing
+   * opening UPWARD when the room below is smaller than both the content and
+   * the room above. A menu that is always fully on screen is also the only
+   * kind whose scrollbar can actually be used.
+   */
+  useLayoutEffect(() => {
+    if (!rect || !menuRef.current) {
+      setPlacement(null)
+      return
+    }
+    setPlacement(
+      fitMenu({
+        anchor: { left: rect.left, top: rect.top, bottom: rect.bottom },
+        menu: { width: menuRef.current.offsetWidth, contentHeight: menuRef.current.scrollHeight },
+        viewport: { width: window.innerWidth, height: window.innerHeight },
+      }),
+    )
+  }, [rect, options.length])
+
+  // Keyboard follows the highlight: without this, arrowing past the fold
+  // moved `activeIndex` into rows the capped menu never showed.
+  useEffect(() => {
+    if (!open) return
+    // Optional call: jsdom implements neither scrolling nor this method, and
+    // a consumer's component tests should not crash for a scroll nicety.
+    document.getElementById(`${id}-${activeIndex}`)?.scrollIntoView?.({ block: 'nearest' })
+  }, [open, activeIndex, id])
+
   // Outside click and Escape — the two exits every menu has. `mousedown`
   // rather than `click`, so a press that starts outside dismisses at once.
   useEffect(() => {
@@ -61,14 +141,24 @@ export function Select({ value, onChange, options, size = 'default', ariaLabel,
       if (triggerRef.current?.contains(e.target as Node)) return
       setRect(null)
     }
-    const onMove = () => setRect(null)
+    const onResize = () => setRect(null)
+    /*
+     * A PAGE scroll moves the anchor out from under the fixed menu, so it
+     * closes. A scroll INSIDE the menu is the menu working as designed —
+     * capture phase sees those too, and closing on them made the list
+     * impossible to scroll at all (the bug this comment survives to prevent).
+     */
+    const onScroll = (e: Event) => {
+      if (e.target instanceof Node && menuRef.current?.contains(e.target)) return
+      setRect(null)
+    }
     document.addEventListener('mousedown', onDown)
-    window.addEventListener('resize', onMove)
-    window.addEventListener('scroll', onMove, true)
+    window.addEventListener('resize', onResize)
+    window.addEventListener('scroll', onScroll, true)
     return () => {
       document.removeEventListener('mousedown', onDown)
-      window.removeEventListener('resize', onMove)
-      window.removeEventListener('scroll', onMove, true)
+      window.removeEventListener('resize', onResize)
+      window.removeEventListener('scroll', onScroll, true)
     }
   }, [open])
 
@@ -133,9 +223,20 @@ export function Select({ value, onChange, options, size = 'default', ariaLabel,
         onClick={() => (open ? close(false) : openMenu())}
         onKeyDown={onKeyDown}
         className={cn(
-          'flex w-full items-center justify-between gap-2 rounded-lg border bg-bg-inset text-left',
+          /*
+           * `min-w-0 max-w-full`: a trigger must never outgrow its container
+           * (Katerina, 2026-09-01 — a long label stretched the files panel's
+           * Lead row past its card). In a flex row the default min-width:auto
+           * forbids shrinking below the label's width, which is what kept
+           * `truncate` from ever engaging; in a block container max-w-full is
+           * the cap. Full-width callers are unaffected.
+           */
+          'flex w-full min-w-0 max-w-full items-center justify-between gap-2 rounded-lg border bg-bg-inset text-left',
           'border-border-default text-text-primary outline-none transition-colors',
-          'hover:border-border-strong disabled:pointer-events-none disabled:bg-bg-disabled disabled:text-text-disabled',
+          // The focused border survives a hover: hover alone strengthens the
+          // hairline, but hover while focused must not grey the focus colour —
+          // the stacked variant outranks plain hover by specificity.
+          'hover:border-border-strong focus-visible:hover:border-border-focus aria-expanded:hover:border-border-focus disabled:pointer-events-none disabled:bg-bg-disabled disabled:text-text-disabled',
           'focus-visible:border-border-focus aria-expanded:border-border-focus',
           'signal:transition-shadow signal:focus-visible:shadow-focus-ring',
           size === 'default' && 'px-3 py-2 text-[14px] leading-[1.4] font-normal',
@@ -158,8 +259,15 @@ export function Select({ value, onChange, options, size = 'default', ariaLabel,
             role="listbox"
             aria-activedescendant={`${id}-${activeIndex}`}
             tabIndex={-1}
-            style={{ top: rect.bottom + 4, left: rect.left, minWidth: rect.width }}
-            className="fixed z-50 max-h-72 overflow-y-auto rounded-lg border border-border-default bg-bg-elevated p-1 shadow-lg"
+            style={
+              placement
+                ? { ...placement, minWidth: rect.width }
+                : // Provisional frame: measured by the layout effect above,
+                  // replaced before paint. Hidden so a cut-off position is
+                  // never visible, not even for a frame.
+                  { top: rect.bottom + 4, left: rect.left, minWidth: rect.width, visibility: 'hidden' }
+            }
+            className="fixed z-50 overflow-y-auto rounded-lg border border-border-default bg-bg-elevated p-1 shadow-lg"
           >
             {options.map((option, index) => (
               <div

package/src/Sidebar.mdx

@@ -0,0 +1,56 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as SidebarStories from './Sidebar.stories'
+
+<Meta of={SidebarStories} />
+
+# Sidebar
+
+The navigation column: 240px, a hairline on its right, the surface behind
+it, scrolling independently of the content beside it. What goes inside is
+the caller's — this is the shell.
+
+<Canvas of={SidebarStories.Composed} />
+
+## When
+
+- The structured frame's navigation (AppShell's `solid` variant), filled
+  with **NavItem** rows — the sidebar pairs with the solid TopBar, as the
+  Rail pairs with the floating one.
+- A labelled group inside it: a **SectionLabel** in a 32px `px-2` row
+  above its rows (the Composed story shows the idiom).
+- It scrolls on its own — a long list never scrolls the frame away.
+
+<Canvas of={SidebarStories.Scrolls} />
+
+## When not
+
+- An icon strip → **Rail**.
+- Sections within a page's content → **SectionHeader** over content, not
+  a second sidebar.
+- Desktop only — there is no narrow-screen drawer; don't improvise one
+  per app.
+
+## How
+
+```tsx
+import { Sidebar, NavItem, SectionLabel } from '@estiva-app/ui'
+
+<Sidebar>
+  <NavItem href="#/documents" label="Documents" active />
+  <div className="mt-2 flex h-8 shrink-0 items-center px-2">
+    <SectionLabel>Collections</SectionLabel>
+  </div>
+  <NavItem href="#/collections/12" label="Quarterly plan" count={7} countLabel="7 open" />
+</Sidebar>
+```
+
+Anything you place directly in the column needs `shrink-0` (the heading
+row above carries it): the column scrolls on overflow, and a flex child
+without it gets compressed instead — rows must keep their height.
+
+It is a `nav` region — pass `aria-label` when "Workspace" is not the
+right name for what it navigates.
+
+## Props
+
+<Controls of={SidebarStories.Composed} />

package/src/Sidebar.stories.tsx

@@ -0,0 +1,50 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconSquareRounded } from '@tabler/icons-react'
+import { NavItem } from './NavItem'
+import { SectionLabel } from './SectionLabel'
+import { Sidebar } from './Sidebar'
+
+const placeholder = <IconSquareRounded size={16} stroke={1.5} />
+
+const meta = {
+  title: 'Frame/Sidebar',
+  component: Sidebar,
+  parameters: { layout: 'fullscreen' },
+  args: { children: null },
+  argTypes: { children: { control: false } },
+  decorators: [(Story) => <div className="flex h-screen bg-bg-base">{Story()}</div>],
+} satisfies Meta<typeof Sidebar>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Entries, then a labelled group — the heading is a SectionLabel in a 32px row. */
+export const Composed: Story = {
+  render: (args) => (
+    <Sidebar {...args}>
+      <NavItem href="#" label="Item one" icon={placeholder} count={18} countLabel="18 open" active />
+      <NavItem href="#" label="Item two" icon={placeholder} count={5} countLabel="5 active" />
+      <div className="mt-2 flex h-8 shrink-0 items-center px-2">
+        <SectionLabel>Group</SectionLabel>
+      </div>
+      <NavItem href="#" label="Item three" count={7} countLabel="7 open" />
+      <NavItem href="#" label="Item four" count={2} countLabel="2 open" />
+      <NavItem href="#" label="Item five" />
+    </Sidebar>
+  ),
+}
+
+/** The column scrolls on its own — a long list never scrolls the frame away. */
+export const Scrolls: Story = {
+  render: (args) => (
+    <Sidebar {...args}>
+      <NavItem href="#" label="Item one" icon={placeholder} count={18} countLabel="18 open" />
+      <div className="mt-2 flex h-8 shrink-0 items-center px-2">
+        <SectionLabel>Group</SectionLabel>
+      </div>
+      {Array.from({ length: 40 }, (_, i) => (
+        <NavItem key={i} href="#" label={`Item ${i + 2}`} active={i === 2} count={((i * 7) % 9) + 1} countLabel={`${((i * 7) % 9) + 1} open`} />
+      ))}
+    </Sidebar>
+  ),
+}

package/src/Sidebar.tsx

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react'
+import { cn } from './cn'
+
+/**
+ * The navigation column: 240px, a hairline on its right, the surface
+ * behind it, scrolling independently of the content beside it (the shell
+ * of Ship's Sidebar, 2026-09-02 — its contents stayed in the app).
+ *
+ * What goes inside is the caller's: NavItem rows, a SectionLabel heading
+ * in a 32px row over a group. Desktop only — there is no narrow-screen
+ * drawer.
+ */
+export interface SidebarProps {
+  /** Names the navigation region for assistive tech. */
+  'aria-label'?: string
+  children: ReactNode
+  className?: string
+}
+
+export function Sidebar({ 'aria-label': ariaLabel = 'Workspace', children, className }: SidebarProps) {
+  return (
+    <nav
+      aria-label={ariaLabel}
+      className={cn(
+        'flex w-60 shrink-0 flex-col gap-px overflow-y-auto border-r border-border-default bg-bg-surface px-2.5 py-3',
+        className,
+      )}
+    >
+      {children}
+    </nav>
+  )
+}

package/src/Skeleton.mdx

@@ -0,0 +1,39 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as SkeletonStories from './Skeleton.stories'
+
+<Meta of={SkeletonStories} />
+
+# Skeleton
+
+The loading placeholder, in generic parts: **SkeletonBar** (the pulsing
+block), **SkeletonRow** (a 32px row — a 16px square and a bar, like a row
+with a face and a name), and **SkeletonList** (rows of varied widths, so
+the placeholder does not read as a pattern).
+
+<Canvas of={SkeletonStories.List} />
+
+## When
+
+- Data is on its way and the shape of what arrives is known — show that
+  shape.
+- A placeholder shaped like your own card is yours to build **from the
+  bar**; the parts here stay ignorant of what they stand for.
+
+## When not
+
+- Nothing is coming → **EmptyState**.
+- A click is being processed → the control's own busy state, not a
+  skeleton.
+
+## How
+
+```tsx
+import { SkeletonList, SkeletonBar } from '@estiva-app/ui'
+
+{loading ? <SkeletonList rows={6} /> : <YourList items={items} />}
+```
+
+- **SkeletonList reveals after 150ms** (`animate-skeleton-in`) — a fast
+  load never flashes a skeleton. Building your own placeholder from the
+  bar? Put that class on its container for the same manner.
+- The list is `aria-hidden` — a placeholder has nothing to read.

package/src/Tabs.mdx

@@ -0,0 +1,53 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as TabsStories from './Tabs.stories'
+
+<Meta of={TabsStories} />
+
+# Tabs
+
+A row of tabs for switching between views of one thing. The selected tab
+is a neutral fill, not the accent — selection is a place, not a highlight.
+
+<Canvas of={TabsStories.WithCounts} />
+
+## When
+
+- Views of the same subject: all / unread / flagged, list / grid.
+- A tab's `count` is a muted mono number after the label, sharing its
+  baseline — the one way a number sits beside a label. A count of `0` is
+  still drawn ("Assigned to me · 0" is an answer); an absent count draws
+  nothing.
+- Two sizes: `default` (14px) and `small` (12px, the denser geometry).
+
+<Canvas of={TabsStories.WithAZero} />
+
+## When not
+
+- Going to a different place → links and **Breadcrumb**.
+- Choosing a value that gets saved → **Select**.
+- Actions → **Button**s; a tab never *does*, it *shows*.
+
+## How
+
+```tsx
+import { Tabs } from '@estiva-app/ui'
+
+<Tabs
+  tabs={[
+    { id: 'all', label: 'All', count: total },
+    { id: 'unread', label: 'Unread', count: unread },
+  ]}
+  active={tab}
+  onChange={setTab}
+/>
+```
+
+- Generic over the id type — `onChange` hands back your union, not a
+  string.
+- It renders `role="tablist"` / `role="tab"` with `aria-selected`;
+  switching is by click (there is no arrow-key roving), and wiring the
+  panels — what shows for the active tab — is the caller's.
+
+## Props
+
+<Controls of={TabsStories.NoCounts} />

package/src/Tabs.stories.tsx

@@ -0,0 +1,91 @@
+import { useState } from 'react'
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconLock } from '@tabler/icons-react'
+import { Tabs, type TabDef } from './Tabs'
+
+/** A row of tabs; the selected one is a neutral fill, never the accent tint. */
+const meta = {
+  title: 'Navigation/Tabs',
+  component: Tabs,
+} satisfies Meta<typeof Tabs>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+function Demo<T extends string>({ tabs, size, initial }: { tabs: TabDef<T>[]; size?: 'default' | 'small'; initial: T }) {
+  const [active, setActive] = useState<T>(initial)
+  return <Tabs tabs={tabs} active={active} onChange={setActive} size={size} />
+}
+
+/** A count is the sidebar's number — mono, muted, tabular — not a chip (Katerina, 2026-09-01). */
+export const WithCounts: Story = {
+  args: { tabs: [], active: 'active', onChange: () => {} },
+  render: () => (
+    <Demo
+      initial="all"
+      tabs={[
+        { id: 'all', label: 'All', count: 12 },
+        { id: 'archived', label: 'Archived', count: 4 },
+      ]}
+    />
+  ),
+}
+
+/** A count of 0 is still drawn — "Flagged 0" is an answer, not an absence. */
+export const WithAZero: Story = {
+  args: { tabs: [], active: 'all', onChange: () => {} },
+  render: () => (
+    <Demo
+      initial="all"
+      tabs={[
+        { id: 'all', label: 'All', count: 31 },
+        { id: 'unread', label: 'Unread', count: 21 },
+        { id: 'flagged', label: 'Flagged', count: 0 },
+      ]}
+    />
+  ),
+}
+
+/** A plain pair — a view switch. */
+export const NoCounts: Story = {
+  args: { tabs: [], active: 'table', onChange: () => {} },
+  render: () => (
+    <Demo
+      initial="list"
+      tabs={[
+        { id: 'list', label: 'List' },
+        { id: 'grid', label: 'Grid' },
+      ]}
+    />
+  ),
+}
+
+/** A leading icon, 16px stroke 1.5 — as Peek draws them. */
+export const WithAnIcon: Story = {
+  args: { tabs: [], active: 'open', onChange: () => {} },
+  render: () => (
+    <Demo
+      initial="open"
+      tabs={[
+        { id: 'open', label: 'Open' },
+        { id: 'locked', label: 'Locked', icon: <IconLock size={16} stroke={1.5} /> },
+      ]}
+    />
+  ),
+}
+
+/** `small` is the 12px geometry. */
+export const Small: Story = {
+  args: { tabs: [], active: 'conversations', onChange: () => {} },
+  render: () => (
+    <Demo
+      size="small"
+      initial="overview"
+      tabs={[
+        { id: 'overview', label: 'Overview' },
+        { id: 'private', label: 'Private', icon: <IconLock size={16} stroke={1.5} /> },
+        { id: 'activity', label: 'Activity' },
+      ]}
+    />
+  ),
+}

package/src/Tabs.tsx

@@ -0,0 +1,73 @@
+import type { ReactNode } from 'react'
+import { cn } from './cn'
+
+/**
+ * A row of tabs. Ship's Tabs (2026-09-01), which was Peek's TopicTabs with
+ * the topic-specific ids taken out.
+ *
+ * A selected tab is a neutral fill (bg-active), not the accent tint —
+ * Katerina's ruling (2026-08-27), extended to every app (2026-09-01). Two
+ * sizes: `default` is 14px, a little more room; `small` is Peek's own
+ * geometry (its inline `fontSize: 12` was the caption token spelled by hand).
+ *
+ * A tab's count is the sidebar's number, not a chip (Katerina, 2026-09-01,
+ * superseding the chip ruling of 2026-08-26): mono, caption size, muted,
+ * tabular — the one way a number sits beside a label everywhere. A count of
+ * `0` is still drawn ("Assigned to me 0" is an answer); an absent count draws
+ * nothing.
+ */
+export interface TabDef<T extends string> {
+  id: T
+  label: string
+  /** Shown as a muted mono number after the label. Absent draws nothing; 0 is drawn. */
+  count?: number
+  /** 16px, stroke 1.5. */
+  icon?: ReactNode
+}
+
+export interface TabsProps<T extends string> {
+  tabs: TabDef<T>[]
+  active: T
+  onChange: (id: T) => void
+  /** `default` 14px; `small` 12px, the denser geometry. */
+  size?: 'default' | 'small'
+  className?: string
+}
+
+export function Tabs<T extends string>({ tabs, active, onChange, size = 'default', className }: TabsProps<T>) {
+  return (
+    <div role="tablist" className={cn('flex items-center gap-2', className)}>
+      {tabs.map((tab) => (
+        <button
+          key={tab.id}
+          type="button"
+          role="tab"
+          aria-selected={active === tab.id}
+          onClick={() => onChange(tab.id)}
+          className={cn(
+            'flex cursor-pointer items-center transition-colors',
+            // Arbitrary sizes (the body-2 and caption tokens): the colour branch below
+            // follows them through cn(), and tw-merge drops a custom text-{size}
+            // once a text-{colour} lands after it. Measured: tabs rendered 16px.
+            // gap: default is Ship's 6px; small keeps Peek's original 4px, or
+            // "small is Peek's geometry" stops being true.
+            size === 'default' ? 'gap-1.5 rounded-md px-2 py-1 text-[14px] leading-[140%]' : 'gap-1 rounded px-1.5 py-0.5 text-[12px] leading-[120%]',
+            active === tab.id ? 'bg-bg-active text-text-primary' : 'text-text-secondary hover:bg-bg-hover',
+          )}
+        >
+          {tab.icon}
+          {/* Label and count share a baseline: a smaller text centred as a box
+              (items-center) floats above the label's baseline — the digits
+              read as riding high. Baseline alignment is what makes two sizes
+              sit on one line. */}
+          <span className="flex items-baseline">
+            {tab.label}
+            {tab.count !== undefined ? (
+              <span className="ml-2.5 font-mono text-caption tabular-nums text-text-secondary">{tab.count}</span>
+            ) : null}
+          </span>
+        </button>
+      ))}
+    </div>
+  )
+}

package/src/TextInput.mdx

@@ -0,0 +1,39 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as TextInputStories from './TextInput.stories'
+
+<Meta of={TextInputStories} />
+
+# TextInput
+
+The single-line field: inset surface, 8px radius, 14px text, the focus
+border in every theme.
+
+<Canvas of={TextInputStories.Filled} />
+
+## When
+
+- One line of text in a form or dialog — a name, a title, a URL. Label it
+  with a **Field**.
+
+## When not
+
+- Several lines → **Textarea**.
+- Filtering a list → **SearchInput**.
+- Editing text where it is displayed → **EditableText**.
+
+## How
+
+```tsx
+import { TextInput } from '@estiva-app/ui'
+
+<TextInput value={name} onChange={(e) => setName(e.target.value)} placeholder="Untitled" />
+```
+
+- It is a native `<input>` with a ref — every native prop passes through.
+- Name it: a Field's label is visual, so give the input an `aria-label`
+  too.
+- `disabled` gets the disabled surface and text; say why with a tooltip.
+
+## Props
+
+<Controls of={TextInputStories.Empty} />

package/src/Textarea.mdx

@@ -0,0 +1,36 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as TextareaStories from './Textarea.stories'
+
+<Meta of={TextareaStories} />
+
+# Textarea
+
+TextInput's look on a multi-line field that does not resize.
+
+<Canvas of={TextareaStories.Filled} />
+
+## When
+
+- Several lines in a form or dialog — a description, a message body. Label
+  it with a **Field**.
+
+## When not
+
+- One line → **TextInput**.
+- Editing text where it is displayed → **EditableText** with `multiline`.
+
+## How
+
+```tsx
+import { Textarea } from '@estiva-app/ui'
+
+<Textarea rows={4} value={text} onChange={(e) => setText(e.target.value)} />
+```
+
+- Resizing is off by design — size it with `rows` or your layout.
+- Native `<textarea>` with a ref; every native prop passes through; give
+  it an accessible name.
+
+## Props
+
+<Controls of={TextareaStories.Empty} />