@startsimpli/ui 0.4.109 → 0.4.111

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.109",
+  "version": "0.4.111",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -21,6 +21,8 @@
     "./blog/resolve": "./src/components/blog/resolveArticle.ts",
     "./activity": "./src/components/activity/index.ts",
     "./collection": "./src/components/collection/index.ts",
+    "./scope": "./src/components/scope/index.ts",
+    "./facet-tree": "./src/components/facet-tree/index.ts",
     "./document-editor": "./src/components/document-editor/index.ts",
     "./email-editor": "./src/components/email-editor/index.ts",
     "./workflows": "./src/components/workflows/index.ts",
@@ -121,8 +123,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/i18n": "0.1.3",
-    "@startsimpli/realtime": "0.0.2"
+    "@startsimpli/realtime": "0.0.2",
+    "@startsimpli/i18n": "0.1.3"
   },
   "keywords": [
     "ui",

package/src/components/collection/__tests__/review.test.ts

@@ -223,3 +223,64 @@ describe('reviewHostOf / fieldStr', () => {
     expect(fieldStr(undefined, 'x')).toBe('');
   });
 });
+
+// ---- decision vocabulary (bd startsim-b313v) ----
+//
+// THE DEFECT THESE COVER. The three labels were string literals inside
+// `reviewDecisions`, so every tenant's every reviewable type said the same three
+// words. On the OGMC tenant that collided in the customer's hands: approving a
+// TOPIC ("this subject is worth writing") and approving a DRAFT ("this piece is
+// publishable") are different KINDS of decision, and both rendered "Approve".
+// Her question, mid-walkthrough: "so if I go, I click approve now, does it
+// approve all of them?"
+
+describe('decision labels are the consumer’s to name', () => {
+  const type = {
+    id: 't',
+    key: 'topic',
+    label: 'Topic',
+    attributes: [
+      {
+        id: 'a',
+        name: 'status',
+        dataType: 'enum' as const,
+        required: false,
+        config: { choices: ['suggested', 'ready', 'written', 'rejected'] },
+      },
+    ],
+  };
+
+  it('keeps the generic words when a consumer supplies none', () => {
+    expect(reviewDecisions(resolveReviewConfig(type)).map((d) => d.label)).toEqual([
+      'Approve',
+      'Needs work',
+      'Reject',
+    ]);
+  });
+
+  it('lets a consumer name what the decision is ABOUT', () => {
+    const cfg = resolveReviewConfig(type, {
+      decisionLabels: { approve: 'Approve topic', reject: 'Reject topic' },
+    });
+    const byKey = Object.fromEntries(reviewDecisions(cfg).map((d) => [d.key, d.label]));
+    expect(byKey.approve).toBe('Approve topic');
+    expect(byKey.reject).toBe('Reject topic');
+    // Unnamed decisions keep the default rather than going blank.
+    expect(byKey.needs_work).toBe('Needs work');
+  });
+
+  it('ignores a blank override instead of rendering an unlabelled button', () => {
+    const cfg = resolveReviewConfig(type, { decisionLabels: { approve: '   ' } });
+    expect(reviewDecisions(cfg).find((d) => d.key === 'approve')?.label).toBe('Approve');
+  });
+
+  it('leaves every other part of the decision alone — this is copy, not behaviour', () => {
+    const plain = reviewDecisions(resolveReviewConfig(type));
+    const named = reviewDecisions(
+      resolveReviewConfig(type, { decisionLabels: { approve: 'Approve topic' } }),
+    );
+    expect(named.map((d) => [d.key, d.status, d.verdict, d.tone, d.advance, d.shortcut])).toEqual(
+      plain.map((d) => [d.key, d.status, d.verdict, d.tone, d.advance, d.shortcut]),
+    );
+  });
+});

package/src/components/collection/index.ts

@@ -13,6 +13,8 @@ export {
   resolveReviewConfig,
   deriveReviewTransitions,
   reviewDecisions,
+  decisionLabel,
+  DEFAULT_DECISION_LABELS,
   applyDecisionToData,
   type ReviewDecision,
   pickStatusAttr,

package/src/components/collection/review.ts

@@ -169,6 +169,23 @@ export interface ReviewConfig {
   sourceAttrs?: string[];
   /** Drop the middle "Needs work" decision — a binary accept/reject flow (default false). */
   omitNeedsWork?: boolean;
+  /**
+   * What each decision is CALLED, by decision key ('approve' | 'needs_work' |
+   * 'reject'). Anything omitted keeps the generic default.
+   *
+   * WHY THIS EXISTS (bd startsim-b313v). The labels used to be string literals
+   * in `reviewDecisions` below, so every tenant's every reviewable type rendered
+   * the same three words. On OGMC that collided in the customer's hands: a
+   * reviewer approving a TOPIC ("this subject is worth writing") and a reviewer
+   * approving a DRAFT ("this piece is publishable") both pressed a button
+   * labelled "Approve", and she asked, mid-walkthrough, "so if I go, I click
+   * approve now, does it approve all of them?"
+   *
+   * A workspace cannot answer that from here — only the consumer knows what its
+   * records ARE — so the vocabulary is the consumer's to supply. Defaults are
+   * unchanged, so nothing that does not pass this renders differently.
+   */
+  decisionLabels?: Record<string, string>;
 }
 
 export interface ResolvedReview {
@@ -185,6 +202,7 @@ export interface ResolvedReview {
   metaAttrs: string[];
   sourceAttrs: string[];
   omitNeedsWork: boolean;
+  decisionLabels: Record<string, string>;
 }
 
 const DEFAULT_SOURCE_ATTRS = ['source_1', 'source_2', 'source_3', 'sources'];
@@ -216,9 +234,23 @@ export function resolveReviewConfig(
     // Keep source attrs the caller asked for; default to the ones this type declares.
     sourceAttrs: (config.sourceAttrs ?? DEFAULT_SOURCE_ATTRS).filter((a) => declared.has(a)),
     omitNeedsWork: config.omitNeedsWork ?? false,
+    decisionLabels: config.decisionLabels ?? {},
   };
 }
 
+/** The default name of a decision, when the consumer supplies none. */
+export const DEFAULT_DECISION_LABELS: Record<string, string> = {
+  approve: 'Approve',
+  needs_work: 'Needs work',
+  reject: 'Reject',
+};
+
+/** What a decision is called on THIS surface — the consumer's word, else the default. */
+export function decisionLabel(key: string, cfg: Pick<ResolvedReview, 'decisionLabels'>): string {
+  const supplied = cfg.decisionLabels?.[key];
+  return supplied && supplied.trim() ? supplied : DEFAULT_DECISION_LABELS[key] ?? key;
+}
+
 // ---- the single review decision (Approve / Needs work / Reject) ----
 //
 // status and team_verdict are two fields with different consumers (status = the
@@ -262,7 +294,7 @@ export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
   if (r.transitions.approve) {
     out.push({
       key: 'approve',
-      label: 'Approve',
+      label: decisionLabel('approve', r),
       status: r.transitions.approve,
       verdict: verdictOf('good'),
       tone: 'good',
@@ -276,7 +308,7 @@ export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
   if (!r.omitNeedsWork && entry && (editVerdict || entry !== r.transitions.approve)) {
     out.push({
       key: 'needs_work',
-      label: 'Needs work',
+      label: decisionLabel('needs_work', r),
       status: entry,
       verdict: editVerdict,
       tone: 'neutral',
@@ -289,7 +321,7 @@ export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
   if (r.transitions.reject) {
     out.push({
       key: 'reject',
-      label: 'Reject',
+      label: decisionLabel('reject', r),
       status: r.transitions.reject,
       verdict: verdictOf('bad'),
       tone: 'bad',

package/src/components/facet-tree/FacetTree.tsx

@@ -0,0 +1,250 @@
+'use client'
+
+/**
+ * THE TREE, drawn from a level cache and nothing else.
+ *
+ * Purely presentational: every row it renders comes out of `levels[under]` for
+ * the container it is currently rendering, so the security property described in
+ * `useFacetLevels` survives the render. There is no path arithmetic here at all
+ * — `node.path` is what the server said and it is what goes to the next frame.
+ *
+ * A11Y, AND WHAT IT DELIBERATELY DOES NOT CLAIM. This is a `<ul>` of disclosure
+ * buttons, not a `role="tree"`. The full WAI-ARIA tree pattern owes a reader
+ * roving-tabindex focus management and arrow-key traversal; claiming the roles
+ * without them tells a screen reader to expect navigation that is not there,
+ * which is worse than the plain list this actually is. Tab reaches every control
+ * natively, `aria-expanded` states the disclosure, `aria-current` states the
+ * selection, and each row's name is spelled out rather than left to the DOM.
+ */
+
+import * as React from 'react'
+import { FACET_ROOT } from './path'
+import { EMPTY_LEVEL } from './types'
+import type { FacetLevelState } from './types'
+
+export type FacetTreeSlot = 'root' | 'node' | 'nodeSelected' | 'count' | 'muted' | 'error' | 'more'
+
+const DEFAULTS: Record<FacetTreeSlot, string> = {
+  root: 'space-y-0.5',
+  node: 'flex min-w-0 flex-1 items-center gap-1.5 rounded-md px-2 py-1 text-left text-sm hover:bg-accent hover:text-accent-foreground',
+  nodeSelected: 'bg-accent font-medium text-accent-foreground',
+  count: 'ml-auto shrink-0 text-xs tabular-nums opacity-60',
+  muted: 'px-2 py-1 text-xs text-muted-foreground',
+  error: 'px-2 py-1 text-xs text-destructive',
+  more: 'px-2 py-1 text-xs font-medium underline underline-offset-2 opacity-80 hover:opacity-100 disabled:no-underline disabled:opacity-50',
+}
+
+export interface FacetTreeProps {
+  levels: Record<string, FacetLevelState>
+  expanded: Record<string, boolean>
+  /** The full path currently in scope, or `null` for "no bound at all". */
+  selected: string | null
+  /** Handed a full path the server returned, verbatim. */
+  onSelect: (path: string) => void
+  onToggle: (path: string) => void
+  onMore: (under: string, page: number) => void
+  /** The top of the tree. `/` means everything. */
+  root?: string
+  /**
+   * The noun in a row's accessible name — "record", "document", "topic".
+   *
+   * "INSIDE" is appended rather than "matching", because the number is
+   * DESCENDANTS: a reader who has narrowed the list would otherwise hear
+   * "Acme, 8 records" beside a list of none. The word has to stay true whatever
+   * the list is currently bounded to.
+   */
+  countNoun?: string
+  /** The noun in "Show N more …" — "folder", "scope", "category". */
+  nodeNoun?: string
+  /** Pixels of indent per level. */
+  indent?: number
+  classNames?: Partial<Record<FacetTreeSlot, string>>
+}
+
+export function FacetTree({
+  levels,
+  expanded,
+  selected,
+  onSelect,
+  onToggle,
+  onMore,
+  root = FACET_ROOT,
+  countNoun = 'record',
+  nodeNoun = 'item',
+  indent = 14,
+  classNames = {},
+}: FacetTreeProps) {
+  const cn = { ...DEFAULTS, ...classNames }
+  const top = levels[root] ?? EMPTY_LEVEL
+
+  return (
+    <div className={cn.root}>
+      {top.loading && top.rows.length === 0 ? <p className={cn.muted}>Loading…</p> : null}
+      {top.error ? (
+        <p className={cn.error} role="alert">
+          {top.error}
+        </p>
+      ) : null}
+      <FacetLevel
+        under={root}
+        depth={0}
+        levels={levels}
+        expanded={expanded}
+        selected={selected}
+        onSelect={onSelect}
+        onToggle={onToggle}
+        onMore={onMore}
+        countNoun={countNoun}
+        nodeNoun={nodeNoun}
+        indent={indent}
+        classNames={cn}
+      />
+    </div>
+  )
+}
+
+// ---------------------------------------------------------------------------
+
+/**
+ * The children of ONE container, and recursively the expanded ones among them.
+ *
+ * It reads `levels[under]` and nothing else — the whole map travels down only so
+ * that recursion needs no context, and each frame touches exactly its own key.
+ */
+function FacetLevel({
+  under,
+  depth,
+  levels,
+  expanded,
+  selected,
+  onSelect,
+  onToggle,
+  onMore,
+  countNoun,
+  nodeNoun,
+  indent,
+  classNames: cn,
+}: {
+  under: string
+  depth: number
+  levels: Record<string, FacetLevelState>
+  expanded: Record<string, boolean>
+  selected: string | null
+  onSelect: (path: string) => void
+  onToggle: (path: string) => void
+  onMore: (under: string, page: number) => void
+  countNoun: string
+  nodeNoun: string
+  indent: number
+  classNames: Record<FacetTreeSlot, string>
+}) {
+  const level = levels[under]
+  if (!level) return null
+  const remaining = level.total - level.rows.length
+
+  return (
+    <ul className="space-y-0.5">
+      {level.rows.map((node) => {
+        const open = Boolean(expanded[node.path])
+        const child = levels[node.path]
+        return (
+          <li key={node.path}>
+            <div className="flex items-center">
+              {/* Indent by DEPTH, not by counting separators in the path — a
+                  stored path with a doubled slash would indent wrongly, and the
+                  depth is a fact this render already knows. */}
+              <span aria-hidden="true" style={{ width: depth * indent }} className="shrink-0" />
+              {node.hasChildren ? (
+                <button
+                  type="button"
+                  className="w-4 shrink-0 rounded text-xs opacity-50 hover:opacity-100"
+                  aria-expanded={open}
+                  aria-label={`${open ? 'Collapse' : 'Expand'} ${node.name}`}
+                  onClick={() => onToggle(node.path)}
+                >
+                  {open ? '▾' : '▸'}
+                </button>
+              ) : (
+                // A leaf keeps the triangle's width so names stay in one column.
+                <span aria-hidden="true" className="w-4 shrink-0" />
+              )}
+              <button
+                type="button"
+                className={`${cn.node} ${selected === node.path ? cn.nodeSelected : ''}`}
+                aria-current={selected === node.path ? 'true' : undefined}
+                // SPELLED OUT rather than left to the DOM. Two adjacent spans
+                // concatenate with no separator, so the computed name of this
+                // control would be "Acme1204" — which is what a screen reader
+                // would say. The `title` is the FULL path, because the visible
+                // label is only the last segment and a truncated one at that.
+                aria-label={`${node.name}, ${node.count.toLocaleString()} ${countNoun}${node.count === 1 ? '' : 's'} inside`}
+                title={node.path}
+                onClick={() => onSelect(node.path)}
+              >
+                <span className="truncate">{node.name}</span>
+                {/* DESCENDANTS, not direct children — which is why a node can say
+                    1,204 and open onto nothing of its own. */}
+                <span className={cn.count} aria-hidden="true">
+                  {node.count.toLocaleString()}
+                </span>
+              </button>
+            </div>
+
+            {open ? (
+              <>
+                {child?.loading && child.rows.length === 0 ? (
+                  <p className={cn.muted} style={{ paddingLeft: (depth + 1) * indent + 16 }}>
+                    Loading…
+                  </p>
+                ) : null}
+                {child?.error ? (
+                  <p
+                    className={cn.error}
+                    role="alert"
+                    style={{ paddingLeft: (depth + 1) * indent + 16 }}
+                  >
+                    {child.error}
+                  </p>
+                ) : null}
+                <FacetLevel
+                  under={node.path}
+                  depth={depth + 1}
+                  levels={levels}
+                  expanded={expanded}
+                  selected={selected}
+                  onSelect={onSelect}
+                  onToggle={onToggle}
+                  onMore={onMore}
+                  countNoun={countNoun}
+                  nodeNoun={nodeNoun}
+                  indent={indent}
+                  classNames={cn}
+                />
+              </>
+            ) : null}
+          </li>
+        )
+      })}
+
+      {/* MORE AT THIS LEVEL. The server's own `count` for this container against
+          what has been drawn, so a container with 900 children costs one page
+          until somebody asks for the next — rule 8 applies to the tree exactly as
+          it applies to rows. */}
+      {remaining > 0 ? (
+        <li>
+          <button
+            type="button"
+            className={cn.more}
+            disabled={level.loading}
+            style={{ marginLeft: depth * indent + 16 }}
+            onClick={() => onMore(under, level.page + 1)}
+          >
+            {level.loading
+              ? 'Loading…'
+              : `Show ${remaining} more ${nodeNoun}${remaining === 1 ? '' : 's'}`}
+          </button>
+        </li>
+      ) : null}
+    </ul>
+  )
+}

package/src/components/facet-tree/__tests__/facet-tree.test.tsx

@@ -0,0 +1,228 @@
+/**
+ * The facet tree engine (bd startsim-6fceh).
+ *
+ * These pin the two properties that are not obvious from the render: it asks the
+ * server for ONE LEVEL at a time, and it draws each level from that level's own
+ * response and nothing else. The second one is the security property — a tree
+ * that merged responses, or kept a flat set of every node seen, would put on
+ * screen a node the server never returned for this reader.
+ */
+import * as React from 'react'
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+import { FacetTree } from '../FacetTree'
+import { useFacetLevels } from '../useFacetLevels'
+import { facetName, facetTrail, FACET_ROOT } from '../path'
+import type { FacetLevelLoader, FacetLevelQuery, FacetNode, Paginated } from '../types'
+
+function node(path: string, count: number, hasChildren = false): FacetNode {
+  return { path, name: facetName(path), count, hasChildren }
+}
+
+function page(results: FacetNode[], count = results.length): Paginated<FacetNode> {
+  return { count, next: null, previous: null, results }
+}
+
+/** The fixture tree. `/Clients-old` is a SIBLING of `/Clients`, not a child. */
+const TREE: Record<string, Paginated<FacetNode>> = {
+  '/': page([
+    node('/Clients', 1204, true),
+    node('/Clients-old', 3),
+    node('/Internal', 12),
+  ]),
+  '/Clients': page([node('/Clients/Acme', 900, true), node('/Clients/Globex', 300)]),
+  '/Clients/Acme': page([node('/Clients/Acme/GCC Weekly', 41)]),
+}
+
+function loaderFor(tree = TREE): jest.MockedFunction<FacetLevelLoader> {
+  return jest.fn(async (query: FacetLevelQuery) => tree[query.under] ?? page([]))
+}
+
+function Harness({
+  load,
+  pageSize,
+  onUnavailable,
+}: {
+  load?: FacetLevelLoader
+  pageSize?: number
+  onUnavailable?: () => void
+}) {
+  const [selected, setSelected] = React.useState<string | null>(null)
+  const levels = useFacetLevels({ load, pageSize, onUnavailable })
+  return (
+    <>
+      <span data-testid="selected">{selected ?? 'none'}</span>
+      <FacetTree
+        levels={levels.levels}
+        expanded={levels.expanded}
+        selected={selected}
+        onSelect={setSelected}
+        onToggle={levels.toggle}
+        onMore={levels.loadMore}
+        countNoun="record"
+        nodeNoun="scope"
+      />
+    </>
+  )
+}
+
+describe('useFacetLevels — one level per request', () => {
+  it('asks for the root and nothing else on mount', async () => {
+    const load = loaderFor()
+    render(<Harness load={load} />)
+
+    await screen.findByRole('button', { name: /^Clients, 1,204 records inside$/ })
+    expect(load).toHaveBeenCalledTimes(1)
+    expect(load).toHaveBeenCalledWith(expect.objectContaining({ under: FACET_ROOT, page: 1 }))
+  })
+
+  it('draws the disclosure triangle from has_children, with no probe request', async () => {
+    const load = loaderFor()
+    render(<Harness load={load} />)
+
+    await screen.findByRole('button', { name: 'Expand Clients' })
+    // `/Internal` and `/Clients-old` said hasChildren:false, so they get no control.
+    expect(screen.queryByRole('button', { name: 'Expand Internal' })).toBeNull()
+    expect(screen.queryByRole('button', { name: 'Expand Clients-old' })).toBeNull()
+    // Still exactly the one root request — the triangles cost nothing.
+    expect(load).toHaveBeenCalledTimes(1)
+  })
+
+  it('fetches a child level only when it is expanded, and only once', async () => {
+    const user = userEvent.setup()
+    const load = loaderFor()
+    render(<Harness load={load} />)
+
+    await user.click(await screen.findByRole('button', { name: 'Expand Clients' }))
+    await screen.findByRole('button', { name: /^Acme, 900 records inside$/ })
+    expect(load).toHaveBeenCalledWith(expect.objectContaining({ under: '/Clients', page: 1 }))
+    expect(load).toHaveBeenCalledTimes(2)
+
+    // Collapse and re-expand: the level is already known.
+    await user.click(screen.getByRole('button', { name: 'Collapse Clients' }))
+    await user.click(await screen.findByRole('button', { name: 'Expand Clients' }))
+    await screen.findByRole('button', { name: /^Acme, 900 records inside$/ })
+    expect(load).toHaveBeenCalledTimes(2)
+  })
+
+  it('never draws a sibling under the node it merely shares a prefix with', async () => {
+    const user = userEvent.setup()
+    render(<Harness load={loaderFor()} />)
+
+    await user.click(await screen.findByRole('button', { name: 'Expand Clients' }))
+    await screen.findByRole('button', { name: /^Acme, 900 records inside$/ })
+
+    // `/Clients-old` is at the ROOT level and stays there. A prefix match would
+    // have pulled it under `/Clients`; a level cache keyed by `under=` cannot.
+    const clientsList = screen
+      .getByRole('button', { name: /^Acme, 900 records inside$/ })
+      .closest('ul') as HTMLElement
+    expect(clientsList).toBeTruthy()
+    expect(
+      Array.from(clientsList.querySelectorAll('button')).map((b) => b.getAttribute('title')),
+    ).toEqual(expect.not.arrayContaining(['/Clients-old']))
+    expect(screen.getByRole('button', { name: /^Clients-old, 3 records inside$/ })).toBeTruthy()
+  })
+
+  it('hands back the full path the server returned, verbatim', async () => {
+    const user = userEvent.setup()
+    render(<Harness load={loaderFor()} />)
+
+    await user.click(await screen.findByRole('button', { name: 'Expand Clients' }))
+    await user.click(await screen.findByRole('button', { name: /^Acme, 900 records inside$/ }))
+    expect(screen.getByTestId('selected')).toHaveTextContent('/Clients/Acme')
+  })
+
+  it('goes three levels deep, one request per level', async () => {
+    const user = userEvent.setup()
+    const load = loaderFor()
+    render(<Harness load={load} />)
+
+    await user.click(await screen.findByRole('button', { name: 'Expand Clients' }))
+    await user.click(await screen.findByRole('button', { name: 'Expand Acme' }))
+    await screen.findByRole('button', { name: /^GCC Weekly, 41 records inside$/ })
+    expect(load).toHaveBeenCalledTimes(3)
+  })
+})
+
+describe('useFacetLevels — paging', () => {
+  it('offers the server’s remaining count and appends the next page', async () => {
+    const user = userEvent.setup()
+    const first = page([node('/A', 1), node('/B', 2)], 4)
+    const second = page([node('/C', 3), node('/D', 4)], 4)
+    const load = jest.fn(async (query: FacetLevelQuery) => (query.page === 1 ? first : second))
+
+    render(<Harness load={load} pageSize={2} />)
+
+    const more = await screen.findByRole('button', { name: 'Show 2 more scopes' })
+    expect(load).toHaveBeenCalledWith({ under: '/', page: 1, pageSize: 2 })
+
+    await user.click(more)
+    await screen.findByRole('button', { name: /^D, 4 records inside$/ })
+    // APPENDED, not replaced.
+    expect(screen.getByRole('button', { name: /^A, 1 record inside$/ })).toBeTruthy()
+    expect(screen.queryByRole('button', { name: /Show .* more/ })).toBeNull()
+    expect(load).toHaveBeenLastCalledWith({ under: '/', page: 2, pageSize: 2 })
+  })
+
+  it('says "1 more scope" rather than "1 more scopes"', async () => {
+    const load = jest.fn(async () => page([node('/A', 1)], 2))
+    render(<Harness load={load} />)
+    expect(await screen.findByRole('button', { name: 'Show 1 more scope' })).toBeTruthy()
+  })
+})
+
+describe('useFacetLevels — a deployment that cannot answer', () => {
+  it.each([404, 400, 501])('treats %s as "no tree here" and says so once', async (status) => {
+    const onUnavailable = jest.fn()
+    const load = jest.fn(async () => {
+      throw Object.assign(new Error('nope'), { status })
+    })
+    render(<Harness load={load} onUnavailable={onUnavailable} />)
+
+    await waitFor(() => expect(onUnavailable).toHaveBeenCalledTimes(1))
+    expect(screen.queryByRole('alert')).toBeNull()
+  })
+
+  it('reports a real failure on screen instead of pretending there is no tree', async () => {
+    const onUnavailable = jest.fn()
+    const load = jest.fn(async () => {
+      throw Object.assign(new Error('Boom'), { status: 500 })
+    })
+    render(<Harness load={load} onUnavailable={onUnavailable} />)
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('Boom')
+    expect(onUnavailable).not.toHaveBeenCalled()
+  })
+
+  it('names the 401 and 403 cases in words a reader can act on', async () => {
+    const load = jest.fn(async () => {
+      throw Object.assign(new Error('x'), { status: 401 })
+    })
+    render(<Harness load={load} />)
+    expect(await screen.findByRole('alert')).toHaveTextContent(/session has expired/i)
+  })
+
+  it('reports unavailable when the client has no loader at all', async () => {
+    const onUnavailable = jest.fn()
+    render(<Harness onUnavailable={onUnavailable} />)
+    await waitFor(() => expect(onUnavailable).toHaveBeenCalledTimes(1))
+  })
+})
+
+describe('path helpers', () => {
+  it('names a node by its last segment only', () => {
+    expect(facetName('/Clients/Acme/GCC Weekly')).toBe('GCC Weekly')
+    expect(facetName('/Clients')).toBe('Clients')
+    expect(facetName('/')).toBe('/')
+  })
+
+  it('builds a trail of ancestors, each carrying a whole path', () => {
+    expect(facetTrail('/A/B/C')).toEqual([
+      { path: '/A', name: 'A' },
+      { path: '/A/B', name: 'B' },
+      { path: '/A/B/C', name: 'C' },
+    ])
+  })
+})