@startsimpli/ui 0.4.110 → 0.4.111

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.110",
+  "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",
@@ -45,9 +47,9 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
+    "@startsimpli/api": "^0.5.58",
     "@startsimpli/auth": "^0.4.35",
-    "@startsimpli/i18n": "^0.1.3",
-    "@startsimpli/api": "^0.5.58"
+    "@startsimpli/i18n": "^0.1.3"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -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/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' },
+    ])
+  })
+})

package/src/components/facet-tree/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @startsimpli/ui/facet-tree — a lazily-paged, server-navigable tree over a
+ * materialized path attribute.
+ *
+ * DATA-AGNOSTIC ON PURPOSE. It knows about `{path, name, count, hasChildren}`
+ * and an injected `load({under, page, pageSize})`, and nothing else — not what a
+ * scope is, not what a document is. `ScopeSwitcher` (`../scope`) is the first
+ * consumer; the Library folder tree in `@startsimpli/integrations` is the second
+ * one waiting to converge onto it (bd startsim-6fceh's notes carry that bead).
+ */
+export { FACET_ROOT, PATH_SEPARATOR, facetName, facetTrail } from './path'
+export { FacetTree, type FacetTreeProps, type FacetTreeSlot } from './FacetTree'
+export {
+  useFacetLevels,
+  isTreeUnsupported,
+  type FacetLevels,
+  type UseFacetLevelsOptions,
+} from './useFacetLevels'
+export {
+  EMPTY_LEVEL,
+  type FacetNode,
+  type FacetLevelQuery,
+  type FacetLevelLoader,
+  type FacetLevelState,
+  type Paginated,
+} from './types'

package/src/components/facet-tree/path.ts

@@ -0,0 +1,55 @@
+/**
+ * Path arithmetic for a materialized-path tree — the ONLY file in this folder
+ * allowed to take a path apart, and only ever for DISPLAY.
+ *
+ * The rule the rest of the tree obeys: a path the server returned goes back out
+ * VERBATIM as the next `under=` and as the next `?attr.<name>=`. A client that
+ * re-joins segments has a small escaping bug in it, and the server returns whole
+ * paths precisely so that nobody has to. Both helpers below take apart a string
+ * the server already handed to THIS reader, purely to label a control; neither
+ * synthesizes a node, and nothing here is ever sent back to the server.
+ */
+
+/** The separator the tenant declares at `/api/v1/capabilities/#path_separator`. */
+export const PATH_SEPARATOR = '/'
+
+/**
+ * The root of any materialized-path tree.
+ *
+ * `under=/` means EVERYTHING, not "the top-level rows": the server's
+ * `subtree_bound()` makes the root's descendant prefix `/`, which every stored
+ * path begins with. It is the reading a person expects from the top of a file
+ * browser.
+ */
+export const FACET_ROOT = PATH_SEPARATOR
+
+/** The last segment of a full path, for display. `/A/B` -> `B`. */
+export function facetName(path: string): string {
+  const segments = String(path ?? '')
+    .split(PATH_SEPARATOR)
+    .filter(Boolean)
+  return segments.length > 0 ? segments[segments.length - 1] : String(path ?? '')
+}
+
+/**
+ * The ancestors of a path, for a breadcrumb — `/A/B/C` -> `/A`, `/A/B`, `/A/B/C`.
+ *
+ * SPLITTING IS SAFE HERE and the module header's rule still holds, because this
+ * is not the act that rule forbids. It puts no node on screen that the server did
+ * not already name to this reader, and fills no level from another level's
+ * response. The forbidden act is SYNTHESISING a node — deciding that a container
+ * exists, or what is in it, from data the server did not return about it — and a
+ * breadcrumb over a path the reader is already holding does none of that.
+ */
+export function facetTrail(path: string): Array<{ path: string; name: string }> {
+  const segments = String(path ?? '')
+    .split(PATH_SEPARATOR)
+    .filter(Boolean)
+  const trail: Array<{ path: string; name: string }> = []
+  let at = ''
+  for (const segment of segments) {
+    at = `${at}${PATH_SEPARATOR}${segment}`
+    trail.push({ path: at, name: segment })
+  }
+  return trail
+}