@startsimpli/ui 0.4.110 → 0.4.112

package/src/components/collection/scoped-client.ts

@@ -0,0 +1,155 @@
+/**
+ * THE ONE SEAM (bd startsim-nq39j, epic startsim-ux39t).
+ *
+ * `withScope(client, scope)` returns a `CollectionClient` whose LIST reads carry
+ * the active scope and whose WRITES cannot cross one. Because every review
+ * surface in this package is client-injected — the app wrapper is ~10 LOC and
+ * hands in its authed tenant API — wrapping that one object scopes the whole
+ * surface at once. Nothing else in `collection/` knows what a scope is, and
+ * nothing else should learn: a second place that narrows is a second place that
+ * can forget to.
+ *
+ * THE WIRE SPELLING OF "EVERYTHING" IS SILENCE, and this is the decision the
+ * bead asked to be taken deliberately. The BROWSER URL spells it `?scope=all`
+ * (`SCOPE_ALL`), because there a missing parameter has to stay distinguishable
+ * from an asserted one — see `../scope/useScopeParam`. The WIRE cannot borrow
+ * that spelling and must not borrow the empty one either:
+ *
+ *   • `?scope=all` is a 400 — every stored path begins with the separator, so a
+ *     value that does not is refused as a value that could only match nothing.
+ *   • `?scope=` (blank) is ALSO a 400, and it is the dangerous one:
+ *     `normalize_container("")` returns `/`, so the obvious implementation reads
+ *     an empty parameter as EVERY scoped row (bd startsim-mj609).
+ *
+ * So "no scope" OMITS THE KEY. That is not merely the safe encoding, it is the
+ * only correct one: an omitted parameter returns unscoped rows too, which today
+ * is every row, while `?scope=/` would return only rows that carry a path.
+ *
+ * A PATH IS PASSED THROUGH VERBATIM, INCLUDING A BAD ONE. A value that is not
+ * `all` and not blank goes on the wire as the caller wrote it, even without a
+ * leading separator, because the server refuses that and a refusal is a better
+ * answer than a client that quietly drops a narrowing it did not understand.
+ *
+ * REFERENTIALLY STABLE OR NOT AT ALL. The returned client is the query key's
+ * input and react-query's identity for the injected API; building a new one on
+ * every render is the same mistake as building a new `ScopeClient` on every
+ * render (see `../scope/types.ts`). Memoize it on the scope, or use
+ * `useScopedCollectionClient` from `@startsimpli/ui/scope`, which does.
+ */
+import type { CollectionClient, EntityFilters, ListEntitiesOptions } from './types';
+
+/**
+ * The query parameter the tenant recognises. It is a plain lowercase word, so
+ * unlike `attr.x__gte` it survives a camel/snake rewrite unharmed — but it still
+ * travels the {@link EntityFilters} path, because one narrowing mechanism is the
+ * whole point of `EntityFilters` existing.
+ */
+export const SCOPE_FILTER = 'scope';
+
+/**
+ * The URL's reserved word for "no bound at all". Recognised here as well as in
+ * `useScopeParam` because a caller can reach a raw `?scope=` value without going
+ * through the hook — a server component reading `searchParams`, a test, an app
+ * that keeps the scope somewhere else — and `all` must mean the same thing to
+ * every one of them.
+ */
+const SCOPE_ALL_VALUE = 'all';
+
+/**
+ * A `CollectionClient` that knows what it is bounded to.
+ *
+ * `scope` is exposed for ONE reason and it is not decoration: a cached read is
+ * only valid for the scope it was made under, so a consumer's react-query key
+ * has to name it. {@link scopeKey} is that read.
+ */
+export interface ScopedCollectionClient extends CollectionClient {
+  /** The active path, or `null` for no bound. */
+  readonly scope: string | null;
+}
+
+/**
+ * Resolve any spelling of a scope to the one the wire uses: a path, or `null`.
+ *
+ * `null`, `undefined`, empty, whitespace and the reserved `all` all resolve to
+ * `null` — "no bound" — and `null` is spelled on the wire by sending nothing.
+ */
+export function resolveScope(scope: string | null | undefined): string | null {
+  if (typeof scope !== 'string') return null;
+  const trimmed = scope.trim();
+  if (!trimmed || trimmed === SCOPE_ALL_VALUE) return null;
+  return trimmed;
+}
+
+/**
+ * The filters a scope contributes to a list read — `{}` when there is no bound.
+ *
+ * IT RETURNS AN ABSENT KEY, NOT AN EMPTY ONE. `{ scope: '' }` is a 400 that
+ * would be read as "the root" by an unlucky implementation; the only encoding of
+ * "everything" this package will ever put on the wire is no key at all.
+ */
+export function scopeFilters(scope: string | null | undefined): EntityFilters {
+  const resolved = resolveScope(scope);
+  return resolved === null ? {} : { [SCOPE_FILTER]: resolved };
+}
+
+/**
+ * The cache-key fragment for a client's bound. `'all'` for no bound, so an
+ * UNWRAPPED client (a plain `CollectionClient`, which has no `scope` at all)
+ * keys identically to an explicitly unbounded one and an existing consumer's
+ * cache does not split in two for no reason.
+ */
+export function scopeKey(client: Pick<ScopedCollectionClient, 'scope'> | CollectionClient | null | undefined): string {
+  const scope = (client as ScopedCollectionClient | null | undefined)?.scope;
+  return resolveScope(scope) ?? SCOPE_ALL_VALUE;
+}
+
+/**
+ * Bind a `CollectionClient` to a scope.
+ *
+ * LIST reads gain `?scope=<path>`; WRITES are handed on BYTE-FOR-BYTE. A write
+ * that carried the active scope would be able to MOVE a row: patch a row while
+ * `/clients/acme` is selected and it would silently leave `/clients/globex`.
+ * Changing a row's scope is an explicit act with its own affordance, never a
+ * side effect of editing it somewhere. (The bead's phrase "writes stamp it"
+ * belongs to CREATE, on the scope-aware upsert path — there is no create on this
+ * interface, so there is nothing here to stamp.)
+ */
+export function withScope(
+  client: CollectionClient,
+  scope: string | null | undefined,
+): ScopedCollectionClient {
+  const resolved = resolveScope(scope);
+
+  return {
+    scope: resolved,
+
+    // Passed on with NO arguments at all. The schema read carries no `?type=`,
+    // and `?scope=` without `?type=` is a 400 (bd startsim-mj609) — so this is
+    // not an omission to tidy up later, it is the refusal being respected.
+    listTypes: () => client.listTypes(),
+
+    listAllEntities: (type: string, options?: ListEntitiesOptions) => {
+      // A type-less list read cannot carry a scope for the same reason
+      // `listTypes` cannot: the parameter resolves through ONE type's
+      // declaration. A blank type is already a bad request; adding a scope to it
+      // would turn a legible 400 into a confusing one.
+      const scopable = typeof type === 'string' && type.trim() !== '';
+      const applies = scopable && options?.scoped !== false;
+      const extra = applies ? scopeFilters(resolved) : {};
+      // Merged UNDER the caller's own filters, not over them: a consumer that
+      // deliberately sent its own `scope` (a fixture, a one-off drill-down)
+      // means it, and the decorator does not overrule it.
+      const filters: EntityFilters = { ...extra, ...(options?.filters ?? {}) };
+      const next: ListEntitiesOptions = { ...options, filters };
+      // No filters and no options in means no options through — an
+      // implementation that only ever took `(type)` sees exactly what it did
+      // before, so wrapping an old client is not a behaviour change.
+      if (Object.keys(filters).length === 0 && options === undefined) {
+        return client.listAllEntities(type);
+      }
+      return client.listAllEntities(type, next);
+    },
+
+    updateEntity: (id, input) => client.updateEntity(id, input),
+  };
+}

package/src/components/collection/types.ts

@@ -42,13 +42,64 @@ export interface Paginated<T> {
   results: T[];
 }
 
+/**
+ * Server-side narrowing, spelled EXACTLY as the wire spells it — `type`,
+ * `scope`, `attr.published_at__gte`, `attr.topic_ref__in`. The value is a string
+ * because it is a query-string value and nothing else.
+ *
+ * THE KEY GOES IN THE URL, NEVER THROUGH A CLIENT'S `params` BAG. The shared
+ * `@startsimpli/api` client rewrites request keys between camelCase and
+ * snake_case, and `attr.published_at__gte` is neither — it comes out mangled,
+ * the server does not recognise it, and (on an image with
+ * TENANT_ALLOW_UNKNOWN_FILTERS on) reads as "no filter" rather than as an
+ * error. That is a widening, and a widening under an active filter chip is the
+ * failure that cost nine production tandem rows on 2026-08-27. The fork's
+ * `listEntities` already builds the query string itself for this reason and is
+ * guarded by its own `src/lib/__tests__/entity-filters.test.ts`; this type is
+ * the same contract, named, so a `CollectionClient` implementation inherits the
+ * requirement instead of rediscovering it.
+ */
+export type EntityFilters = Record<string, string>;
+
+/**
+ * How a list read is narrowed. Deliberately the SAME SHAPE the fork's
+ * `listAllEntities(type, { filters })` already accepts (bd startsim-nq39j), so
+ * the existing, tested filter path is extended rather than joined by a second
+ * one — an app that already implements it satisfies this interface unchanged.
+ */
+export interface ListEntitiesOptions {
+  /** Server-side narrowing — see {@link EntityFilters}. */
+  filters?: EntityFilters;
+  /**
+   * Opt this read OUT of the active scope. Default: scoped.
+   *
+   * THE SHARED CORPUS IS WHY THIS EXISTS (epic startsim-ux39t, decision 2: "one
+   * news_item corpus, one source registry"). A source registry or an article
+   * corpus is subscribed to by several scopes rather than ingested per scope, so
+   * narrowing a LOOKUP read of one to the active scope answers the wrong
+   * question: either the type declares no scope path and the server 400s
+   * (`?scope=` on an unscoped type is a refusal, bd startsim-mj609), or it does
+   * and the lookup silently loses every row outside the bound. Deliverable reads
+   * — the topics and drafts a client is owed — stay scoped.
+   *
+   * The polarity is deliberate: forgetting this flag NARROWS loudly, it never
+   * widens silently. Do not delete it as dead config.
+   */
+  scoped?: boolean;
+}
+
 /**
  * The tenant-API surface a review workspace needs. The app implements this over
  * its authed same-origin client (keys are camel/snake-normalized by that client;
  * PATCH replaces the whole data blob, so callers send the full merged data).
+ *
+ * `listTypes` TAKES NO NARROWING AND MUST NOT. It is a schema read with no
+ * `?type=`, and `?scope=` REQUIRES `?type=` server-side — a 400, by design,
+ * because the parameter resolves through one type's declaration and an
+ * unfiltered list spans many (bd startsim-mj609).
  */
 export interface CollectionClient {
   listTypes(): Promise<Paginated<EntityTypeDef>>;
-  listAllEntities(type: string): Promise<EntityRecord[]>;
+  listAllEntities(type: string, options?: ListEntitiesOptions): Promise<EntityRecord[]>;
   updateEntity(id: number | string, input: { name?: string; data?: Record<string, unknown> }): Promise<EntityRecord>;
 }

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>
+  )
+}