@estiva-app/ui 0.1.0 → 0.3.0

package/src/AppShell.stories.tsx

@@ -0,0 +1,117 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconMenu2, IconSquareRounded } from '@tabler/icons-react'
+import { AppShell } from './AppShell'
+import { Banner } from './Banner'
+import { EmptyState } from './EmptyState'
+import { IconButton } from './IconButton'
+import { NavItem } from './NavItem'
+import { PersonTrigger } from './PersonTrigger'
+import { Rail } from './Rail'
+import { RailItem } from './RailItem'
+import { SearchInput } from './SearchInput'
+import { Sidebar } from './Sidebar'
+
+const meta = {
+  title: 'Frame/AppShell',
+  component: AppShell,
+  parameters: { layout: 'fullscreen' },
+  args: { nav: null, children: null },
+  argTypes: {
+    variant: { control: 'inline-radio', options: ['solid', 'floating'] },
+    menu: { control: false },
+    logo: { control: false },
+    search: { control: false },
+    identity: { control: false },
+    banner: { control: false },
+    nav: { control: false },
+    children: { control: false },
+  },
+  decorators: [(Story) => <div className="h-screen overflow-hidden">{Story()}</div>],
+} satisfies Meta<typeof AppShell>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const identity = <PersonTrigger name="Ana Duarte" />
+const menuButton = (
+  <IconButton tooltip="Toggle menu" tooltipPlacement="bottom" aria-label="Toggle menu">
+    <IconMenu2 size={16} stroke={1.5} />
+  </IconButton>
+)
+
+const placeholder = <IconSquareRounded size={16} stroke={1.5} />
+
+const sidebar = (
+  <Sidebar>
+    <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" />
+  </Sidebar>
+)
+
+const rail = (
+  <Rail>
+    <RailItem href="#" label="Item" icon={placeholder} active />
+    <RailItem href="#" label="Item" icon={placeholder} />
+    <RailItem href="#" label="Item" icon={placeholder} />
+  </Rail>
+)
+
+/** The structured frame: solid bar, sidebar, content beside it. */
+export const Solid: Story = {
+  render: (args) => (
+    <AppShell {...args} logo="Estiva" search={<SearchInput shortcut="⌘ K" className="w-[290px]" />} identity={identity} nav={sidebar}>
+      <div className="flex h-full items-center justify-center">
+        <EmptyState message="Nothing here yet." />
+      </div>
+    </AppShell>
+  ),
+}
+
+/** The banner belongs to the content area — at its top, never across the navigation. */
+export const SolidWithBanner: Story = {
+  render: (args) => (
+    <AppShell {...args} logo="Estiva" identity={identity} nav={sidebar} banner={<Banner tone="ok">Public key copied.</Banner>}>
+      <div className="flex h-full items-center justify-center">
+        <EmptyState message="Nothing here yet." />
+      </div>
+    </AppShell>
+  ),
+}
+
+/** The floating frame: the bar floats over the top edge, the rail stands on the background, and the content lives in the rounded card. */
+export const Floating: Story = {
+  render: (args) => (
+    <AppShell
+      {...args}
+      variant="floating"
+      menu={menuButton}
+      logo="Estiva"
+      search={<SearchInput shortcut="⌘ K" className="w-[290px]" />}
+      identity={identity}
+      nav={rail}
+    >
+      <div className="flex h-full items-center justify-center">
+        <EmptyState message="Nothing here yet." />
+      </div>
+    </AppShell>
+  ),
+}
+
+/** In the floating frame the banner draws inside the card, at its top. */
+export const FloatingWithBanner: Story = {
+  render: (args) => (
+    <AppShell
+      {...args}
+      variant="floating"
+      menu={menuButton}
+      logo="Estiva"
+      identity={identity}
+      nav={rail}
+      banner={<Banner tone="info">A new version is available. Reload when convenient.</Banner>}
+    >
+      <div className="flex h-full items-center justify-center">
+        <EmptyState message="Nothing here yet." />
+      </div>
+    </AppShell>
+  ),
+}

package/src/AppShell.tsx

@@ -0,0 +1,77 @@
+import type { ReactNode } from 'react'
+import { cn } from './cn'
+import { TopBar } from './TopBar'
+
+/**
+ * The frame of an app, in the two manners that pair with the TopBar's
+ * (Katerina, 2026-09-02: the two shells go together — the solid bar with
+ * the sidebar, the floating bar with the rail):
+ *
+ * - `solid` — the structured frame: a solid TopBar, the navigation
+ *   column, the content beside it, sidebar and main scrolling
+ *   independently (2026-09-02, verbatim from the structured app).
+ * - `floating` — the floating frame: the TopBar floats over the top
+ *   edge, the rail stands on the app background, and the content lives
+ *   in the rounded card beside it (2026-09-02, the floating app's frame
+ *   geometry; its collapse animation and launcher stay in the app).
+ *
+ * The banner belongs to the content area (her ruling, 2026-09-02): it
+ * renders at the top of the main column — inside the card, in the
+ * floating manner — never across the navigation.
+ *
+ * Layout only. What goes in each region is the caller's; this component
+ * has no data and no routes.
+ */
+export interface AppShellProps {
+  variant?: 'solid' | 'floating'
+  /** The top bar's menu button, in an app whose navigation collapses. */
+  menu?: ReactNode
+  /** The top bar's left: the app's logo mark, or its name as text. */
+  logo?: ReactNode
+  /** The top bar's centre — a search field, when there is one. */
+  search?: ReactNode
+  /** The top bar's right cluster — an `IdentityMenu`. */
+  identity?: ReactNode
+  /** A `Banner`, or nothing — drawn at the top of the content area. */
+  banner?: ReactNode
+  /** The navigation: a `Sidebar` in the solid manner, a `Rail` in the floating one. */
+  nav: ReactNode
+  children: ReactNode
+}
+
+export function AppShell({ variant = 'solid', menu, logo, search, identity, banner, nav, children }: AppShellProps) {
+  const bar = <TopBar variant={variant} menu={menu} logo={logo} search={search} right={identity} />
+
+  if (variant === 'floating') {
+    return (
+      <div className="relative h-full min-h-0 overflow-hidden bg-bg-base">
+        {bar}
+        <div className="flex h-full pb-4 pr-4 pt-[52px]">
+          {nav}
+          <div
+            className={cn(
+              'flex min-w-0 flex-1 flex-col overflow-hidden rounded-2xl bg-bg-surface',
+              'signal:border signal:border-border-subtle signal:shadow-[inset_0_1px_0_rgba(255,255,255,0.035)]',
+            )}
+          >
+            {banner}
+            <main className="flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden">{children}</main>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-bg-base text-text-primary">
+      {bar}
+      <div className="flex min-h-0 flex-1">
+        {nav}
+        <div className="flex min-h-0 min-w-0 flex-1 flex-col">
+          {banner}
+          <main className="min-w-0 flex-1 overflow-y-auto">{children}</main>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/Avatar.initials.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest'
+import { initialsFor } from './Avatar'
+
+describe('initialsFor', () => {
+  it('takes the first letter of the first two words', () => {
+    expect(initialsFor('Ana Duarte')).toBe('AD')
+  })
+
+  it('gives a single-word name a single letter', () => {
+    expect(initialsFor('Yael')).toBe('Y')
+  })
+
+  it('never shows a symbol — a parenthetical name gets one letter', () => {
+    // The bot rendered "C(" in the members pill (Katerina, 2026-09-01).
+    expect(initialsFor('Claude (steered by Katerina Kelepouri)')).toBe('C')
+  })
+
+  it('falls back to the first character when no word starts with a letter', () => {
+    expect(initialsFor('(bot)')).toBe('(')
+  })
+})

package/src/Avatar.mdx

@@ -0,0 +1,49 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as AvatarStories from './Avatar.stories'
+
+<Meta of={AvatarStories} />
+
+# Avatar
+
+A person's face: their picture, or their initials on a colour that is
+theirs, or — when there is no name to take initials from — a silhouette.
+
+<Canvas of={AvatarStories.Sizes} />
+
+## When
+
+- Anywhere a person appears at a glance: a row, a card, a picker, a byline.
+- The scale is 16 · 24 · 32 · 36 (default) — pick from it rather than
+  inventing sizes.
+
+## When not
+
+- Several people at once → **AvatarGroup**.
+- The face beside the name → **Person**.
+- The face as a button that opens a menu → **PersonTrigger**.
+
+## How
+
+```tsx
+import { Avatar } from '@estiva-app/ui'
+
+<Avatar name={person.name} src={person.picture} size={24} />
+```
+
+- The caller resolves `src`. A picture that fails to load falls back to the
+  initials — nothing to handle.
+- Initials come from a **name, never a key**: the first letter of the first
+  two words, skipping words that open with a symbol. An unnamed person is
+  the silhouette, not a `?` — a question mark reads as an error badge.
+- The colour behind initials is per person, chosen from the name, the same
+  everywhere they appear. It is a fallback palette, not a token — themes
+  have no say in it.
+- The corner is `rounded-sm` and stays that way. A surface that wants
+  rounder geometry wraps the Avatar concentrically — it does not override
+  the Avatar's own radius.
+
+<Canvas of={AvatarStories.Palette} />
+
+## Props
+
+<Controls of={AvatarStories.Initials} />

package/src/Avatar.tsx

@@ -31,14 +31,17 @@ export const hueFor = (key: string) => {
   return HUES[Math.abs(h) % HUES.length]
 }
 
-/** Peek's rule: the first letter of the first two words. */
-export const initialsFor = (name: string) =>
-  name
-    .split(' ')
-    .map((w) => w[0])
-    .slice(0, 2)
-    .join('')
-    .toUpperCase()
+/**
+ * Peek's rule, sharpened: the first letter of the first two words — counting
+ * only words that begin with a letter or digit, so "Claude (steered by
+ * Katerina Kelepouri)" shows "C", never "C(" (Katerina, 2026-09-01: a name
+ * carrying such symbols gets a single letter rather than one of them).
+ */
+export const initialsFor = (name: string) => {
+  const words = name.split(/\s+/).slice(0, 2).filter((w) => /^[\p{L}\p{N}]/u.test(w))
+  const initials = words.map((w) => w[0]).join('') || name.trim().charAt(0)
+  return initials.toUpperCase()
+}
 
 export interface AvatarProps {
   /** The picture URL, resolved by the caller. A picture that fails to load falls back to the initials. */
@@ -47,7 +50,7 @@ export interface AvatarProps {
   name?: string
   /** Alt text for the picture; the name when absent. Also the initials' source when there is no name. */
   alt?: string
-  /** Pixels. Peek's scale: 16 · 24 · 32 · 36 (default). */
+  /** Pixels. The scale: 16 · 24 · 32 · 36 (default). */
   size?: number
   className?: string
 }

package/src/AvatarGroup.mdx

@@ -0,0 +1,39 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as AvatarGroupStories from './AvatarGroup.stories'
+
+<Meta of={AvatarGroupStories} />
+
+# AvatarGroup
+
+Up to three overlapping 24px faces with a surface-coloured ring — the
+member stack for anywhere a group is shown at a glance.
+
+<Canvas of={AvatarGroupStories.OverflowShowsThree} />
+
+## When
+
+- A compact "who's in this" — a members pill, a row's participants, a
+  card's crew. More than three members still draws three; the caller says
+  the count elsewhere if it matters.
+
+## When not
+
+- One person → **Avatar**.
+- Names need to be readable → a list of **Person** rows.
+
+## How
+
+```tsx
+import { AvatarGroup } from '@estiva-app/ui'
+
+<AvatarGroup members={people.map((p) => ({ name: p.name, picture: p.picture }))} />
+```
+
+- A member is a `name` plus an optional `picture` URL, resolved by the
+  caller — exactly as Avatar takes its `src`. No picture draws initials.
+- The ring rides on the Avatar itself (one box); don't wrap each face in a
+  clipping window — a window minus a border crops the initials.
+
+## Props
+
+<Controls of={AvatarGroupStories.ThreeMembers} />

package/src/AvatarGroup.stories.tsx

@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { AvatarGroup } from './AvatarGroup'
+
+const meta = {
+  title: 'Primitives/AvatarGroup',
+  component: AvatarGroup,
+  args: {
+    members: [{ name: 'Ana Duarte' }, { name: 'Ravi Mehta' }, { name: 'Marta Silva' }],
+  },
+} satisfies Meta<typeof AvatarGroup>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const ThreeMembers: Story = {}
+export const TwoMembers: Story = {
+  args: { members: [{ name: 'Ana Duarte' }, { name: 'Ravi Mehta' }] },
+}
+export const One: Story = {
+  args: { members: [{ name: 'Ana Duarte' }] },
+}
+
+/** Five members, three faces — the stack never grows past three. */
+export const OverflowShowsThree: Story = {
+  args: {
+    members: [
+      { name: 'Ana Duarte' },
+      { name: 'Ravi Mehta' },
+      { name: 'Marta Silva' },
+      { name: 'Jonas Weber' },
+      { name: 'Lea Novak' },
+    ],
+  },
+}
+
+/**
+ * Inside a members pill with the total count — the shape a conversation
+ * header draws over the stack. The pill is the caller's; this is the group
+ * doing its job in one.
+ */
+export const InMembersPill: Story = {
+  args: {
+    members: [
+      { name: 'Ana Duarte' },
+      { name: 'Ravi Mehta' },
+      { name: 'Marta Silva' },
+      { name: 'Jonas Weber' },
+    ],
+  },
+  render: (args) => (
+    <div className="bg-bg-elevated border border-border-default rounded-sm flex gap-2 items-center pl-[2px] pr-2 py-[2px] w-fit">
+      <AvatarGroup {...args} />
+      <span className="text-caption text-text-secondary">{args.members.length}</span>
+    </div>
+  ),
+}

package/src/AvatarGroup.tsx

@@ -0,0 +1,42 @@
+import { Avatar } from './Avatar'
+
+/**
+ * Up to three overlapping 24px faces with a `bg-surface` ring — Peek's member
+ * stack (2026-09-01), with one generalisation on the way in: a member is a
+ * name plus an optional picture URL, resolved by the caller, exactly as
+ * Avatar takes its `src`. Peek's version took bare names because its Avatar
+ * wrapper resolves pictures itself; a consumer without such a wrapper could
+ * never have shown one.
+ *
+ * The ring sits on the Avatar itself: the old extra wrapper was a 24px
+ * window minus a 2px border with a fixed 24px Avatar inside, so
+ * overflow-hidden clipped 4px of face — and the right edge of the initials
+ * with it, which is how "CO" rendered as "C(". One box, whole letters.
+ */
+export interface AvatarGroupMember {
+  name: string
+  /** Resolved by the caller. Absent draws the initials. */
+  picture?: string
+}
+
+export interface AvatarGroupProps {
+  members: AvatarGroupMember[]
+}
+
+export function AvatarGroup({ members }: AvatarGroupProps) {
+  const visible = members.slice(0, 3)
+  return (
+    <div className="flex items-center pr-2">
+      {visible.map((member, i) => (
+        <Avatar
+          key={i}
+          size={24}
+          name={member.name}
+          src={member.picture}
+          alt={member.name}
+          className="-mr-2 relative border-2 border-bg-surface"
+        />
+      ))}
+    </div>
+  )
+}

package/src/Banner.mdx

@@ -0,0 +1,45 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as BannerStories from './Banner.stories'
+
+<Meta of={BannerStories} />
+
+# Banner
+
+The strip under the header where the app says something happened: one
+line, one of four tones, gone when there is nothing to say.
+
+<Canvas of={BannerStories.AllTones} />
+
+## When
+
+- The outcome or state of the whole surface: "Public key copied.", the
+  reason the last read failed, a read-only notice.
+- **`ok`** confirms, **`info`** informs, **`warning`** cautions,
+  **`error`** reports a failure — and only `error` announces itself
+  (`role="alert"`); the others are polite (`role="status"`).
+- It belongs to the **content area** — at its top, never across the
+  navigation. AppShell's `banner` slot places it exactly there.
+
+## When not
+
+- Feedback about one action, briefly → **Toast**.
+- A standing property of one thing → **Chip** on that thing.
+- A notice inside the content flow with its own action — that is a
+  different component (not in the package yet).
+
+## How
+
+```tsx
+import { Banner } from '@estiva-app/ui'
+
+{notice && <Banner tone={notice.tone}>{notice.text}</Banner>}
+```
+
+- Render it only while there is something to say — an empty strip is not
+  a state.
+- One line of plain text, `body-2`. If it needs a button or a second
+  line, it has outgrown this component.
+
+## Props
+
+<Controls of={BannerStories.Ok} />

package/src/Banner.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Banner } from './Banner'
+
+const meta = {
+  title: 'Feedback/Banner',
+  component: Banner,
+  parameters: { layout: 'fullscreen' },
+  args: { tone: 'ok', children: 'Public key copied.' },
+  argTypes: { tone: { control: 'inline-radio', options: ['ok', 'error', 'info', 'warning'] } },
+} satisfies Meta<typeof Banner>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Ok: Story = {}
+
+/** An error announces itself (`role="alert"`); the rest are polite. */
+export const Error: Story = { args: { tone: 'error', children: 'The last read failed — reconnecting.' } }
+
+export const Info: Story = { args: { tone: 'info', children: 'A new version is available. Reload when convenient.' } }
+
+export const Warning: Story = { args: { tone: 'warning', children: 'This workspace is read-only until sign-in.' } }
+
+/** All four tones, stacked. */
+export const AllTones: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <Banner tone="ok">Public key copied.</Banner>
+      <Banner tone="info">A new version is available. Reload when convenient.</Banner>
+      <Banner tone="warning">This workspace is read-only until sign-in.</Banner>
+      <Banner tone="error">The last read failed — reconnecting.</Banner>
+    </div>
+  ),
+}

package/src/Banner.tsx

@@ -0,0 +1,35 @@
+import { cn } from './cn'
+
+/**
+ * The strip under the header where the app says something happened —
+ * one line, gone when there is nothing to say (Ship's Banner,
+ * 2026-09-02, verbatim; `info` and `warning` added on extraction,
+ * Katerina's ruling — the semantic set is four everywhere else).
+ *
+ * body-2, her ruling (2026-09-01): the caption this once claimed never
+ * rendered, so 14px is what it has always been and what she kept.
+ * An `error` announces itself (`role="alert"`); the other tones are
+ * polite (`role="status"`).
+ */
+export type BannerTone = 'ok' | 'error' | 'info' | 'warning'
+
+export interface BannerProps {
+  tone: BannerTone
+  children: string
+  className?: string
+}
+
+const TONE: Record<BannerTone, string> = {
+  ok: 'bg-success-muted text-success-default',
+  error: 'bg-error-muted text-error-default',
+  info: 'bg-info-muted text-info-default',
+  warning: 'bg-warning-muted text-warning-default',
+}
+
+export function Banner({ tone, children, className }: BannerProps) {
+  return (
+    <div role={tone === 'error' ? 'alert' : 'status'} className={cn('px-4 py-2 text-body-2', TONE[tone], className)}>
+      {children}
+    </div>
+  )
+}

package/src/Breadcrumb.mdx

@@ -0,0 +1,52 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as BreadcrumbStories from './Breadcrumb.stories'
+
+<Meta of={BreadcrumbStories} />
+
+# Breadcrumb
+
+A trail: where you are, and the way back up. Crumbs, muted slashes
+between them, and a tooltip on any crumb that has had to truncate.
+
+<Canvas of={BreadcrumbStories.OnAnItem} />
+
+## When
+
+- The top of a detail page: parents first, the current place last.
+- A crumb with an `href` is a link — even the last one, when a page ends
+  its trail on somewhere to go. The last item without one is "you are
+  here" (`aria-current="page"`).
+- `mono` sets a crumb in the mono face for a ref or an id — and a mono
+  crumb **never gives up width** to a long name beside it; the name
+  truncates, the ref stays whole.
+
+<Canvas of={BreadcrumbStories.LongName} />
+
+## When not
+
+- Switching between sibling views of one thing → **Tabs**.
+- Just a page title → the `h*` type tokens; a one-item trail says
+  nothing.
+
+## How
+
+```tsx
+import { Breadcrumb } from '@estiva-app/ui'
+
+<Breadcrumb
+  items={[
+    { label: 'Documents', href: '#/documents' },
+    { label: 'Quarterly plan', href: '#/documents/12' },
+    { label: 'DOC-12', mono: true },
+  ]}
+/>
+```
+
+- Truncation is re-measured as the trail resizes; the tooltip appears and
+  disappears with the room the trail actually has. Give the trail a
+  `min-w-0` container so it can truncate at all.
+- The separators are `aria-hidden` — the trail reads as its places.
+
+## Props
+
+<Controls of={BreadcrumbStories.OnAnItem} />

package/src/Breadcrumb.stories.tsx

@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Breadcrumb } from './Breadcrumb'
+
+/** A trail of places, ending where you are — or on a mono ref. */
+const meta = {
+  title: 'Navigation/Breadcrumb',
+  component: Breadcrumb,
+  args: {
+    items: [
+      { label: 'Documents', href: '#' },
+      { label: 'Quarterly plan', href: '#' },
+      { label: 'DOC-12', mono: true },
+    ],
+  },
+} satisfies Meta<typeof Breadcrumb>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const OnAnItem: Story = {}
+
+/** An item with no parent: straight from the list to the ref. */
+export const NoParent: Story = {
+  args: { items: [{ label: 'Documents', href: '#' }, { label: 'DOC-12', mono: true }] },
+}
+
+/** A container page: the last crumb is a plain name, where you are. */
+export const OnAContainer: Story = {
+  args: { items: [{ label: 'Documents', href: '#' }, { label: 'Quarterly plan' }] },
+}
+
+/** A long name truncates; the ref stays. Hover the cut-off crumb to read the whole label — a crumb that fits shows no tooltip. */
+export const LongName: Story = {
+  decorators: [(Story) => <div className="w-[320px]"><Story /></div>],
+  args: {
+    items: [
+      { label: 'Documents', href: '#' },
+      { label: 'Onboarding flow for new workspaces, the whole first ten minutes', href: '#' },
+      { label: 'ONB-12', mono: true },
+    ],
+  },
+}