@estiva-app/ui 0.1.0 → 0.3.0

package/src/EditableText.stories.tsx

@@ -0,0 +1,63 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+import { EditableText } from './EditableText'
+
+const meta = {
+  title: 'Inputs/EditableText',
+  component: EditableText,
+  args: {
+    value: 'Team charter',
+    placeholder: 'Add a title',
+    label: 'Title',
+    onCommit: () => true as boolean,
+    className: 'text-[16px] leading-[1.4] font-medium',
+  },
+  argTypes: { onCommit: { control: false } },
+  decorators: [(Story) => <div className="w-80">{Story()}</div>],
+} satisfies Meta<typeof EditableText>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Click the text: it becomes a field. Enter commits, Escape cancels, blur commits. */
+export const Title: Story = {
+  parameters: { controls: { disable: true } },
+  render: (args) => {
+    const [value, setValue] = useState(args.value)
+    return (
+      <EditableText
+        {...args}
+        value={value}
+        onCommit={(next) => {
+          setValue(next)
+          return true
+        }}
+      />
+    )
+  },
+}
+
+/** Shift+Enter is a new line; Enter still commits. */
+export const Multiline: Story = {
+  args: {
+    value: 'A longer piece of text.\nIt keeps its lines.',
+    placeholder: 'Add a description',
+    label: 'Description',
+    multiline: true,
+    className: 'text-[14px] leading-[1.4]',
+  },
+}
+
+/** Empty shows the placeholder, muted — still clickable. */
+export const Empty: Story = { args: { value: '' } }
+
+/** For a reader who cannot write: the value alone, no edit affordance. */
+export const ReadOnly: Story = { args: { readOnly: true } }
+
+/**
+ * A commit that resolves `false` keeps the field open with the text in it —
+ * an edit is never silently lost. Try committing anything here.
+ */
+export const RefusedCommit: Story = {
+  args: { onCommit: () => false },
+}

package/src/EditableText.tsx

@@ -0,0 +1,169 @@
+import { useEffect, useRef, useState, type KeyboardEvent, type ReactNode, type RefObject } from 'react'
+import { cn } from './cn'
+
+/**
+ * Text you click to edit — Ship's EditableText (2026-09-01), verbatim. Its
+ * own comment always called it a package candidate: nothing here knows what
+ * is being edited.
+ *
+ * Reads as text until clicked; then it is a field. Enter commits (Shift+Enter
+ * is a new line when multiline), Escape cancels, blur commits. A commit that
+ * fails keeps the field open with the text in it, so an edit is never
+ * silently lost — the caller has already said why. An unchanged value is not
+ * committed at all. Empty shows the placeholder, muted.
+ */
+export interface EditableTextProps {
+  value: string
+  placeholder: string
+  /** Resolve `true` when saved; `false` (or throw) keeps the field open with the text. */
+  onCommit: (value: string) => Promise<boolean> | boolean
+  multiline?: boolean
+  /** Applied to both the text and the field, so they are the same size. */
+  className?: string
+  /** The accessible name of the field — "Title", "Description". */
+  label: string
+  /**
+   * What to *show* when not editing, when that differs from what is edited —
+   * a value carrying a raw reference that the caller renders as a live object
+   * below the text, say.
+   *
+   * It overrides the display branch only. `value` is still what the editor
+   * opens with and what a commit compares against, so nothing is silently lost
+   * — which is the failure a naive `value={stripped}` would cause.
+   */
+  display?: string
+  /**
+   * What to *draw* when not editing, when the value is structured rather than
+   * a line of prose.
+   *
+   * A node, not a string, because a heading and a bullet are elements. Added
+   * for a rich text field (SPEC §13): the app renders the parsed body and
+   * hands the result in.
+   *
+   * `display` stays the **string**, and stays what decides emptiness — so a
+   * blank field still shows its placeholder rather than an empty element. Like
+   * `display`, this overrides the display branch only: `value` is what the
+   * editor opens with and what a commit compares against, so what is edited is
+   * unchanged.
+   *
+   * `whitespace-pre-wrap` is dropped when this is set. Structured content
+   * carries its own line breaks, and preserving the source's as well doubles
+   * every one of them.
+   */
+  displayNode?: ReactNode
+  /** Show the value only — no edit affordance. For a reader who cannot write. */
+  readOnly?: boolean
+}
+
+export function EditableText({ value, display, displayNode, placeholder, onCommit, multiline = false, className, label, readOnly = false }: EditableTextProps) {
+  const [editing, setEditing] = useState(false)
+  const [draft, setDraft] = useState(value)
+  const [busy, setBusy] = useState(false)
+  const fieldRef = useRef<HTMLInputElement | HTMLTextAreaElement>(null)
+
+  useEffect(() => {
+    if (editing) {
+      fieldRef.current?.focus()
+      fieldRef.current?.select()
+    }
+  }, [editing])
+
+  const open = () => {
+    setDraft(value)
+    setEditing(true)
+  }
+
+  const cancel = () => {
+    setEditing(false)
+    setDraft(value)
+  }
+
+  const commit = async () => {
+    if (busy) return
+    const next = draft.trim()
+    if (next === value) {
+      setEditing(false)
+      return
+    }
+    setBusy(true)
+    try {
+      const ok = await onCommit(next)
+      if (ok) setEditing(false)
+    } catch {
+      /* the caller has shown why; keep the field open */
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const onKeyDown = (event: KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => {
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      cancel()
+    } else if (event.key === 'Enter' && !(multiline && event.shiftKey)) {
+      event.preventDefault()
+      void commit()
+    }
+  }
+
+  const fieldClass = cn(
+    'w-full rounded-md border border-border-strong bg-bg-inset px-2 py-1 text-text-primary outline-none',
+    multiline && 'resize-none',
+    className,
+  )
+
+  if (readOnly) {
+    return (
+      <div
+        aria-label={label}
+        className={cn('w-full px-2 py-1', multiline && !displayNode && 'whitespace-pre-wrap', (display ?? value) ? 'text-text-primary' : 'text-text-muted', className)}
+      >
+        {(display ?? value) ? (displayNode ?? (display ?? value)) : placeholder}
+      </div>
+    )
+  }
+
+  if (editing) {
+    return multiline ? (
+      <textarea
+        ref={fieldRef as RefObject<HTMLTextAreaElement>}
+        aria-label={label}
+        value={draft}
+        rows={4}
+        disabled={busy}
+        onChange={(event) => setDraft(event.target.value)}
+        onKeyDown={onKeyDown}
+        onBlur={() => void commit()}
+        className={fieldClass}
+      />
+    ) : (
+      <input
+        ref={fieldRef as RefObject<HTMLInputElement>}
+        aria-label={label}
+        value={draft}
+        disabled={busy}
+        onChange={(event) => setDraft(event.target.value)}
+        onKeyDown={onKeyDown}
+        onBlur={() => void commit()}
+        className={fieldClass}
+      />
+    )
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={open}
+      title="Click to edit"
+      aria-label={`Edit ${label.toLowerCase()}`}
+      className={cn(
+        'w-full rounded-md border border-transparent px-2 py-1 text-left transition-colors hover:border-border-default',
+        multiline && !displayNode && 'whitespace-pre-wrap',
+        (display ?? value) ? 'text-text-primary' : 'text-text-muted',
+        className,
+      )}
+    >
+      {(display ?? value) ? (displayNode ?? (display ?? value)) : placeholder}
+    </button>
+  )
+}

package/src/EmptyState.mdx

@@ -0,0 +1,41 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as EmptyStateStories from './EmptyState.stories'
+
+<Meta of={EmptyStateStories} />
+
+# EmptyState
+
+A 16px icon over a centred line of secondary text, for the place where
+content will be once there is some.
+
+<Canvas of={EmptyStateStories.Default} />
+
+## When
+
+- A list, panel or view with nothing in it yet. The message says **what
+  would fill it** — "No comments yet. Start the thread." — not just that
+  it is empty.
+- `icon` swaps the default speech bubble for one that matches the
+  subject.
+
+## When not
+
+- Data is still on its way → **Skeleton**; empty and loading are
+  different truths.
+- Something went wrong → say that, in your surface's own error treatment
+  — an empty state that hides a failure misleads.
+
+## How
+
+```tsx
+import { EmptyState } from '@estiva-app/ui'
+
+<EmptyState message="No documents yet. Create the first one." />
+```
+
+The message is the caller's — a shared component has no words of its own
+for what is missing.
+
+## Props
+
+<Controls of={EmptyStateStories.Default} />

package/src/Field.mdx

@@ -0,0 +1,39 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as FieldStories from './Field.stories'
+
+<Meta of={FieldStories} />
+
+# Field
+
+A label over a control — the form row. The label is the `input-label`
+token; `required` marks it with the error-coloured asterisk.
+
+<Canvas of={FieldStories.Required} />
+
+## When
+
+- Any labelled control in a form or dialog: a TextInput, a Textarea, a
+  Select, a ChipInput.
+
+## When not
+
+- Displaying a label–value pair → **Property**; Field is for editing.
+- It carries no helper or error text of its own — validation display is
+  the caller's, under the control.
+
+## How
+
+```tsx
+import { Field, TextInput } from '@estiva-app/ui'
+
+<Field label="Name" required>
+  <TextInput value={name} onChange={(e) => setName(e.target.value)} />
+</Field>
+```
+
+The label is visual, not wired: also give the control its accessible name
+(`aria-label`, or an `id`/`htmlFor` pair of your own) so the two agree.
+
+## Props
+
+<Controls of={FieldStories.Default} />

package/src/IconButton.mdx

@@ -0,0 +1,47 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as IconButtonStories from './IconButton.stories'
+
+<Meta of={IconButtonStories} />
+
+# IconButton
+
+A square button around a 16px icon: 4px padding, 8px radius, three
+variants. For the actions a surface repeats too often to label every time.
+
+<Canvas of={IconButtonStories.AllVariants} />
+
+## When
+
+- Toolbars and row-hover actions — edit, copy, dismiss, more.
+- A dialog's close.
+- `tooltip` names it on hover; `primary` exists for the rare icon action
+  that is the point of its surface.
+
+## When not
+
+- The action deserves a visible label → **Button** (words are cheaper than
+  a guessed icon).
+- Inside a menu → **MenuItem** with `leading`.
+- A strip of these is a toolbar — right; but the moment rows toggle and
+  persist state, see **Checkbox**.
+
+## How
+
+```tsx
+import { IconButton } from '@estiva-app/ui'
+import { IconPencil } from '@tabler/icons-react'
+
+<IconButton aria-label="Edit" tooltip="Edit" onClick={edit}>
+  <IconPencil size={16} stroke={1.5} />
+</IconButton>
+```
+
+- **`aria-label` is required** — nothing visible names an icon-only
+  control. The `tooltip` shows sighted hover users the same word; it does
+  not replace the label.
+- The icon is 16px at stroke 1.5.
+- `type` defaults to `"button"`; every native prop passes through.
+
+## Props
+
+<Controls of={IconButtonStories.Muted} />

package/src/IdentityMenu.mdx

@@ -0,0 +1,62 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as IdentityMenuStories from './IdentityMenu.stories'
+
+<Meta of={IdentityMenuStories} />
+
+# IdentityMenu
+
+Who you are, and where you are: the identity trigger for a top bar, and
+the menu it opens — ready-made, because every app needs one and it is
+built of nothing but shared parts.
+
+<Canvas of={IdentityMenuStories.SignedIn} />
+
+## When
+
+- The account control of any app. The trigger is a face and a name —
+  never a key — or, `compact`, the face alone at 36px.
+- Anonymous is the silhouette and the word "Anonymous": the truth of the
+  situation rather than hex posing as a name.
+- **Every section hides when the app cannot fill it** — no `relayUrl`, no
+  workspace section; no `onCopyKey`, no copy item; no `idBase`, no
+  sign-in surface. Only offer actions that can succeed. The MinimalApp
+  story is the floor: identity alone.
+
+<Canvas of={IdentityMenuStories.MinimalApp} />
+
+## When not
+
+- Any other menu → **Menu**.
+- Showing a person who is not the viewer → **Person**.
+- A trigger that opens something of your own → **PersonTrigger** plus
+  your menu.
+
+## How
+
+```tsx
+import { IdentityMenu } from '@estiva-app/ui'
+
+<IdentityMenu
+  me={{ name: me.name, picture: me.picture, email: me.email }}
+  signedIn={signedIn}
+  relayUrl={relayUrl}
+  idBase={ID_BASE}
+  onSignOut={signOut}
+/>
+```
+
+- App-specific rows go through `children`, drawn as their own group
+  between the workspace section and the actions. Pass a function to
+  receive `close`, so a row can shut the menu before opening what it
+  opens.
+- Items are text only — no icons in this menu, by ruling.
+- **IdentityPanel** is exported alone for a surface that wants the panel
+  without the trigger; the stories render it, so the designed artifact is
+  what you review.
+- The trigger's toggle, `aria-expanded`, and the accessible-name rules
+  (the row is named by the person; only the bare compact face takes an
+  `aria-label`) are wired inside — bring nothing.
+
+## Props
+
+<Controls of={IdentityMenuStories.SignedIn} />

package/src/IdentityMenu.stories.tsx

@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IdentityPanel } from './IdentityMenu'
+
+/**
+ * The menu itself, standing in flow (`static` beats the anchoring, as the
+ * Menu stories do it) — no trigger, no bar chrome: the trigger's shapes are
+ * PersonTrigger's own stories. In an app, `IdentityMenu` bundles that
+ * trigger with this panel.
+ */
+const meta = {
+  title: 'Navigation/IdentityMenu',
+  component: IdentityPanel,
+  args: {
+    me: {},
+    signedIn: false,
+    relayUrl: 'http://localhost:3000',
+    onCopyKey: () => {},
+    onSignOut: () => {},
+    onClose: () => {},
+    className: 'static',
+  },
+  argTypes: { onClose: { control: false }, className: { control: false } },
+} satisfies Meta<typeof IdentityPanel>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** A browser-held key: silhouette, "Acting as", and the honest sentence. */
+export const Anonymous: Story = {}
+
+/** Signed in through Estiva ID, in a build that offers sign-in. */
+export const SignedIn: Story = {
+  args: {
+    me: { name: 'Ana Duarte', email: 'ana@example.com' },
+    signedIn: true,
+    idBase: 'https://id.estiva.app',
+  },
+}
+
+/**
+ * An app that cannot name a relay or supply a key: those pieces simply are
+ * not there — only offer actions that can succeed.
+ */
+export const MinimalApp: Story = {
+  args: {
+    me: { name: 'Ana Duarte' },
+    signedIn: true,
+    idBase: 'https://id.estiva.app',
+    relayUrl: undefined,
+    onCopyKey: undefined,
+  },
+}

package/src/IdentityMenu.tsx

@@ -0,0 +1,159 @@
+import { useState, type ReactNode } from 'react'
+import { cn } from './cn'
+import { Divider } from './Divider'
+import { Menu, MenuItem, MenuRow, MenuSection } from './Menu'
+import { Person } from './Person'
+import { PersonTrigger } from './PersonTrigger'
+
+/**
+ * Who you are, and where you are — the top bar's identity trigger and the
+ * menu it opens. Ship's IdentityMenu (2026-09-01), moved in whole: every app
+ * needs one, and this one is already made of nothing but shared parts.
+ *
+ * The trigger is a face and a name, never a key (Ship's ruling A4) — or, with
+ * `compact`, the face alone, as Peek's top bar draws it. Anonymous is a
+ * silhouette and the word "Anonymous": the truth of the situation rather than
+ * eight hex characters posing as a name.
+ *
+ * The menu keeps the two honest sentences, and the workspace line names the
+ * relay because on this substrate the relay *is* the workspace. Every section
+ * hides when the app cannot fill it: no `relayUrl`, no workspace section; no
+ * `onCopyKey`, no copy item — only offer actions that can succeed. The one
+ * place a key appears is as the *result* of "Copy public key" — this
+ * component never receives the key, so it cannot show one; the caller
+ * copies. Items are text only, no icons (her ruling).
+ */
+export interface Identity {
+  /** From `kind:0`. Absent means anonymous. */
+  name?: string
+  picture?: string
+  /** Known to Estiva ID, never published to the relay. */
+  email?: string
+}
+
+export interface IdentityMenuProps {
+  me: Identity
+  /** Signed in through Estiva ID, as opposed to a browser-held key. */
+  signedIn: boolean
+  /** Names the workspace; absent hides the workspace section. */
+  relayUrl?: string
+  /** Estiva ID's base URL when this build offers sign-in; absent = anonymous-only build. */
+  idBase?: string
+  /** "Copy public key" appears only when the app can supply one. */
+  onCopyKey?: () => void
+  onSignOut?: () => void
+  /** Face-only trigger, 36px — no chevron, no name beside it. */
+  compact?: boolean
+  className?: string
+  /**
+   * App-specific rows, drawn as their own group between the workspace
+   * section and the actions. A function receives `close`, so a row can
+   * shut the menu before opening what it opens.
+   */
+  children?: ReactNode | ((close: () => void) => ReactNode)
+}
+
+export interface IdentityPanelProps extends Omit<IdentityMenuProps, 'compact' | 'className'> {
+  onClose: () => void
+  /** On the Menu surface — the stories pass `static` to stand it in flow. */
+  className?: string
+}
+
+/** The menu alone — what `IdentityMenu` opens. Exported so the stories show
+ *  the designed artifact rather than a closed trigger, and for any surface
+ *  that wants the panel without the trigger. */
+export function IdentityPanel({ me, signedIn, relayUrl, idBase, onCopyKey, onSignOut, onClose, className, children }: IdentityPanelProps) {
+  const act = (action: () => void) => () => {
+    onClose()
+    action()
+  }
+  const appRows = typeof children === 'function' ? children(onClose) : children
+  return (
+    <Menu onClose={onClose} className={cn('w-72', className)}>
+      <MenuSection label={signedIn ? 'Signed in as' : 'Acting as'}>
+        <MenuRow>
+          <Person name={me.name} picture={me.picture} fallback="Anonymous" size={28} className="text-body-2-strong" />
+        </MenuRow>
+        <Note>
+          {signedIn
+            ? 'Your Estiva ID. The same person you are in every Estiva app.'
+            : 'A key held by this browser only. Nobody else knows who you are.'}
+        </Note>
+        {me.email && <Note>{me.email} · known to Estiva, never published to the relay</Note>}
+      </MenuSection>
+
+      {relayUrl && (
+        <>
+          <Divider className="mx-0 my-2" />
+          <MenuSection label="Workspace">
+            <MenuRow>
+              <span className="break-all font-mono text-caption text-text-primary">{relayUrl}</span>
+            </MenuRow>
+            <Note>Everyone on this relay shares this workspace, in every app.</Note>
+          </MenuSection>
+        </>
+      )}
+
+      {appRows && (
+        <>
+          <Divider className="mx-0 my-2" />
+          {appRows}
+        </>
+      )}
+
+      {(signedIn && idBase) || onCopyKey || (idBase && onSignOut) ? <Divider className="mx-0 my-2" /> : null}
+
+      {signedIn && idBase && (
+        <MenuItem
+          label="Edit your profile in Estiva ID"
+          onClick={act(() => window.open(idBase, '_blank', 'noopener,noreferrer'))}
+        />
+      )}
+      {onCopyKey && <MenuItem label="Copy public key" onClick={act(onCopyKey)} />}
+      {idBase && onSignOut && <MenuItem label="Sign out" onClick={act(onSignOut)} />}
+    </Menu>
+  )
+}
+
+export function IdentityMenu({ me, signedIn, relayUrl, idBase, onCopyKey, onSignOut, compact = false, className, children }: IdentityMenuProps) {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <div className={cn('relative', className)}>
+      <PersonTrigger
+        name={me.name}
+        picture={me.picture}
+        fallback="Anonymous"
+        compact={compact}
+        size={compact ? 36 : undefined}
+        open={open}
+        // Swallowed so the menu's outside-mousedown dismiss does not fire
+        // first and turn the toggle into a close-then-reopen flicker.
+        onMouseDown={(event) => event.stopPropagation()}
+        onClick={() => setOpen((value) => !value)}
+        // The row shape is named by its own text — the person. Only the bare
+        // face needs a label; naming the row would override the person's name
+        // as the accessible name (Ship's tests find the trigger by it).
+        aria-label={compact ? 'Account menu' : undefined}
+      />
+
+      {open && (
+        <IdentityPanel
+          me={me}
+          signedIn={signedIn}
+          relayUrl={relayUrl}
+          idBase={idBase}
+          onCopyKey={onCopyKey}
+          onSignOut={onSignOut}
+          onClose={() => setOpen(false)}
+        >
+          {children}
+        </IdentityPanel>
+      )}
+    </div>
+  )
+}
+
+function Note({ children }: { children: ReactNode }) {
+  return <span className="px-2 pb-1.5 text-caption text-text-secondary">{children}</span>
+}