@startsimpli/ui 0.4.110 → 0.4.111

package/src/components/scope/client.ts

@@ -0,0 +1,145 @@
+/**
+ * A `ScopeClient` over the tenant data plane's generic `/api/v1/entities/*`
+ * endpoints — the ONE place in this package that knows how a scope is stored.
+ *
+ * It exists so that every app does not re-derive the same two parameter builders
+ * (CLAUDE.md rule 9). An app that already has its own adapter can ignore it and
+ * implement `ScopeClient` directly; nothing else in this package imports it.
+ *
+ * THE FACET READ HAS ITS OWN PARAMETER BUILDER, and that is not tidiness. The
+ * facets action SCREENS its query parameters against a vocabulary before any
+ * handler runs (`_Scoped.initial` -> `_FACET_FILTERS`), so handing it a list
+ * builder's parameters risks 400-ing the whole tree on a filter it does not
+ * know. This sends exactly `type`, `attr`, `under` and the page, which every
+ * deployment that has the route at all understands.
+ *
+ * SERVER-SIDE, ALWAYS (CLAUDE.md rule 8). Both reads are paginated by the server
+ * and neither is filtered in the browser. There is no read of "all scopes" here
+ * to slice up locally, and there must not be.
+ */
+import { facetName } from '../facet-tree/path'
+import type { FacetLevelQuery, Paginated, ScopeClient, ScopeMatch, ScopeNode, ScopeSearchQuery } from './types'
+
+/** The tenant page envelope as the wire spells it, before key normalization. */
+interface WirePage<T> {
+  count?: number
+  next?: string | null
+  previous?: string | null
+  results?: T[]
+}
+
+/**
+ * One `/entities/facets/` row. Spelled BOTH WAYS because the house API clients
+ * camelCase response keys and a raw `fetch` does not, so `has_children` arrives
+ * under either name depending on which client the app injected.
+ */
+interface WireFacetRow {
+  value?: string
+  count?: number
+  has_children?: boolean
+  hasChildren?: boolean
+}
+
+/** One `/entities/` row, of which the switcher needs only the name and the path. */
+interface WireEntity {
+  name?: string
+  data?: Record<string, unknown> | null
+}
+
+export interface ScopeHttp {
+  get<T>(path: string, config?: { params?: Record<string, unknown> }): Promise<T>
+}
+
+export interface CreateScopeClientOptions {
+  http: ScopeHttp
+  /** The declared entity type key. */
+  type?: string
+  /** The attribute carrying the materialized path. */
+  attr?: string
+  /** Collection path, for a deployment that mounts the API somewhere else. */
+  entitiesPath?: string
+}
+
+/** The tenant caps `page_size`; asking for more is silently overruled. */
+const MAX_PAGE_SIZE = 200
+
+/** `?search=` is a text filter and the server bounds text filters. */
+const TEXT_FILTER_MAX = 500
+
+function pageParams(query: { page?: number; pageSize?: number }): Record<string, unknown> {
+  const out: Record<string, unknown> = { page: query.page ?? 1 }
+  if (query.pageSize) out.page_size = Math.min(query.pageSize, MAX_PAGE_SIZE)
+  return out
+}
+
+function envelope<T, U>(response: WirePage<T>, map: (row: T) => U | null): Paginated<U> {
+  const rows = response?.results ?? []
+  const mapped = rows.map(map).filter((row): row is U => row !== null)
+  return {
+    // The server's own total, NOT the mapped length: a row dropped below is
+    // still a row the server counted, and reporting the shorter number would
+    // make "Show N more" stop early.
+    count: response?.count ?? rows.length,
+    next: response?.next ?? null,
+    previous: response?.previous ?? null,
+    results: mapped,
+  }
+}
+
+export function createScopeClient({
+  http,
+  type = 'scope',
+  attr = 'path',
+  entitiesPath = 'api/v1/entities',
+}: CreateScopeClientOptions): ScopeClient {
+  function toNode(row: WireFacetRow): ScopeNode | null {
+    const path = typeof row?.value === 'string' ? row.value : ''
+    if (!path) return null
+    return {
+      path,
+      name: facetName(path),
+      count: row?.count ?? 0,
+      hasChildren: Boolean(row?.has_children ?? row?.hasChildren),
+    }
+  }
+
+  function toMatch(row: WireEntity): ScopeMatch | null {
+    const raw = row?.data ? (row.data as Record<string, unknown>)[attr] : undefined
+    const path = typeof raw === 'string' ? raw : ''
+    // A scope record with no path is not addressable — a selection carries the
+    // path and nothing else — so it is dropped rather than shown as a row that
+    // does nothing when clicked.
+    if (!path) return null
+    return { path, name: row?.name || facetName(path) }
+  }
+
+  return {
+    listScopeChildren(query: FacetLevelQuery): Promise<Paginated<ScopeNode>> {
+      return http
+        .get<WirePage<WireFacetRow>>(`${entitiesPath}/facets`, {
+          params: {
+            type,
+            attr,
+            // The FULL path the server handed back, verbatim. `/` is the root
+            // and means EVERY scope — `subtree_bound()` makes the root's
+            // descendant prefix `/`, which every stored path begins with.
+            under: query.under || '/',
+            ...pageParams(query),
+          },
+        })
+        .then((response) => envelope(response, toNode))
+    },
+
+    searchScopes(query: ScopeSearchQuery): Promise<Paginated<ScopeMatch>> {
+      return http
+        .get<WirePage<WireEntity>>(entitiesPath, {
+          params: {
+            type,
+            search: query.search.slice(0, TEXT_FILTER_MAX),
+            ...pageParams(query),
+          },
+        })
+        .then((response) => envelope(response, toMatch))
+    },
+  }
+}

package/src/components/scope/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @startsimpli/ui/scope — the scope switcher and its URL binding
+ * (bd startsim-6fceh, epic startsim-ux39t).
+ *
+ * A scope is one self-nesting type: a root scope is a client, a child scope is a
+ * project, and depth is not capped. Selection lives in the query string, so a
+ * scoped view is a link somebody can send and a reload lands where it left off.
+ */
+export {
+  ScopeSwitcher,
+  ScopeSwitcherControlled,
+  type ScopeSwitcherProps,
+  type ScopeSwitcherControlledProps,
+  type ScopeSwitcherBaseProps,
+  type ScopeSwitcherLabels,
+} from './ScopeSwitcher'
+export {
+  useScopeParam,
+  SCOPE_PARAM,
+  SCOPE_ALL,
+  type ScopeParam,
+  type UseScopeParamOptions,
+} from './useScopeParam'
+export {
+  createScopeClient,
+  type ScopeHttp,
+  type CreateScopeClientOptions,
+} from './client'
+export type {
+  ScopeClient,
+  ScopeNode,
+  ScopeMatch,
+  ScopeSearchQuery,
+} from './types'

package/src/components/scope/types.ts

@@ -0,0 +1,90 @@
+/**
+ * @startsimpli/ui/scope — the contract the `<ScopeSwitcher/>` is handed
+ * (bd startsim-6fceh, epic startsim-ux39t).
+ *
+ * A SCOPE IS ONE SELF-NESTING TYPE, not client-and-project as two. A root scope
+ * is what a person calls a client, a child scope is what they call a project,
+ * and depth is not capped by the model — the UI may print "Client" and "Project"
+ * but that is a label on a `kind` attribute, not a second table. Nesting is a
+ * MATERIALIZED PATH (epic startsim-ux39t), which is why this file describes a
+ * tree of paths rather than a graph of edges.
+ *
+ * CLIENT-INJECTED, the same way `CollectionClient` and `CorpusApi` are: the app
+ * passes an object implementing this shape over its own authed HTTP client, and
+ * nothing in this package constructs a request or knows an origin.
+ * `createScopeClient` in `./client` is a ready adapter over the tenant's generic
+ * `/api/v1/entities/*` endpoints for apps that want one.
+ *
+ * WHAT THE SERVER GUARANTEES AND THIS PACKAGE MUST NOT ASSUME AWAY: both reads
+ * are gated out of `EntityViewSet.get_queryset()` itself — type gate, row gate,
+ * field gate — so a viewer is shown the scopes their own readable rows are in.
+ * The component therefore renders only what came back for the exact request it
+ * made, and never composes a scope out of two responses.
+ */
+import type { FacetLevelQuery, FacetNode, Paginated } from '../facet-tree/types'
+
+export type { FacetLevelQuery, Paginated }
+
+/**
+ * A scope as the tree read describes it: full path, display name, descendant
+ * record count, and whether anything nests below it.
+ *
+ * It is exactly a `FacetNode` — a scope is one value of the `path` attribute,
+ * derived at read time. There is no scope row minted here and no scope id, so a
+ * rename orphans nothing.
+ */
+export type ScopeNode = FacetNode
+
+/**
+ * A scope as the SEARCH read describes it, and it is deliberately thinner.
+ *
+ * Search is a row read (`GET /entities/?type=scope&search=…`), not a facet read,
+ * so it returns the scope RECORDS that matched rather than grouped path values.
+ * That read knows the scope's own `name` — which is the label a person gave it,
+ * better than the last path segment — but it has no descendant count to offer,
+ * so `count` is optional and a row simply shows none. Inventing one would mean a
+ * second round trip per result, or a number that is not the one the tree shows.
+ */
+export interface ScopeMatch {
+  /** The FULL path, verbatim from the server. The value a selection carries. */
+  path: string
+  /** What to call it. The record's own name where there is one, else the last segment. */
+  name: string
+  /** Descendant records, when the read happened to know. Usually absent. */
+  count?: number
+}
+
+export interface ScopeSearchQuery {
+  search: string
+  page?: number
+  pageSize?: number
+}
+
+/**
+ * THE TWO READS A SCOPE SWITCHER NEEDS.
+ *
+ * They are different endpoints on purpose. Browsing is a FACET read — the child
+ * scopes of one node, with counts and disclosure, one level per request. Searching
+ * is a ROW read — "the scopes whose record matches this term", anywhere in the
+ * tree, flat, each carrying its own full path. Neither is expressible as the
+ * other, and doing search by filtering already-loaded levels would answer
+ * confidently about a subtree the reader has never expanded.
+ */
+export interface ScopeClient {
+  /**
+   * One level of the tree. `under` is a path the server previously returned, or
+   * `/` for the top — which means EVERY scope, not just the roots.
+   *
+   * MUST BE REFERENTIALLY STABLE (memoize the client object). Its identity is
+   * the switcher's reset key: a new client means a new principal, and everything
+   * already fetched was gated for the old one.
+   */
+  listScopeChildren(query: FacetLevelQuery): Promise<Paginated<ScopeNode>>
+  /**
+   * OPTIONAL, because a deployment can legitimately not offer it. Where it is
+   * absent — or answers 404/400 — the switcher filters the levels it has already
+   * loaded and SAYS SO on screen, rather than rendering a partial answer under a
+   * control that implies it searched everything.
+   */
+  searchScopes?(query: ScopeSearchQuery): Promise<Paginated<ScopeMatch>>
+}

package/src/components/scope/useScopeParam.ts

@@ -0,0 +1,200 @@
+'use client'
+
+/**
+ * THE SCOPE LIVES IN THE URL. This hook is the only thing that reads or writes
+ * it, and the switcher is built on it rather than on state of its own.
+ *
+ * WHY THE URL AND NOT A CONTEXT (bd startsim-6fceh). A scoped view has to be a
+ * link somebody can send, and it has to survive a reload. A provider gives you
+ * neither, and a provider mounted in a Next layout gives you something worse —
+ * see below.
+ *
+ * WHY THIS IS `'use client'` AND READS `useSearchParams()` ON EVERY RENDER.
+ * Next.js does not re-render a shared LAYOUT on client-side navigation: layouts
+ * are cached per segment path, ignoring the query string, so state a SERVER
+ * layout derived from the query (or from a middleware header carrying it)
+ * survives a soft nav to a differently-scoped URL and renders stale — that is
+ * `feedback_no_searchparam_state_in_layouts`, hit for real on auth-web tenant
+ * branding, where a hard nav passed and a soft nav kept the wrong tenant. A
+ * CLIENT component is not subject to it: `useSearchParams()` is backed by the
+ * app router's own context, so a component reading it re-renders on every
+ * navigation no matter which layout it happens to sit in. The consuming app's
+ * sidebar sits in exactly such a layout, which is why the switcher takes no
+ * `value` prop for a server layout to compute and hand it — the only shape that
+ * makes the stale reading unreachable is the component owning the read itself.
+ *
+ * "ALL SCOPES" IS SPELLED `?scope=all`, AND IT HAS TO BE SPELLED SOMEHOW. The
+ * obvious design deletes the parameter for "everything", and it has a hole in
+ * it: a URL with no parameter then says two different things — "I chose
+ * everything" and "nobody has chosen" — and `remember` below cannot tell them
+ * apart, so a colleague's link meaning "look at all of it" would open at
+ * whatever scope the reader's own tab was last on. `all` is a reserved value
+ * that no path can collide with, because every path begins with `/`. Both
+ * spellings read out as `scope: null`; the difference is only whether the URL is
+ * ASSERTING it.
+ *
+ * TWO MECHANISMS KEEP A SCOPE ALIVE ACROSS NAVIGATION, and they are not
+ * redundant:
+ *
+ *  • `withScope` — the RIGHT one. A `<Link href="/drafts">` drops the query
+ *    string, so a sidebar built from bare hrefs loses the scope on every click.
+ *    Wrap the href and the link carries whatever the URL is currently asserting,
+ *    which keeps the URL the whole truth.
+ *  • `remember` — the SAFETY NET, on by default. The last explicit choice is
+ *    kept in `sessionStorage` and written back onto a route reached with NO
+ *    parameter at all. THE READING IT COMMITS TO: a bare URL means "this tab's
+ *    scope", and only a `?scope=` parameter is an assertion about scope. So a
+ *    link that names a scope wins, a link that says `all` wins, and a bare
+ *    `/drafts` picks up where the reader left off. An app that wants the bare
+ *    URL to mean "everything" instead should pass `remember={false}` and rely on
+ *    `withScope` alone.
+ */
+
+import * as React from 'react'
+import { usePathname, useRouter, useSearchParams } from 'next/navigation'
+
+/** The query parameter. Short and legible, because a person reads this URL. */
+export const SCOPE_PARAM = 'scope'
+
+/**
+ * The reserved parameter value that ASSERTS "no bound at all".
+ *
+ * It cannot collide with a scope: a path is a materialized path and always
+ * begins with the separator, so `all` is not a value the server can ever return.
+ */
+export const SCOPE_ALL = 'all'
+
+export interface UseScopeParamOptions {
+  /** Override the parameter name where an app already uses `scope` for something else. */
+  param?: string
+  /**
+   * Keep the last explicit choice for this browser tab and restore it onto a URL
+   * that carries no parameter at all. Set false to make the URL the only
+   * mechanism — see the header for which reading each posture commits to.
+   */
+  remember?: boolean
+  /** Namespace for the remembered value, so two apps on one origin do not collide. */
+  rememberKey?: string
+  /**
+   * `replace` (default) keeps the back button meaning "the page before", which is
+   * what a filter control should do. `push` makes each scope change its own
+   * history entry.
+   */
+  history?: 'replace' | 'push'
+}
+
+export interface ScopeParam {
+  /** The path in scope, or `null` for "no bound at all". */
+  scope: string | null
+  /**
+   * True when the URL is ASSERTING a scope — a path, or `all`. False on a bare
+   * URL, where `scope` is `null` because nobody has said anything yet.
+   */
+  asserted: boolean
+  /** Write a full path the server returned, or `null` to bound nothing. */
+  setScope: (next: string | null) => void
+  /** Carry the URL's current assertion onto an href, so a `<Link>` does not drop it. */
+  withScope: (href: string) => string
+}
+
+/** `sessionStorage` throws outright in some embeddings; never let that break a render. */
+function readRemembered(key: string): string | null {
+  try {
+    const raw = window.sessionStorage.getItem(key)
+    return raw && raw.trim() ? raw : null
+  } catch {
+    return null
+  }
+}
+
+function writeRemembered(key: string, value: string): void {
+  try {
+    window.sessionStorage.setItem(key, value)
+  } catch {
+    /* private mode, blocked storage — the URL still carries the truth */
+  }
+}
+
+export function useScopeParam({
+  param = SCOPE_PARAM,
+  remember = true,
+  rememberKey,
+  history = 'replace',
+}: UseScopeParamOptions = {}): ScopeParam {
+  const searchParams = useSearchParams()
+  const router = useRouter()
+  const pathname = usePathname()
+
+  const storageKey = rememberKey ?? `startsimpli.${param}`
+  // THE STRING, not the object. Everything below depends on the query as a
+  // VALUE, so a host whose `useSearchParams()` happens to hand back a fresh
+  // instance per render cannot turn the restore effect below into a redirect
+  // loop. Next memoizes it today; this does not rely on that.
+  const queryString = searchParams?.toString() ?? ''
+  const raw = searchParams?.get(param) ?? null
+  // A blank parameter asserts nothing. `?scope=` is what a hand-edited URL leaves
+  // behind, and treating it as an assertion would be reading intent into a typo.
+  const asserted = Boolean(raw && raw.trim())
+  const value = asserted ? (raw as string).trim() : null
+  const scope = value === SCOPE_ALL ? null : value
+
+  const navigate = React.useCallback(
+    (next: string) => {
+      const params = new URLSearchParams(queryString)
+      params.set(param, next)
+      const url = `${pathname}?${params.toString()}`
+      const go = history === 'push' ? router.push : router.replace
+      go(url, { scroll: false })
+    },
+    [queryString, pathname, router, param, history],
+  )
+
+  const setScope = React.useCallback(
+    (next: string | null) => {
+      // WRITTEN, never deleted. A choice of "everything" is a choice, and the URL
+      // is where a choice is legible — see the header on `SCOPE_ALL`.
+      const written = next === null ? SCOPE_ALL : next
+      if (remember) writeRemembered(storageKey, written)
+      navigate(written)
+    },
+    [remember, storageKey, navigate],
+  )
+
+  // THE SAFETY NET. A route reached with NO parameter — a `<Link>` that dropped
+  // the query, a bookmark of the bare path — takes the tab's last explicit
+  // choice, whether that was a scope or `all`. It never runs when the URL
+  // asserts anything, so a link somebody sent always wins.
+  //
+  // ONE ATTEMPT PER VISIT, and the ref is what makes that true. Without it, a
+  // `replace` the host declines to honour would leave the effect's inputs
+  // unchanged and the restore would fire again on the next render — a redirect
+  // loop out of a convenience. (It is keyed on the pathname, so leaving a route
+  // and coming back earns a fresh attempt, which is what a return visit wants.)
+  const restoredFor = React.useRef<string | null>(null)
+  React.useEffect(() => {
+    if (!remember || asserted) return
+    if (restoredFor.current === pathname) return
+    const remembered = readRemembered(storageKey)
+    if (!remembered) return
+    restoredFor.current = pathname
+    navigate(remembered)
+  }, [remember, asserted, storageKey, navigate, pathname])
+
+  const withScope = React.useCallback(
+    (href: string) => {
+      // The URL's ASSERTION, not the resolved scope — so `all` propagates through
+      // a link as `all` and keeps meaning "everything" on the next page.
+      if (!value) return href
+      const [base, existing = ''] = String(href).split('#')[0].split('?')
+      const hash = String(href).includes('#') ? `#${String(href).split('#')[1]}` : ''
+      const params = new URLSearchParams(existing)
+      // A link that already names a scope means it, and is left alone.
+      if (!params.get(param)) params.set(param, value)
+      const query = params.toString()
+      return `${base}${query ? `?${query}` : ''}${hash}`
+    },
+    [value, param],
+  )
+
+  return { scope, asserted, setScope, withScope }
+}