@estiva-app/ui 0.1.0 → 0.2.0

package/src/SearchInput.stories.tsx

@@ -0,0 +1,24 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { SearchInput } from './SearchInput'
+
+/** An inset field whose border strengthens on focus; under Signal the shortcut becomes the mono kbd chip. */
+const meta = {
+  title: 'Inputs/SearchInput',
+  component: SearchInput,
+  decorators: [(Story) => <div className="w-[290px]"><Story /></div>],
+} satisfies Meta<typeof SearchInput>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+/** The keyboard hint at the right edge. */
+export const WithShortcut: Story = {
+  args: { shortcut: '⌘ K' },
+}
+
+/** The default placeholder says only "Search…" — the app names what is searched. */
+export const OwnPlaceholder: Story = {
+  args: { placeholder: 'Search documents…', shortcut: '⌘ K' },
+}

package/src/SearchInput.tsx

@@ -0,0 +1,45 @@
+import { type InputHTMLAttributes } from 'react'
+import { cn } from './cn'
+
+/**
+ * Peek's SearchInput (2026-09-01), verbatim: an inset field with a hairline
+ * border that strengthens on focus, and an optional keyboard hint at the
+ * right edge — under Signal, the hint becomes the mono `kbd` chip with the
+ * thicker bottom edge.
+ *
+ * The one product string — Peek's default placeholder "Search Peek..." —
+ * stays in Peek; the default here says only "Search…".
+ *
+ * In Peek's top bar this is a launcher affordance rather than a live field:
+ * the input is `pointer-events-none` and clicking the surround opens the
+ * command launcher. The component is the same either way.
+ */
+export interface SearchInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'className'> {
+  /** A keyboard hint drawn at the right edge, e.g. "⌘ K". */
+  shortcut?: string
+  className?: string
+}
+
+export function SearchInput({ shortcut, className, placeholder = 'Search…', ...props }: SearchInputProps) {
+  return (
+    <div
+      className={cn(
+        'flex gap-2 items-center px-3 py-2 rounded-lg',
+        'bg-bg-inset border border-border-default',
+        'focus-within:border-border-strong transition-colors',
+        className,
+      )}
+    >
+      <input
+        className="flex-1 min-w-0 bg-transparent text-input-value text-text-primary placeholder:text-text-muted outline-none"
+        placeholder={placeholder}
+        {...props}
+      />
+      {shortcut && (
+        <div className="flex items-center justify-center px-1 py-px rounded-sm bg-bg-inset border border-border-strong shrink-0 signal:bg-[rgba(255,255,255,.05)] signal:border-b-2">
+          <span className="text-caption text-text-secondary whitespace-nowrap signal:font-mono signal:text-[10px]">{shortcut}</span>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/SectionHeader.mdx

@@ -0,0 +1,52 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as SectionHeaderStories from './SectionHeader.stories'
+
+<Meta of={SectionHeaderStories} />
+
+# SectionHeader
+
+The 32px row a section starts with: a SectionLabel, an optional collapse
+chevron that makes the whole row the toggle, and actions that appear on
+hover as IconButtons with tooltips.
+
+<Canvas of={SectionHeaderStories.WithActions} />
+
+## When
+
+- A sidebar or panel section that collapses, or that carries its own
+  actions — add, sort, filter.
+- `showActions="always"` keeps the actions visible — for touch, or for a
+  section whose actions are the point.
+
+<Canvas of={SectionHeaderStories.Collapsible} />
+
+## When not
+
+- A title with no chevron and no actions → **SectionLabel** alone.
+- A heading inside a menu → **MenuSection**.
+- Page-level headings → the `h*` type tokens.
+
+## How
+
+```tsx
+import { SectionHeader } from '@estiva-app/ui'
+import { IconPlus } from '@tabler/icons-react'
+
+<SectionHeader
+  title="Sections"
+  chevron
+  isExpanded={expanded}
+  onToggle={() => setExpanded((v) => !v)}
+  actions={[{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: add }]}
+/>
+```
+
+- An action is `{ icon, tooltip, onClick }` — the tooltip doubles as the
+  action's accessible name, and an action's click never also toggles the
+  section.
+- With `chevron`, the whole row is the toggle — no separate hit target to
+  find.
+
+## Props
+
+<Controls of={SectionHeaderStories.Plain} />

package/src/SectionHeader.stories.tsx

@@ -0,0 +1,66 @@
+import { useState } from 'react'
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconPlus, IconSortDescending } from '@tabler/icons-react'
+import { SectionHeader } from './SectionHeader'
+
+/** The 32px row a section starts with. Hover it: the row fills, and its actions appear. */
+const meta = {
+  title: 'Navigation/SectionHeader',
+  component: SectionHeader,
+  decorators: [(Story) => <div className="w-[280px]"><Story /></div>],
+  args: { title: 'Starred', showActions: 'hover' },
+  argTypes: { showActions: { control: 'inline-radio', options: ['hover', 'always'] } },
+} satisfies Meta<typeof SectionHeader>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Plain: Story = {}
+
+/** The chevron makes the whole row the toggle; click it. */
+export const Collapsible: Story = {
+  args: { title: 'Your documents', chevron: true },
+  render: (args) => {
+    const [expanded, setExpanded] = useState(true)
+    return (
+      <div className="flex flex-col gap-1">
+        <SectionHeader {...args} isExpanded={expanded} onToggle={() => setExpanded((v) => !v)} />
+        {expanded &&
+          ['Quarterly plan', 'Reading list'].map((row) => (
+            <div key={row} className="rounded-lg px-2 py-1.5 text-[14px] leading-[140%] text-text-primary hover:bg-bg-hover">
+              {row}
+            </div>
+          ))}
+      </div>
+    )
+  },
+}
+
+/** Peek's add/sort pair, in its original order — revealed on hover, and a click on one never toggles the section. */
+export const WithActions: Story = {
+  args: {
+    title: 'Sections',
+    chevron: true,
+    actions: [
+      { icon: <IconSortDescending size={16} stroke={1.5} />, tooltip: 'Sort by', onClick: () => {} },
+      { icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: () => {} },
+    ],
+  },
+}
+
+/** Actions without the collapse — a fixed section that still offers Add on hover. */
+export const ActionsOnly: Story = {
+  args: {
+    title: 'Pinned',
+    actions: [{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: () => {} }],
+  },
+}
+
+/** The actions held on screen — `showActions="always"` — for a section whose affordance should not hide. */
+export const PersistentActions: Story = {
+  args: {
+    title: 'Pinned',
+    showActions: 'always',
+    actions: [{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: () => {} }],
+  },
+}

package/src/SectionHeader.tsx

@@ -0,0 +1,85 @@
+import { useState, type ReactNode } from 'react'
+import { IconChevronRight } from '@tabler/icons-react'
+import { cn } from './cn'
+import { IconButton } from './IconButton'
+import { SectionLabel } from './SectionLabel'
+
+/**
+ * The 32px row a section starts with (Peek's SectionHeader, 2026-09-01):
+ * a SectionLabel, an optional collapse chevron that makes the whole row the
+ * toggle, and actions that appear only while the row is hovered, as
+ * IconButtons with tooltips.
+ *
+ * One API change from Peek's original, safe because no call site used the
+ * old shape yet: the two hard-wired action slots (add, sort) became
+ * `actions` — the caller brings the icon, the tooltip and the handler; the
+ * header owns the hover reveal and stops the click from also toggling the
+ * section. Peek's add/sort pair is the WithActions story, in its original
+ * order.
+ */
+export interface SectionAction {
+  /** 16px, stroke 1.5. */
+  icon: ReactNode
+  tooltip: string
+  onClick: () => void
+}
+
+export interface SectionHeaderProps {
+  title: string
+  /** Collapsible: draws the chevron and makes the whole row the toggle. */
+  chevron?: boolean
+  isExpanded?: boolean
+  onToggle?: () => void
+  /** Right-aligned, in the order given. */
+  actions?: SectionAction[]
+  /** `hover` reveals the actions only while the row is hovered; `always` keeps them. */
+  showActions?: 'hover' | 'always'
+  className?: string
+}
+
+export function SectionHeader({ title, chevron = false, isExpanded = true, onToggle, actions, showActions = 'hover', className }: SectionHeaderProps) {
+  const [isHovered, setIsHovered] = useState(false)
+
+  return (
+    <div
+      className={cn(
+        'flex h-[32px] items-center justify-between rounded-lg px-2 transition-colors',
+        isHovered && 'bg-bg-hover',
+        chevron && 'cursor-pointer',
+        className,
+      )}
+      onClick={chevron ? onToggle : undefined}
+      onMouseEnter={() => setIsHovered(true)}
+      onMouseLeave={() => setIsHovered(false)}
+    >
+      <div className="flex shrink-0 items-center gap-1">
+        {chevron && (
+          <IconChevronRight
+            size={12}
+            stroke={1.5}
+            className={cn('text-text-secondary transition-transform duration-150', isExpanded && 'rotate-90')}
+          />
+        )}
+        <SectionLabel>{title}</SectionLabel>
+      </div>
+
+      {(showActions === 'always' || isHovered) && actions && actions.length > 0 && (
+        <div className="flex items-center gap-1">
+          {actions.map((action) => (
+            <IconButton
+              key={action.tooltip}
+              tooltip={action.tooltip}
+              aria-label={action.tooltip}
+              onClick={(event) => {
+                event.stopPropagation()
+                action.onClick()
+              }}
+            >
+              {action.icon}
+            </IconButton>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/SectionLabel.mdx

@@ -0,0 +1,42 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as SectionLabelStories from './SectionLabel.stories'
+
+<Meta of={SectionLabelStories} />
+
+# SectionLabel
+
+**The** section-title span. Every section heading — sidebar sections, menu
+headings, panel titles — renders through it, so a change of voice is one
+edit. 12px / 500, primary text; some themes restyle it (the toolbar shows
+how).
+
+<Canvas of={SectionLabelStories.HeadingAList} />
+
+## When
+
+- Titling a group of rows in a sidebar, a panel, a rail.
+- Inside a menu it arrives via **MenuSection** — don't place it there by
+  hand.
+
+## When not
+
+- A heading that also collapses or carries actions → **SectionHeader**.
+- The label above a stacked control → **Property** `stacked` — a field
+  label is a different voice, at a different size, on purpose.
+- Page-level headings → the `h*` type tokens.
+
+## How
+
+```tsx
+import { SectionLabel } from '@estiva-app/ui'
+
+<SectionLabel>Pinned</SectionLabel>
+```
+
+It is a bare span: the caller owns the row it sits in and the spacing
+around it. Read it `secondary` (via `className`) where it labels rather
+than leads — menu headings do.
+
+## Props
+
+<Controls of={SectionLabelStories.Default} />

package/src/SectionLabel.stories.tsx

@@ -0,0 +1,31 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { SectionLabel } from './SectionLabel'
+
+/** Every section title renders through this span — a style change is one edit. Under Signal it becomes the mono uppercase micro-label. */
+const meta = {
+  title: 'Primitives/SectionLabel',
+  component: SectionLabel,
+  args: { children: 'Starred' },
+} satisfies Meta<typeof SectionLabel>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+/** Where it lives: heading a group of rows. */
+export const HeadingAList: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex w-[240px] flex-col gap-1">
+      <div className="flex h-8 items-center px-2">
+        <SectionLabel>Recent</SectionLabel>
+      </div>
+      {['Quarterly plan', 'Reading list', 'Archive'].map((row) => (
+        <div key={row} className="rounded-lg px-2 py-1.5 text-[14px] leading-[140%] text-text-primary hover:bg-bg-hover">
+          {row}
+        </div>
+      ))}
+    </div>
+  ),
+}

package/src/SectionLabel.tsx

@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react'
+import { cn } from './cn'
+
+/**
+ * THE section-title label — every section heading (sidebar sections, menu
+ * headings, panel titles) renders through this span, so a style change is
+ * one edit. Peek's original, verbatim: 12px / 12px / 500, primary text
+ * (Peek's ruling 2026-07-23: labels stay primary), the mono uppercase
+ * micro-label under Signal. Metrics as arbitrary values for the tw-merge
+ * reason the README records.
+ *
+ * Deliberately NOT the same thing as Property's stacked field label (the
+ * 9px `menu`-token one): they were merged for a day and unmerged by
+ * Katerina's ruling (2026-09-01) — a section title and a field label are
+ * different voices, at different sizes, on purpose.
+ */
+export function SectionLabel({ children, className }: { children: ReactNode; className?: string }) {
+  return (
+    <span
+      className={cn(
+        'text-[12px] leading-[12px] font-medium text-text-primary signal:font-mono signal:text-[10px] signal:uppercase signal:tracking-[0.14em]',
+        className,
+      )}
+    >
+      {children}
+    </span>
+  )
+}

package/src/Select.fit.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest'
+import { fitMenu } from './Select'
+
+/**
+ * The Select menu's viewport geometry (Katerina, 2026-09-01): the files-panel
+ * picker was cut off at the right edge, its tail ran past the bottom of the
+ * screen, and it could not be scrolled. `fitMenu` is the pure half of the
+ * fix; these pin its decisions.
+ */
+const viewport = { width: 1280, height: 800 }
+
+describe('fitMenu', () => {
+  it('leaves a comfortable menu exactly where the trigger put it', () => {
+    const fit = fitMenu({
+      anchor: { left: 100, top: 200, bottom: 232 },
+      menu: { width: 240, contentHeight: 180 },
+      viewport,
+    })
+    expect(fit.left).toBe(100)
+    expect(fit.top).toBe(236)
+    expect(fit.bottom).toBeUndefined()
+    expect(fit.maxHeight).toBe(288) // room to spare — the cap is the only limit
+  })
+
+  it('clamps a menu that would run off the right edge (the files-panel cut)', () => {
+    const fit = fitMenu({
+      anchor: { left: 1200, top: 200, bottom: 232 },
+      menu: { width: 340, contentHeight: 180 },
+      viewport,
+    })
+    // 1280 - 340 - 8 margin: fully on screen, margin kept.
+    expect(fit.left).toBe(932)
+  })
+
+  it('never pushes a menu past the LEFT edge either', () => {
+    const fit = fitMenu({
+      anchor: { left: -20, top: 200, bottom: 232 },
+      menu: { width: 240, contentHeight: 180 },
+      viewport,
+    })
+    expect(fit.left).toBe(8)
+  })
+
+  it('caps height to the room below, so the last option is never off screen', () => {
+    const fit = fitMenu({
+      anchor: { left: 100, top: 560, bottom: 592 },
+      menu: { width: 240, contentHeight: 200 },
+      viewport,
+    })
+    // Room below = 800 - 592 - 4 gap - 8 margin = 196 < content 200 …but the
+    // room above (548) is not better than needed-below comparison? It is —
+    // openUp triggers only when below < min(content, cap) AND above > below.
+    // Here above (548) > below (196), content 200 > 196 → opens upward.
+    expect(fit.bottom).toBe(800 - 560 + 4)
+    expect(fit.maxHeight).toBe(288)
+  })
+
+  it('opens upward when the room above is better (the low trigger)', () => {
+    const fit = fitMenu({
+      anchor: { left: 100, top: 700, bottom: 732 },
+      menu: { width: 240, contentHeight: 400 },
+      viewport,
+    })
+    expect(fit.top).toBeUndefined()
+    expect(fit.bottom).toBe(800 - 700 + 4) // anchored to the trigger's top
+    expect(fit.maxHeight).toBe(288) // still capped
+  })
+
+  it('stays below when the room below is bad but the room above is worse', () => {
+    const fit = fitMenu({
+      anchor: { left: 100, top: 60, bottom: 92 },
+      menu: { width: 240, contentHeight: 400 },
+      viewport,
+    })
+    expect(fit.top).toBe(96)
+    // Room below = 800 - 92 - 12 = 696 ≥ cap → full cap available.
+    expect(fit.maxHeight).toBe(288)
+  })
+
+  it('keeps a 120px floor in a cramped corner — scrollable beats invisible', () => {
+    const fit = fitMenu({
+      anchor: { left: 100, top: 740, bottom: 772 },
+      menu: { width: 240, contentHeight: 400 },
+      viewport: { width: 1280, height: 800 },
+    })
+    expect(fit.maxHeight).toBeGreaterThanOrEqual(120)
+  })
+
+  it('caps a long list at 288 with plenty of room — the old max-h-72', () => {
+    const fit = fitMenu({
+      anchor: { left: 100, top: 100, bottom: 132 },
+      menu: { width: 240, contentHeight: 900 },
+      viewport,
+    })
+    expect(fit.maxHeight).toBe(288)
+  })
+})

package/src/Select.mdx

@@ -0,0 +1,71 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as SelectStories from './Select.stories'
+
+<Meta of={SelectStories} />
+
+# Select
+
+One value for a form field: a button that shows the choice and opens a
+portalled listbox under itself. The list keeps itself on screen — clamped
+to the viewport's sides, height capped to the room it actually has,
+opening upward when the room below is worse — so it works in cramped
+corners and scrolling panels.
+
+<Canvas of={SelectStories.Default} />
+
+## When
+
+- A field with one answer out of a known set: a status, a stage, a person.
+- Options may carry a `leading` node — a face beside a name — shown in the
+  trigger and the list alike.
+- Two sizes; `small` for dense rows and rails (it sits well inside
+  **Property**).
+
+<Canvas of={SelectStories.WithLeading} />
+
+## When not
+
+- A list of actions → **Menu** — a Select changes a value, it does not do
+  things.
+- Several values → **ChipInput**.
+- Switching views of one thing → **Tabs**.
+- `disabled` explains nothing by itself — wrap it in a **WithTooltip**
+  that gives the reason.
+
+## How
+
+```tsx
+import { Select } from '@estiva-app/ui'
+
+<Select
+  value={status}
+  onChange={setStatus}
+  options={[
+    { value: 'open', label: 'Open' },
+    { value: 'done', label: 'Done' },
+  ]}
+  ariaLabel="Status"
+/>
+```
+
+- The trigger truncates long labels instead of stretching its row — give
+  it room with your layout, not with `white-space` tricks.
+- Its geometry is pure and tested (`fitMenu`): 288px cap, 120px floor —
+  scrollable beats invisible.
+
+## Keys
+
+| Input | What happens |
+|---|---|
+| Enter / Space / click, closed | opens the list |
+| ↑ / ↓ | move the active option, kept scrolled into view |
+| Home / End | jump to the first / last option |
+| Enter / Space, open | picks the active option |
+| Escape | closes, returns focus to the trigger |
+| Tab | closes |
+| click outside | closes |
+| page scroll or resize | closes (the list is fixed where the trigger was) — the list's **own** scroll never dismisses it |
+
+## Props
+
+<Controls of={SelectStories.Default} />

package/src/Select.stories.tsx

@@ -105,3 +105,98 @@ export const LongLabels: Story = {
 export const ManyOptions: Story = {
   render: (args) => <Demo {...args} initial="p3" options={Array.from({ length: 20 }, (_, i) => ({ value: `p${i}`, label: `Project ${i + 1}` }))} />,
 }
+
+/**
+ * The files-panel bug, reproduced (Katerina, 2026-09-01): a trigger in the
+ * bottom-right corner with a long people list. The menu used to run off the
+ * right edge, past the bottom, and close itself on its own scroll. Now it
+ * clamps to the viewport, opens upward when the room below is worse, and
+ * scrolls — open it and try the wheel and the arrow keys.
+ */
+export const CorneredBottomRight: Story = {
+  parameters: { layout: 'fullscreen' },
+  render: (args) => (
+    <div className="h-[560px]">
+      {/* `fixed`, escaping the meta decorator's 360px column: the point is the
+          REAL viewport corner, where both clamps have to earn their keep. */}
+      <div className="fixed bottom-6 right-2 w-[240px]">
+        <Demo
+          {...args}
+          size="small"
+          initial=""
+          placeholder="Unassigned"
+          options={[
+            { value: '', label: 'Unassigned' },
+            ...[
+              'Claude (steered by Katerina Kelepouri)',
+              'Claude (steered by Miky)',
+              'Handle probe',
+              'Katerina Kelepouri',
+              'Miky',
+              'PC (steered by Katerina Kelepouri)',
+              'PEEK-72 renamed',
+              'Relay Operator',
+              'Amie Miles',
+              'Alice Johnson',
+              'Daniel Stanton',
+              'Greg Bothman',
+            ].map((name, i) => ({
+              value: `p${i}`,
+              label: name,
+              leading: <Avatar name={name} size={16} />,
+            })),
+          ]}
+        />
+      </div>
+    </div>
+  ),
+}
+
+/** The same list from a trigger high on screen — stays below, capped, scrollable. */
+export const LongPeopleList: Story = {
+  render: (args) => (
+    <Demo
+      {...args}
+      initial=""
+      placeholder="Unassigned"
+      options={[
+        { value: '', label: 'Unassigned' },
+        ...Array.from({ length: 18 }, (_, i) => ({
+          value: `p${i}`,
+          label: `Person ${i + 1}`,
+          leading: <Avatar name={`Person ${i + 1}`} size={16} />,
+        })),
+      ]}
+    />
+  ),
+}
+
+
+/**
+ * A long label in a labelled property row (Katerina, 2026-09-01): the trigger
+ * used to size to its content and shove the row past its card. `min-w-0
+ * max-w-full` lets the flex row shrink it, so the label truncates instead.
+ */
+export const LongLabelInPropertyRow: Story = {
+  render: (args) => (
+    <div className="w-[300px] rounded-lg border border-border-subtle p-3">
+      <div className="flex items-center gap-2">
+        <span className="w-[68px] shrink-0 text-xs text-text-secondary">Lead</span>
+        <Demo
+          {...args}
+          size="small"
+          className="w-auto"
+          initial="claude"
+          options={[
+            { value: '', label: 'Unassigned' },
+            {
+              value: 'claude',
+              label: 'Claude (steered by Katerina Kelepouri)',
+              leading: <Avatar name="Claude K" size={16} />,
+            },
+          ]}
+        />
+      </div>
+    </div>
+  ),
+}