@estiva-app/ui 0.44.1 → 0.46.0

package/src/NavItem.tsx

@@ -1,5 +1,9 @@
 import type { ComponentPropsWithoutRef, ReactNode } from 'react'
+import { IconDotsVertical } from '@tabler/icons-react'
 import { cn } from './cn'
+import { SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES } from './looks'
+import { IconButton } from './IconButton'
+import { Menu } from './Menu'
 import { WithTooltip } from './Tooltip'
 
 /**
@@ -12,6 +16,12 @@ import { WithTooltip } from './Tooltip'
  * count draws its zero (see Tabs) — both rulings stand, deliberately.
  *
  * Active is the same fill as a selected tab — `bg-active`, neutral.
+ *
+ * `menu` gives the row a "More options" menu (UIG-44, Katerina, 30
+ * September): a ⋮ that shows while the row is pointed at, focused or its
+ * menu is open, in the count's place — the count steps aside rather than
+ * sitting under it. The ⋮ is beside the link, not inside it (a button inside
+ * an anchor is not a button), and follows it in the Tab order.
  */
 export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'> {
   label: string
@@ -23,12 +33,15 @@ export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'
   active?: boolean
   /** 16px, stroke 1.5. */
   icon?: ReactNode
+  /** The row's "More options" menu: `MenuItem`s. Absent, the row has no menu and is exactly the plain row. */
+  menu?: ReactNode
+  /** The ⋮'s accessible name and tooltip. Default "More options for {label}". */
+  menuLabel?: string
   className?: string
 }
 
-export function NavItem({ label, href, count, countLabel, active = false, icon, className, ...props }: NavItemProps) {
-  return (
-    // @estiva-escape(no-copied-look): N5 (Katerina, 24 September: record only): a row that fills on hover, as PersonTrigger's row also does
+export function NavItem({ label, href, count, countLabel, active = false, icon, menu, menuLabel, className, ...props }: NavItemProps) {
+  const row = (
     <a
       href={href}
       aria-current={active ? 'page' : undefined}
@@ -36,8 +49,12 @@ export function NavItem({ label, href, count, countLabel, active = false, icon,
         // shrink-0: the row keeps its 32px inside an overflowing flex column
         // — without it the list compresses instead of scrolling (the missing-
         // shrink-0 family; Katerina, 2026-09-02).
-        'flex h-8 min-w-0 shrink-0 items-center gap-2 rounded-md px-2 text-body-2 transition-colors',
-        active ? 'bg-bg-active text-text-primary' : 'text-text-secondary hover:bg-bg-hover hover:text-text-primary',
+        'flex h-8 min-w-0 shrink-0 items-center gap-2 px-2 text-body-2',
+        SIDEBAR_ROW_CLASSES,
+        active ? 'bg-bg-active text-text-primary' : cn(SIDEBAR_ROW_TEXT_CLASSES, 'hover:bg-bg-hover'),
+        // With a menu the ⋮ sits beside the link, so the row keeps its hover
+        // look while the ⋮ is pointed at and while its menu is open.
+        menu != null && !active && 'group-hover/nav:bg-bg-hover group-hover/nav:text-text-primary group-has-[[aria-expanded=true]]/nav:bg-bg-hover group-has-[[aria-expanded=true]]/nav:text-text-primary',
         className,
       )}
       {...props}
@@ -50,9 +67,42 @@ export function NavItem({ label, href, count, countLabel, active = false, icon,
               here sits on the same axis as a SectionHeader's action above it
               — right edges alone left a digit 4px off a 16px icon (Katerina,
               2026-09-09). A three-digit count grows the box leftwards. */}
-          <span className="min-w-4 shrink-0 text-center font-mono text-caption tabular-nums text-text-muted">{count}</span>
+          <span
+            className={cn(
+              'min-w-4 shrink-0 text-center font-mono text-caption tabular-nums text-text-muted',
+              // With a menu, the ⋮ takes this place while it shows.
+              menu != null && 'transition-opacity group-hover/nav:opacity-0 group-focus-within/nav:opacity-0 group-has-[[aria-expanded=true]]/nav:opacity-0',
+            )}
+          >
+            {count}
+          </span>
         </WithTooltip>
+      ) : menu != null ? (
+        // No count, but a menu: the count's place is kept free, so a long
+        // label truncates before the ⋮ instead of running under it.
+        <span aria-hidden="true" className="min-w-4 shrink-0" />
       ) : null}
     </a>
   )
+  if (menu == null) return row
+  const name = menuLabel ?? `More options for ${label}`
+  return (
+    <div className="group/nav relative shrink-0">
+      {row}
+      {/* `right-1`: the 24px button's 16px icon then ends 8px from the row's
+          edge, where the count ends (px-2), so the ⋮ lands on the number. */}
+      <div className="absolute inset-y-0 right-1 flex items-center opacity-0 transition-opacity focus-within:opacity-100 group-hover/nav:opacity-100 has-[[aria-expanded=true]]:opacity-100">
+        <Menu
+          align="right"
+          trigger={
+            <IconButton tooltip="More options" aria-label={name}>
+              <IconDotsVertical size={16} stroke={1.5} />
+            </IconButton>
+          }
+        >
+          {menu}
+        </Menu>
+      </div>
+    </div>
+  )
 }

package/src/Reaction.tsx

@@ -81,7 +81,7 @@ export function Reaction({ emoji, count, pressed = false, className, ...props }:
                (Katerina, 2026-09-08). The number reads in the text colour
                there; the accent keeps the edge and the fill. Signal keeps
                Peek's blue-on-wash, which reads. */
-            'border-accent-primary bg-accent-muted text-accent-primary hover:border-accent-hover ship:text-text-primary'
+            'border-accent-primary bg-accent-muted text-accent-text hover:border-accent-hover ship:text-text-primary'
           : 'border-border-default bg-bg-inset text-text-primary hover:border-border-strong hover:bg-bg-hover',
         className,
       )}

package/src/SectionHeader.mdx

@@ -24,6 +24,15 @@ title the toggle — that is where a section folds.
 
 <Canvas of={SectionHeaderStories.PersistentActions} />
 
+- `look="quiet"`: a small grey label over a list whose rows are rows, not
+  headings — "Folders" over the folders — with its action held on screen.
+  It never lights up under the pointer; its button does.
+
+<Canvas of={SectionHeaderStories.Quiet} />
+
+- `look="row"`: the header is a row among rows — a folder in a sidebar. Use
+  it through **CollapsibleSection**'s `look="row"`.
+
 ## When not
 
 - A section that opens and closes → **CollapsibleSection**: the header,

package/src/SectionHeader.stories.tsx

@@ -56,3 +56,18 @@ export const WithTrailing: Story = {
     actions: [{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: () => {} }],
   },
 }
+
+/** `look="quiet"`: a small grey label over a list, with its action always on screen — "Folders" over the folders. The row never lights up; the button does. */
+export const Quiet: Story = {
+  args: {
+    title: 'Folders',
+    look: 'quiet',
+    showActions: 'always',
+    actions: [{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'New folder', onClick: () => {} }],
+  },
+}
+
+/** `look="row"`: a row among rows — the chevron and the title at a sidebar row's size and colour, brightening under the pointer. CollapsibleSection's `look="row"` draws this. */
+export const Row: Story = {
+  args: { title: 'Folder', look: 'row', chevron: true, isExpanded: true, onToggle: () => {} },
+}

package/src/SectionHeader.tsx

@@ -2,6 +2,7 @@ import type { ReactNode } from 'react'
 import { IconChevronRight } from '@tabler/icons-react'
 import { useRender } from '@base-ui/react/use-render'
 import { cn } from './cn'
+import { SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES } from './looks'
 import { IconButton } from './IconButton'
 import { SectionLabel } from './SectionLabel'
 
@@ -65,6 +66,14 @@ export interface SectionHeaderProps {
    * where the buttons light up on their own (UIG-14, Katerina, 19 September).
    */
   hover?: 'fill' | 'none'
+  /**
+   * `heading` (default): a section's title, the `SectionLabel`. `quiet`: a
+   * small grey label over a list (12px, muted) — "Folders" over the folders,
+   * which never reads as one of them. `row`: a row among rows — the chevron
+   * and the title at a row's weight and colour, as a sidebar row is (Katerina,
+   * 30 September: Leaf's folders, in Ship).
+   */
+  look?: 'heading' | 'quiet' | 'row'
   /**
    * What the title renders as, in Base UI's manner. A plain button with
    * `onToggle` by default; `CollapsibleSection` hands in `Collapsible.Trigger`.
@@ -73,24 +82,32 @@ export interface SectionHeaderProps {
   className?: string
 }
 
-export function SectionHeader({ title, chevron = false, isExpanded = true, onToggle, trailing, actions, showActions = 'hover', hover = 'fill', render, className }: SectionHeaderProps) {
+export function SectionHeader({ title, chevron = false, isExpanded = true, onToggle, trailing, actions, showActions = 'hover', hover = 'fill', look = 'heading', render, className }: SectionHeaderProps) {
+  const row = look === 'row'
   const titleElement = useRender({
     render: render ?? (chevron ? <button type="button" onClick={onToggle} aria-expanded={isExpanded} /> : <span />),
     props: {
       // `text-left`: a button centres its text. `h-full` and `flex-1`: the
       // whole row up to the actions is the hit target, as it was when the
       // row itself carried the click.
-      className: 'flex h-full min-w-0 flex-1 items-center gap-1 text-left',
+      className: cn('flex h-full min-w-0 flex-1 items-center text-left', row ? 'gap-2' : 'gap-1'),
       children: (
         <>
           {chevron && (
             <IconChevronRight
-              size={12}
+              size={row ? 16 : 12}
               stroke={1.5}
-              className={cn('shrink-0 text-text-secondary transition-transform duration-150', isExpanded && 'rotate-90')}
+              className={cn('shrink-0 transition-transform duration-150', !row && 'text-text-secondary', isExpanded && 'rotate-90')}
             />
           )}
-          <SectionLabel>{title}</SectionLabel>
+          {look === 'quiet' ? (
+            <span className="min-w-0 truncate text-caption text-text-muted">{title}</span>
+          ) : row ? (
+            // A row's words: NavItem's size and colour, brightening under the pointer with the row.
+            <span className="min-w-0 flex-1 truncate text-body-2">{title}</span>
+          ) : (
+            <SectionLabel>{title}</SectionLabel>
+          )}
         </>
       ),
     },
@@ -99,11 +116,15 @@ export function SectionHeader({ title, chevron = false, isExpanded = true, onTog
   return (
     <div
       className={cn(
-        'group flex h-[32px] shrink-0 items-center gap-1 rounded-lg px-2 transition-colors',
+        'group flex h-[32px] shrink-0 items-center gap-1 px-2',
+        !row && 'transition-colors',
+        // A row is NavItem's shape and colour: 6px corners, secondary words that brighten on hover.
+        row ? cn(SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES) : 'rounded-lg',
         // The fill says "this does something": a row with a toggle or actions
         // lights up, a fixed heading over rows does not (2026-09-09, the
         // Sidebar's fixed group).
-        hover === 'fill' && (chevron || (actions && actions.length > 0)) && 'hover:bg-bg-hover',
+        // A quiet label never lights up: it is a label; its button does.
+        hover === 'fill' && look !== 'quiet' && (chevron || (actions && actions.length > 0)) && 'hover:bg-bg-hover',
         className,
       )}
     >

package/src/SelectionToolbar.mdx

@@ -0,0 +1,78 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as SelectionToolbarStories from './SelectionToolbar.stories'
+
+<Meta of={SelectionToolbarStories} />
+
+# SelectionToolbar
+
+Bold, italic and underline — and code or a link where the editor has them —
+over text you have already selected in an editor.
+
+<Canvas of={SelectionToolbarStories.Default} />
+
+## When
+
+- **Inside any Tiptap editor.** It mounts with the editor and decides for
+  itself when to appear: once a selection has stood still, centred over it.
+- `marks` chooses the buttons, in order: `bold`, `italic`, `underline`, `code`.
+  The default is the first three.
+- `link` adds the Link button, which turns the strip into one field for the
+  address. Select words that are already a link and the field opens by itself,
+  their address in it.
+
+## When not
+
+- In the `/` list → **SuggestionMenu**. Typing `/` replaces the selection, so
+  there is nothing selected to apply a mark to.
+- A strip of actions on a card or an image → **Toolbar** in a **Popover**. This
+  one's placement exists to centre over a text selection.
+
+## How
+
+```tsx
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { SelectionToolbar, KeptSelection } from '@estiva-app/ui/editor'
+
+const editor = useEditor({ extensions: [StarterKit, KeptSelection], content: text })
+
+<EditorContent editor={editor} />
+<SelectionToolbar editor={editor} marks={['bold', 'italic', 'underline', 'code']} link />
+```
+
+- `editor` is the Tiptap editor, or `null` while it loads. There is nothing to
+  place: it anchors itself to the selection.
+- **`link` needs two things in the editor**: a link mark, and `KeptSelection`,
+  which keeps the words highlighted while the address field has the focus.
+  Without a link mark, leave `link` off.
+- **Each mark must be in the editor's schema.** A button for a mark the editor
+  lacks does nothing.
+- **The address field:** Enter applies it, and so does clicking away. Enter on
+  an empty field removes the link; clicking away with an empty field changes
+  nothing. Escape drops what was typed. `http`, `https` and `mailto` only; a
+  bare host gets `https://`.
+
+<Canvas of={SelectionToolbarStories.WithALink} />
+
+## What it owns
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Appears once a selection has stood still, never mid-drag or on a plain click | a selection listener, a timer | |
+| Centres itself over the selection, above it | position arithmetic | |
+| Keeps the caret in the text while a button is pressed | `preventDefault` on each button | |
+| Keeps the words highlighted while the address field has focus | a second selection | |
+
+## Keys
+
+| Input | What happens |
+|---|---|
+| Cmd/Ctrl+B, I, U, E | bold, italic, underline, code — the editor's own keys, named in each tooltip |
+| Tab | onto the strip, as any `Toolbar` |
+| ← / → | between the buttons |
+| Enter, in the address field | applies it; empty removes the link |
+| Escape, in the address field | drops what was typed and puts the caret back |
+
+## Props
+
+<Controls of={SelectionToolbarStories.Default} />

package/src/SelectionToolbar.stories.tsx

@@ -0,0 +1,63 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { richTextClassName } from './RichText'
+import { KeptSelection, SelectionToolbar, type MarkId } from './SelectionToolbar'
+
+/**
+ * Bold, italic, underline — and code or link where the editor has them — over
+ * text you have already selected. It follows the selection by itself.
+ */
+const meta = {
+  title: 'Primitives/SelectionToolbar',
+  component: SelectionToolbar,
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+/**
+ * A real editor with a few words selected as it opens, so the strip is on
+ * screen without a drag — it appears the way it always does, once the
+ * selection has stood still. Select other words to move it.
+ */
+function WithAnEditor({ marks, link, html, select }: { marks?: readonly MarkId[]; link?: boolean; html: string; select: [number, number] }) {
+  const editor = useEditor({
+    extensions: [StarterKit, KeptSelection],
+    content: html,
+    editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
+    onCreate: ({ editor: e }) => {
+      e.commands.focus()
+      e.commands.setTextSelection({ from: select[0], to: select[1] })
+    },
+  })
+  return (
+    <div className="pt-16">
+      <EditorContent editor={editor} className="max-w-[560px]" />
+      <SelectionToolbar editor={editor} marks={marks} link={link} />
+    </div>
+  )
+}
+
+const TEXT = '<p>Select a few words in this line, and the strip appears over them.</p>'
+
+/** The default strip: bold, italic, underline. */
+export const Default: Story = {
+  render: () => <WithAnEditor html={TEXT} select={[10, 19]} />,
+}
+
+/** `marks` chooses the buttons: here code as well. */
+export const WithCode: Story = {
+  render: () => <WithAnEditor html={TEXT} select={[10, 19]} marks={['bold', 'italic', 'underline', 'code']} />,
+}
+
+/** `link` adds the Link button, which opens one field for the address. */
+export const WithALink: Story = {
+  render: () => <WithAnEditor html={TEXT} select={[10, 19]} link />,
+}
+
+/** Words that are already a link open straight on the field, their address in it. */
+export const OnALink: Story = {
+  render: () => <WithAnEditor html={'<p>Select <a href="https://example.com">these words</a> to change where they go.</p>'} select={[8, 19]} link />,
+}

package/src/SelectionToolbar.test.ts

@@ -0,0 +1,105 @@
+// @vitest-environment jsdom
+/**
+ * The selection toolbar's helpers (UIG-31), carried over with it: how a key is
+ * named in a tooltip, and what the address field does to the text. Drawing the
+ * strip needs a real selection standing still, which jsdom cannot make; the
+ * stories show it in a browser.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { Editor } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { KeptSelection, applyLink, currentLink, normalizeHref } from './SelectionToolbar'
+import { shortcutLabel } from './shortcuts'
+
+let editor: Editor
+
+beforeEach(() => {
+  editor = new Editor({ extensions: [StarterKit, KeptSelection], content: '<p>read the linked words first</p>' })
+})
+
+afterEach(() => {
+  editor.destroy()
+})
+
+describe('shortcutLabel', () => {
+  it('says Cmd on Apple platforms', () => {
+    expect(shortcutLabel('Mod-B', true)).toBe('Cmd+B')
+    expect(shortcutLabel('Mod-Shift-B', true)).toBe('Cmd+Shift+B')
+  })
+
+  it('says Ctrl everywhere else', () => {
+    expect(shortcutLabel('Mod-B', false)).toBe('Ctrl+B')
+    expect(shortcutLabel('Mod-Shift-B', false)).toBe('Ctrl+Shift+B')
+  })
+
+  it('upper-cases a single-character key so Ctrl+b never reaches a tooltip', () => {
+    expect(shortcutLabel('Mod-b', false)).toBe('Ctrl+B')
+  })
+})
+
+describe('the marks the strip can toggle are in a standard editor', () => {
+  it.each(['bold', 'italic', 'underline', 'code', 'link'])('%s', (mark) => {
+    expect(Object.keys(editor.schema.marks)).toContain(mark)
+  })
+})
+
+describe('normalizeHref — what typing in the field becomes', () => {
+  const cases: Array<[string, string | null]> = [
+    ['https://example.com/a/b', 'https://example.com/a/b'],
+    ['http://example.com', 'http://example.com'],
+    ['mailto:someone@example.com', 'mailto:someone@example.com'],
+    ['example.com', 'https://example.com'],
+    ['  www.example.com/a?b=c  ', 'https://www.example.com/a?b=c'],
+    ['localhost:5173/page', 'https://localhost:5173/page'],
+    ['javascript:alert(1)', null],
+    ['ftp://files.example.com', null],
+    ['two words', null],
+    ['', null],
+    ['   ', null],
+  ]
+  it.each(cases)('%j → %j', (raw, href) => {
+    expect(normalizeHref(raw)).toBe(href)
+  })
+})
+
+describe('applyLink — over "linked words" in "read the linked words first"', () => {
+  /** The one linked run in the document, or null. */
+  const linkOf = (): { text: string; href: string } | null => {
+    let found: { text: string; href: string } | null = null
+    editor.state.doc.descendants((node) => {
+      const link = node.marks.find((m) => m.type.name === 'link')
+      if (node.isText && link) found = { text: node.text ?? '', href: link.attrs.href as string }
+    })
+    return found
+  }
+
+  beforeEach(() => {
+    editor.commands.setTextSelection({ from: 10, to: 22 })
+  })
+
+  it('an address links the selected words, completing a bare host', () => {
+    expect(applyLink(editor, 'example.com')).toBe(true)
+    expect(linkOf()).toEqual({ text: 'linked words', href: 'https://example.com' })
+    expect(currentLink(editor)).toBe('https://example.com')
+  })
+
+  it('an empty field removes the link', () => {
+    applyLink(editor, 'https://example.com')
+    expect(applyLink(editor, '')).toBe(true)
+    expect(linkOf()).toBeNull()
+    expect(currentLink(editor)).toBe('')
+  })
+
+  it('a scheme a reader may not follow is refused, and nothing changes', () => {
+    expect(applyLink(editor, 'javascript:alert(1)')).toBe(false)
+    expect(linkOf()).toBeNull()
+  })
+
+  it('the caret inside a link re-addresses the whole link', () => {
+    applyLink(editor, 'https://example.com')
+    editor.commands.setTextSelection(15)
+    expect(currentLink(editor)).toBe('https://example.com')
+    expect(applyLink(editor, 'https://example.org')).toBe(true)
+    expect(linkOf()).toEqual({ text: 'linked words', href: 'https://example.org' })
+  })
+})