@estiva-app/ui 0.23.0 → 0.24.0

package/src/Tooltip.stories.tsx

@@ -31,6 +31,32 @@ export const ShortcutComparison: Story = {
   ),
 }
 
+/** A label longer than 320px wraps onto more lines, rather than running off the screen. A short one stays one line at 30px. */
+export const LongLabel: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col items-start gap-2">
+      <Tooltip label="Comment" />
+      <Tooltip label="naddr1qvzqqqr4gupzq9h35qgq6n8ll0xyyv8gurjzjrx9sjwp4hry6ejnlks8cqcmzp6tqyfhwumn8ghj7mmxve3ksctfdch8qatz9uq3wamnwvaz7tmjv4kxz7fwwpexjmtpdshxuet59uq3qamnwvaz7tm99ehx2aqqz9mhxue69uhkummnw3ez6un9d3shjtnwda4k7tnr" />
+      <Tooltip label="Item one, with a title long enough that it no longer fits on one line of a tooltip" />
+    </div>
+  ),
+}
+
+/** `inline`: a tooltip on a word inside a sentence. The wrapper is a span, so the paragraph stays valid HTML. Hover the word. */
+export const InsideText: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <p className="max-w-sm text-body-2 text-text-primary">
+      The plan is in{' '}
+      <WithTooltip inline label="Item one, with a title long enough that it no longer fits on one line of a tooltip">
+        <span className="font-semibold">Item one</span>
+      </WithTooltip>
+      , and the rest follows.
+    </p>
+  ),
+}
+
 /** Hover the button — WithTooltip portals the tooltip above the trigger. */
 export const OnHoverTop: Story = {
   parameters: { controls: { disable: true } },

package/src/Tooltip.test.tsx

@@ -27,6 +27,14 @@ describe('Tooltip, the surface', () => {
     expect(tip.textContent).toBe('BoldCmd+B')
   })
 
+  it('wraps a long label at 320px instead of running it off the screen, and stays 30px on one line', () => {
+    render(<Tooltip label="A label long enough to wrap onto a second line of the tooltip" />)
+    const pill = screen.getByRole('tooltip')
+    expect(pill.className).toContain('max-w-80')
+    expect(pill.className).toContain('min-h-[30px]')
+    expect(pill.querySelector('span')?.className).not.toContain('whitespace-nowrap')
+  })
+
   it('takes a caller class without losing its own', () => {
     render(<Tooltip label="Bold" className="w-40" />)
     const tip = screen.getByRole('tooltip')
@@ -49,6 +57,27 @@ describe('WithTooltip', () => {
     expect(wrapper.firstElementChild?.tagName).toBe('BUTTON')
   })
 
+  it('inline: a span wrapper, so it can sit inside a paragraph without React warning', () => {
+    const errors: unknown[] = []
+    const original = console.error
+    console.error = (...args: unknown[]) => { errors.push(args) }
+    try {
+      render(
+        <p>
+          The plan is in{' '}
+          <WithTooltip inline label="Item one">
+            <span>Item one</span>
+          </WithTooltip>
+          .
+        </p>,
+      )
+    } finally {
+      console.error = original
+    }
+    expect(screen.getByText('Item one').parentElement?.tagName).toBe('SPAN')
+    expect(errors).toEqual([])
+  })
+
   it('takes wrapperClassName, which is what keeps a truncating label truncating', () => {
     const { container } = render(
       <WithTooltip label="A long name" wrapperClassName="min-w-0 shrink">

package/src/Tooltip.tsx

@@ -64,10 +64,16 @@ export interface TooltipProps extends Omit<ComponentPropsWithRef<'div'>, 'childr
   shortcut?: string
 }
 
+/**
+ * One line at 30px, as it has always been; a label longer than 320px wraps
+ * onto more lines rather than running off the screen (Katerina, 19 September:
+ * a reference's full address drew a pill 950px wide). `py-1` only shows once
+ * it wraps: a single line is centred in the 30px.
+ */
 export function Tooltip({ label, shortcut, className, ...props }: TooltipProps) {
   return (
-    <div role="tooltip" className={cn('bg-bg-elevated border border-border-default rounded-lg h-[30px] flex items-center justify-center gap-1.5 px-2 shadow-lg', className)} {...props}>
-      <span className="text-caption text-text-primary whitespace-nowrap">{label}</span>
+    <div role="tooltip" className={cn('bg-bg-elevated border border-border-default rounded-lg min-h-[30px] max-w-80 flex items-center justify-center gap-1.5 px-2 py-1 shadow-lg', className)} {...props}>
+      <span className="min-w-0 text-caption text-text-primary break-words">{label}</span>
       {shortcut && <Kbd>{shortcut}</Kbd>}
     </div>
   )
@@ -80,6 +86,12 @@ export interface WithTooltipProps {
   placement?: 'top' | 'bottom'
   /** Extra classes on the wrapper — e.g. `min-w-0 shrink` so a truncating label keeps truncating inside it. */
   wrapperClassName?: string
+  /**
+   * For a trigger inside a line of text — a reference, a name in a sentence:
+   * the wrapper is a `<span>`, because a `<div>` is not allowed inside a
+   * paragraph (UIG-14, Katerina, 19 September).
+   */
+  inline?: boolean
   children: ReactNode
 }
 
@@ -150,7 +162,8 @@ function TooltipSurface({ label, shortcut, placement }: { label: string; shortcu
  *  an icon. It wraps what it is given in an element that carries the handlers.
  *  A control that can be the trigger does it itself: `IconButton` takes a
  *  `tooltip` prop, and `Button` shows a `disabledReason` the same way. */
-export function WithTooltip({ label, shortcut, placement = 'top', wrapperClassName, children }: WithTooltipProps) {
+export function WithTooltip({ label, shortcut, placement = 'top', wrapperClassName, inline = false, children }: WithTooltipProps) {
+  const Wrapper = inline ? 'span' : 'div'
   return (
     <BaseTooltip.Root disableHoverablePopup>
       {/* The wrapper stays the trigger: `WithTooltip` wraps whatever it is
@@ -158,7 +171,7 @@ export function WithTooltip({ label, shortcut, placement = 'top', wrapperClassNa
           can carry the handlers for all of them. A control that IS the trigger
           (Button, IconButton) composes the part onto itself instead, which is
           what lets a `Dialog.Close` or a `Menu.Trigger` be one of those. */}
-      <BaseTooltip.Trigger delay={OPEN_DELAY} render={<div className={cn('inline-flex shrink-0', wrapperClassName)} />}>
+      <BaseTooltip.Trigger delay={OPEN_DELAY} render={<Wrapper className={cn('inline-flex shrink-0', wrapperClassName)} />}>
         {children}
       </BaseTooltip.Trigger>
       <TooltipSurface label={label} shortcut={shortcut} placement={placement} />

package/src/TopBar.mdx

@@ -57,6 +57,10 @@ import { TopBar, IdentityMenu, SearchInput } from '@estiva-app/ui'
 - The frame is desktop-only for now — there is no narrow-screen
   behaviour; the menu button collapses panels, it does not open a drawer.
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={TopBarStories.Solid} />

package/src/eslint/no-rebuilt-behaviour.ts

@@ -202,7 +202,7 @@ export const OWNED_BEHAVIOURS: OwnedBehaviour[] = [
   },
   {
     id: 'page-keys',
-    behaviour: 'Closes on Escape, and takes its keys, by itself',
+    behaviour: 'Takes its keys by itself',
     baseUi: ['Dialog', 'AlertDialog', 'Popover', 'Menu', 'Select', 'Combobox', 'Tooltip', 'PreviewCard', 'Toast'],
     owners: ['DialogShell', 'Popover', 'Menu', 'Select', 'Tabs', 'Toolbar'],
     reads: 'a keydown, keyup or keypress listener on window or document',

package/src/eslint/no-restyled-part.ts

@@ -118,6 +118,7 @@ export const PART_LOOK_PROPS: Record<string, string[]> = {
   RailItem: ['active'],
   Reaction: ['pressed'],
   ReactionPicker: ['surface'],
+  SectionHeader: ['hover'],
   SectionLabel: ['tone'],
   Select: ['size'],
   Tabs: ['size'],

package/src/pages.test.ts

@@ -0,0 +1,142 @@
+/**
+ * The contract every component page keeps (UIG-14, with UIG-15 and UIG-16 folded in).
+ *
+ * A page opens with a line saying what the part is, then has `When`, `When not`,
+ * `How` (with code) and `What it owns`, in that order, before `Keys` and `Props`.
+ *
+ * `What it owns` reads the checker's own list back. A row ticked ✓ in its third
+ * column is a behaviour from `OWNED_BEHAVIOURS` that one of the page's parts owns,
+ * worded as `ROW` below; every behaviour the page's parts own has one; and a row
+ * worded as a behaviour the parts do not own fails. So the page and the checker
+ * cannot say different things. A part that owns nothing says so in one line.
+ *
+ * A `When not` line names only parts that exist: a bold name is a value export of
+ * `index.ts`, or a page.
+ */
+import { readdirSync, readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+import { OWNED_BEHAVIOURS } from './eslint/no-rebuilt-behaviour'
+
+/** How a page words each behaviour. `base-ui` is how a part is built, not what it does for a caller. */
+const ROW: Record<string, RegExp> = {
+  portal: /^Floats on top of the page\b/,
+  'press-outside': /^Closes on a press outside\b/,
+  'page-keys': /^Takes its keys by itself\b/,
+  focus: /^Holds focus inside while open\b/,
+  'scroll-lock': /^Stops the page behind it scrolling\b/,
+  follow: /^Stays attached to its anchor\b/,
+  walking: /^Moves through its items with the arrow keys\b/,
+  role: /^Says what it is to assistive technology\b/,
+  'tab-stop': /^Is reachable with Tab\b/,
+  scroll: /^Scrolls with our scrollbar\b/,
+}
+const NOT_A_ROW = ['base-ui']
+
+/** A page whose part another ticket is changing, while it is; empty when none is. */
+const WAITING: string[] = []
+
+const NOTHING = 'Nothing. It only draws. Clicks and keys are yours.'
+
+const dir = new URL('.', import.meta.url)
+const read = (file: string) => readFileSync(new URL(file, dir), 'utf8').replace(/\r\n/g, '\n')
+const pages = readdirSync(dir)
+  .filter((f) => f.endsWith('.mdx'))
+  .map((f) => f.slice(0, -4))
+
+const index = read('index.ts')
+/** Value exports of index.ts, by the module they come from. */
+const byModule = new Map<string, string[]>()
+for (const m of index.matchAll(/export\s*\{([^}]*)\}\s*from\s*'\.\/([\w/]+)'/g)) {
+  const names = m[1]
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s && !s.startsWith('type '))
+    .map((s) => s.split(/\s+as\s+/).pop()!)
+  byModule.set(m[2], [...(byModule.get(m[2]) ?? []), ...names])
+}
+const exported = new Set([...byModule.values()].flat())
+
+/** The parts a page documents: its own name, and its module's exports that have no page of their own. */
+const partsOf = (page: string) => [page, ...(byModule.get(page) ?? []).filter((n) => n !== page && !pages.includes(n))]
+
+const section = (t: string, name: string) => {
+  const head = `\n## ${name}\n`
+  const at = t.indexOf(head)
+  if (at < 0) return null
+  const rest = t.slice(at + head.length)
+  const end = rest.search(/^## /m)
+  return end < 0 ? rest : rest.slice(0, end)
+}
+
+const owns = (t: string) =>
+  (section(t, 'What it owns') ?? '')
+    .split('\n')
+    .filter((l) => l.startsWith('| ') && !l.startsWith('| It does |'))
+    .map((l) => l.split('|').map((c) => c.trim()))
+    .map(([, does, never, ticked]) => ({ does, never, ticked: ticked === '✓' }))
+
+describe('the page contract', () => {
+  it('words every behaviour the checker knows', () => {
+    const ids = OWNED_BEHAVIOURS.map((b) => b.id).filter((id) => !NOT_A_ROW.includes(id))
+    expect(Object.keys(ROW).sort()).toEqual(ids.sort())
+  })
+
+  it('finds the pages', () => {
+    expect(pages.length).toBeGreaterThanOrEqual(54)
+  })
+
+  for (const page of pages) {
+    describe(page, () => {
+      const t = read(`${page}.mdx`)
+      const headings = [...t.matchAll(/^## (.+)$/gm)].map((m) => m[1])
+
+      it('opens with a line saying what it is', () => {
+        const opening = t.split(/^# .*$/m)[1]?.split(/\n\s*\n/).map((s) => s.trim()).find((s) => s && !s.startsWith('<'))
+        expect(opening, 'no opening line under the title').toBeTruthy()
+      })
+
+      it('has each section once', () => {
+        expect(headings.filter((h, i) => headings.indexOf(h) !== i)).toEqual([])
+      })
+
+      it('has its sections in order', () => {
+        const want = WAITING.includes(page) ? ['When', 'When not', 'How'] : ['When', 'When not', 'How', 'What it owns']
+        const at = want.map((h) => headings.indexOf(h))
+        expect(at.filter((i) => i < 0).length, `missing: ${want.filter((_, i) => at[i] < 0).join(', ')}`).toBe(0)
+        expect([...at].sort((a, b) => a - b)).toEqual(at)
+        for (const after of ['Keys', 'Props']) {
+          const i = headings.indexOf(after)
+          if (i >= 0) expect(at[at.length - 1], `${want[want.length - 1]} comes before ${after}`).toBeLessThan(i)
+        }
+      })
+
+      it('shows code under How', () => {
+        expect(section(t, 'How')).toMatch(/```tsx?\n/)
+      })
+
+      it('names only parts that exist under When not', () => {
+        const names = [...(section(t, 'When not') ?? '').matchAll(/\*\*`?([A-Z][A-Za-z0-9]*)`?\*\*/g)].map((m) => m[1])
+        expect(names.filter((n) => !exported.has(n) && !pages.includes(n))).toEqual([])
+      })
+
+      if (WAITING.includes(page)) return
+
+      it('says what it owns, as the checker does', () => {
+        const parts = partsOf(page)
+        const owned = OWNED_BEHAVIOURS.filter((b) => !NOT_A_ROW.includes(b.id) && b.owners.some((o) => parts.includes(o))).map((b) => b.id)
+        const rows = owns(t)
+        const body = (section(t, 'What it owns') ?? '').trim()
+        if (!rows.length) {
+          expect(owned, `${page} owns ${owned.join(', ')}; the page says nothing`).toEqual([])
+          expect(body).toBe(NOTHING)
+          return
+        }
+        const said = rows.flatMap((r) => Object.entries(ROW).filter(([, re]) => re.test(r.does)).map(([id]) => ({ id, ticked: r.ticked, does: r.does })))
+        expect(said.filter((s) => !s.ticked).map((s) => s.does), 'a checker behaviour, not ticked').toEqual([])
+        expect(rows.filter((r) => r.ticked && !Object.values(ROW).some((re) => re.test(r.does))).map((r) => r.does), 'ticked, but not worded as a checker behaviour').toEqual([])
+        expect(said.map((s) => s.id).sort()).toEqual([...owned].sort())
+        expect(rows.every((r) => r.does && r.never), 'every row says what it does and what you never write').toBe(true)
+      })
+    })
+  }
+})

package/tailwind-preset.js

@@ -67,9 +67,30 @@ export default {
   // see tokens.css). Both exist so a treatment can be given to the two apps
   // without changing the plain light/dark themes the docs render in.
   plugins: [
-    plugin(({ addVariant }) => {
+    plugin(({ addVariant, addComponents }) => {
       addVariant('signal', '.signal &')
       addVariant('ship', "[data-theme='ship'] &")
+      // The Signal canvas: the control-room dot grid on the app's dark ground,
+      // in the Signal theme only. AppShell's floating frame carries
+      // `signal-canvas`. Peek's, verbatim (UIG-14, Katerina, 19 September: the
+      // canvas is the theme's, so it moved with the frame). A component here,
+      // not base.css, so it reaches every app on the preset and the class lint
+      // knows the name. `isolation` and `z-index: -1` keep the grid above
+      // the ground and below every child: never over the card, a dialog, a menu.
+      addComponents({
+        '.signal .signal-canvas': { isolation: 'isolate' },
+        '.signal .signal-canvas::before': {
+          content: "''",
+          position: 'absolute',
+          inset: '0',
+          zIndex: '-1',
+          pointerEvents: 'none',
+          backgroundImage: 'radial-gradient(circle, rgba(255, 255, 255, 0.045) 1px, transparent 1px)',
+          backgroundSize: '26px 26px',
+          maskImage: 'radial-gradient(1100px 700px at 50% 45%, transparent 25%, #000 100%)',
+          WebkitMaskImage: 'radial-gradient(1100px 700px at 50% 45%, transparent 25%, #000 100%)',
+        },
+      })
     }),
   ],
   theme: {