@startsimpli/ui 0.4.110 → 0.4.111

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

@@ -0,0 +1,89 @@
+/**
+ * The wire shape of a lazily-paged, server-navigable tree over a materialized
+ * path attribute — `GET /api/v1/entities/facets/?type=<t>&attr=<a>&under=/x`.
+ *
+ * DELIBERATELY FIELD-IDENTICAL TO `CorpusFolder` / `FolderQuery` / `CorpusPage`
+ * in `@startsimpli/integrations` (bd startsim-ei8gm.5). That package built the
+ * first consumer of this API — the Library folder tree — and it cannot import
+ * this one (neither package depends on the other today, see bd startsim-6fceh's
+ * notes). Keeping the field names identical means the day the two converge is a
+ * rename and a re-export, not a redesign.
+ *
+ * `Paginated<T>` is reused from `../collection/types` rather than minted a third
+ * time: the server hands back one DRF envelope and this package should describe
+ * it once.
+ */
+import type { Paginated } from '../collection/types'
+
+export type { Paginated }
+
+/**
+ * ONE NODE of the tree, exactly as `/entities/facets/` describes it.
+ *
+ * Every field here is answered by the SAME response that listed the node, which
+ * is what makes a lazy tree cost one request per expanded level and no probe
+ * request per node.
+ */
+export interface FacetNode {
+  /**
+   * The FULL path, as the server returned it — `/Clients/Acme`, never `Acme`.
+   *
+   * It goes straight back out unmodified as the next `under=` and as the value
+   * a consumer filters by. The client never joins segments; see `./path.ts`.
+   */
+  path: string
+  /** The last segment, for display only. Derived from `path`, never sent back. */
+  name: string
+  /**
+   * DESCENDANT records, not direct children — `/Clients` counts the rows under
+   * `/Clients/Acme/GCC` too. That is the number a person reading a collapsed
+   * node wants, and it is why a node can say 1,204 and open onto nothing of its
+   * own.
+   */
+  count: number
+  /**
+   * Whether anything sits BELOW this node. The disclosure control, answered by
+   * the response that listed the node — so drawing a triangle costs no extra
+   * request.
+   */
+  hasChildren: boolean
+}
+
+/**
+ * ONE LEVEL of the tree. `under` is a path the server previously returned, or
+ * `FACET_ROOT` (`/`) for the top, which means everything.
+ */
+export interface FacetLevelQuery {
+  under: string
+  page?: number
+  pageSize?: number
+}
+
+/**
+ * The single read a tree needs, injected. A caller hands in a method off its own
+ * authed client; this package never constructs a request of its own.
+ *
+ * IT MUST BE REFERENTIALLY STABLE across renders. Its identity is the reset key:
+ * a new loader means a new principal or a new workspace, and everything already
+ * fetched was gated for the OLD one, so it is dropped rather than reused.
+ */
+export type FacetLevelLoader = (query: FacetLevelQuery) => Promise<Paginated<FacetNode>>
+
+/** What is known about ONE container's children. Keyed by that container's path. */
+export interface FacetLevelState {
+  rows: FacetNode[]
+  /** The server's own total for this container, so "is there more" is not guessed. */
+  total: number
+  /** Highest page fetched for THIS container. */
+  page: number
+  loading: boolean
+  error: string
+}
+
+export const EMPTY_LEVEL: FacetLevelState = {
+  rows: [],
+  total: 0,
+  page: 0,
+  loading: false,
+  error: '',
+}

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

@@ -0,0 +1,197 @@
+'use client'
+
+/**
+ * THE LEVEL CACHE — the whole state machine of a lazily-paged tree, with no
+ * opinion about what the tree is a tree OF.
+ *
+ * ONE LEVEL PER REQUEST, PAGED (CLAUDE.md rule 8). Expanding a node asks the
+ * server for that node's children and nothing else. The alternative — read every
+ * record's path and assemble the tree in the browser — works on today's rows and
+ * expires in the low thousands, and it is the failure `/entities/facets/`
+ * (start-simpli-api#391) was shipped to end.
+ *
+ * THE SECURITY PROPERTY IS THE SHAPE OF THE STATE, and it is why `levels` is a
+ * map keyed by `under=` rather than a flat set of nodes seen. The facet read is
+ * gated server-side out of `EntityViewSet.get_queryset()` itself, so a member is
+ * shown the containers their own readable rows are in — and a container name
+ * leaks plenty on its own (`/Clients/Acquisition-TargetCo`). So every
+ * container's children are stored under that container's OWN key and rendered
+ * from that key alone. Nothing here merges two responses, fills one level from
+ * another level's answer, or infers a parent from a child: each of those would
+ * put on screen a node the server never returned for THIS reader, which is the
+ * leak rebuilt in the browser out of rows the server was careful about.
+ */
+
+import * as React from 'react'
+import { FACET_ROOT } from './path'
+import { EMPTY_LEVEL } from './types'
+import type { FacetLevelLoader, FacetLevelState } from './types'
+
+export interface UseFacetLevelsOptions {
+  /**
+   * The injected read. OPTIONAL because a client can legitimately not offer one
+   * — an older fork has no facet route at all — and the honest response to that
+   * is the same as to a 404: no tree.
+   *
+   * MUST BE STABLE. See `FacetLevelLoader`; its identity is the reset key.
+   */
+  load?: FacetLevelLoader
+  /** Nodes per request. The server pages; this is the page size it is asked for. */
+  pageSize?: number
+  /** The top of the tree. `/` means everything. */
+  root?: string
+  /**
+   * Set false to hold every request. A switcher that has never been opened needs
+   * no data — its label comes from the URL — so a closed one costs no round trip.
+   */
+  enabled?: boolean
+  /**
+   * Told once when this data source cannot enumerate the tree at all — a fork
+   * that predates the facet route 404s, an older one 400s. A consumer uses it to
+   * stop reserving space for a tree that will never draw.
+   */
+  onUnavailable?: () => void
+}
+
+export interface FacetLevels {
+  levels: Record<string, FacetLevelState>
+  expanded: Record<string, boolean>
+  /** True once the source has said, in any of its several dialects, "no tree here". */
+  unavailable: boolean
+  levelOf: (under: string) => FacetLevelState
+  toggle: (path: string) => void
+  loadMore: (under: string, page: number) => void
+  /** Fetch a container's first page if it has never been asked for. Idempotent. */
+  ensure: (under: string) => void
+}
+
+function failure(err: unknown): string {
+  const status = (err as { status?: number })?.status
+  if (status === 401) return 'Your session has expired. Sign in again.'
+  if (status === 403) return 'You do not have access to these.'
+  return (err as { message?: string })?.message || 'Could not load.'
+}
+
+/**
+ * A 404/400 means "this deployment has no tree enumeration", not "no nodes".
+ *
+ * BOTH CODES, because both are real deployments. A fork built before
+ * start-simpli-api#391 has no `/entities/facets/` route and answers 404; one
+ * built before the parameters were in its vocabulary screens `attr`/`under` as
+ * unknown and answers 400. To a reader they mean the same thing.
+ */
+export function isTreeUnsupported(err: unknown): boolean {
+  const status = (err as { status?: number })?.status
+  return status === 404 || status === 400 || status === 501
+}
+
+export function useFacetLevels({
+  load,
+  pageSize = 100,
+  root = FACET_ROOT,
+  enabled = true,
+  onUnavailable,
+}: UseFacetLevelsOptions): FacetLevels {
+  const [levels, setLevels] = React.useState<Record<string, FacetLevelState>>({})
+  const [expanded, setExpanded] = React.useState<Record<string, boolean>>({})
+  const [unavailable, setUnavailable] = React.useState(false)
+
+  /** Containers already asked for, so a re-render or a re-open costs nothing. */
+  const requested = React.useRef<Set<string>>(new Set())
+  const told = React.useRef(false)
+
+  // A new loader means a new principal or a new workspace. Everything already
+  // fetched was gated for the OLD one, so it is dropped rather than reused — a
+  // stale level is exactly the leak this file is careful about.
+  React.useEffect(() => {
+    requested.current = new Set()
+    told.current = false
+    setLevels({})
+    setExpanded({})
+    setUnavailable(false)
+  }, [load])
+
+  const fetchLevel = React.useCallback(
+    async (under: string, page: number) => {
+      if (!load) {
+        setUnavailable(true)
+        return
+      }
+      setLevels((prev) => ({
+        ...prev,
+        [under]: { ...(prev[under] ?? EMPTY_LEVEL), loading: true, error: '' },
+      }))
+      try {
+        const result = await load({ under, page, pageSize })
+        setLevels((prev) => {
+          const before = prev[under] ?? EMPTY_LEVEL
+          return {
+            ...prev,
+            [under]: {
+              // APPEND, and only ever within this same `under=`. Page 2 of a
+              // container is more of the answer the server already gave about
+              // that container; it is not evidence about any other one.
+              rows: page > 1 ? [...before.rows, ...result.results] : result.results,
+              total: result.count,
+              page,
+              loading: false,
+              error: '',
+            },
+          }
+        })
+      } catch (err) {
+        if (isTreeUnsupported(err)) {
+          setUnavailable(true)
+          return
+        }
+        setLevels((prev) => ({
+          ...prev,
+          [under]: { ...(prev[under] ?? EMPTY_LEVEL), loading: false, error: failure(err) },
+        }))
+      }
+    },
+    [load, pageSize],
+  )
+
+  /**
+   * The ref rather than a check on `levels`, because the guard has to hold
+   * BETWEEN renders — two clicks in the same tick, or a StrictMode
+   * double-invoke, would otherwise both see an empty map and both fetch.
+   */
+  const ensure = React.useCallback(
+    (under: string) => {
+      if (requested.current.has(under)) return
+      requested.current.add(under)
+      void fetchLevel(under, 1)
+    },
+    [fetchLevel],
+  )
+
+  React.useEffect(() => {
+    if (enabled && !unavailable) ensure(root)
+  }, [ensure, enabled, unavailable, root])
+
+  React.useEffect(() => {
+    if (unavailable && !told.current) {
+      told.current = true
+      onUnavailable?.()
+    }
+  }, [unavailable, onUnavailable])
+
+  const toggle = React.useCallback(
+    (path: string) => {
+      setExpanded((prev) => ({ ...prev, [path]: !prev[path] }))
+      // Idempotent, so calling it on a COLLAPSE is free — and calling it here
+      // rather than inside the updater above keeps the updater pure.
+      ensure(path)
+    },
+    [ensure],
+  )
+
+  const levelOf = React.useCallback(
+    (under: string) => levels[under] ?? EMPTY_LEVEL,
+    [levels],
+  )
+
+  return { levels, expanded, unavailable, levelOf, toggle, loadMore: fetchLevel, ensure }
+}

package/src/components/index.ts

@@ -190,3 +190,49 @@ export * from './validation'
 // scorecard) + ReviewNotes (critique thread). Controlled + presentational; light
 // (React + lucide only), so they ride the main barrel like health / validation.
 export * from './review'
+
+// Scope switcher (bd startsim-6fceh) + the data-agnostic facet tree it is built
+// on. Named exports rather than `export *` so the DRF `Paginated` envelope does
+// not enter the main barrel — it belongs to the '@startsimpli/ui/collection'
+// contract and re-exporting it here would give it two homes.
+export {
+  ScopeSwitcher,
+  ScopeSwitcherControlled,
+  useScopeParam,
+  createScopeClient,
+  SCOPE_PARAM,
+  SCOPE_ALL,
+} from './scope'
+export type {
+  ScopeSwitcherProps,
+  ScopeSwitcherControlledProps,
+  ScopeSwitcherBaseProps,
+  ScopeSwitcherLabels,
+  ScopeParam,
+  UseScopeParamOptions,
+  ScopeClient,
+  ScopeNode,
+  ScopeMatch,
+  ScopeSearchQuery,
+  ScopeHttp,
+  CreateScopeClientOptions,
+} from './scope'
+export {
+  FacetTree,
+  useFacetLevels,
+  isTreeUnsupported,
+  facetName,
+  facetTrail,
+  FACET_ROOT,
+  PATH_SEPARATOR,
+} from './facet-tree'
+export type {
+  FacetTreeProps,
+  FacetTreeSlot,
+  FacetLevels,
+  UseFacetLevelsOptions,
+  FacetNode,
+  FacetLevelQuery,
+  FacetLevelLoader,
+  FacetLevelState,
+} from './facet-tree'