@startsimpli/ui 0.4.111 → 0.4.113

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/index.ts

@@ -199,6 +199,7 @@ export {
   ScopeSwitcher,
   ScopeSwitcherControlled,
   useScopeParam,
+  useScopedCollectionClient,
   createScopeClient,
   SCOPE_PARAM,
   SCOPE_ALL,

package/src/components/scope/__tests__/use-scoped-client.test.tsx

@@ -0,0 +1,80 @@
+/**
+ * `useScopedCollectionClient` (bd startsim-nq39j) — the URL's scope bound onto
+ * the app's injected tenant client, which is the whole of a fork's adoption.
+ *
+ * Two properties, and the second is the one that would otherwise be discovered
+ * in production: the hook reads the SAME `?scope=` the switcher writes (so a
+ * shared link scopes the data, not just the picker's label), and the client it
+ * returns is REFERENTIALLY STABLE — it is a react-query input, and a fresh
+ * object per render refetches every list on every keystroke elsewhere on the
+ * page.
+ */
+import * as React from 'react'
+import { render, screen } from '@testing-library/react'
+import { useSearchParams } from 'next/navigation'
+
+import { useScopedCollectionClient } from '../useScopedClient'
+import type { CollectionClient, EntityRecord, EntityTypeDef, Paginated } from '../../collection/types'
+
+const mockedSearchParams = useSearchParams as unknown as jest.Mock
+
+function page<T>(results: T[]): Paginated<T> {
+  return { count: results.length, next: null, previous: null, results }
+}
+
+const client: CollectionClient = {
+  listTypes: async () => page<EntityTypeDef>([]),
+  listAllEntities: async () => [] as EntityRecord[],
+  updateEntity: async () => ({}) as EntityRecord,
+}
+
+/** Renders the bound scope and hands every client instance it saw to the test. */
+function Probe({ seen }: { seen: unknown[] }) {
+  const scoped = useScopedCollectionClient(client, { remember: false })
+  seen.push(scoped)
+  return <span data-testid="scope">{String(scoped.scope)}</span>
+}
+
+beforeEach(() => {
+  mockedSearchParams.mockReturnValue(new URLSearchParams(''))
+})
+
+describe('useScopedCollectionClient', () => {
+  it('binds the client to the scope the URL is asserting', () => {
+    mockedSearchParams.mockReturnValue(new URLSearchParams('scope=/clients/acme'))
+    render(<Probe seen={[]} />)
+    expect(screen.getByTestId('scope').textContent).toBe('/clients/acme')
+  })
+
+  it('reads the URL’s reserved "all" as no bound', () => {
+    // `?scope=all` is the browser spelling of "everything"; on the wire that is
+    // the ABSENCE of the parameter, which is what `scope: null` produces.
+    mockedSearchParams.mockReturnValue(new URLSearchParams('scope=all'))
+    render(<Probe seen={[]} />)
+    expect(screen.getByTestId('scope').textContent).toBe('null')
+  })
+
+  it('is unbounded on a bare URL', () => {
+    render(<Probe seen={[]} />)
+    expect(screen.getByTestId('scope').textContent).toBe('null')
+  })
+
+  it('returns the SAME client across re-renders, so react-query does not thrash', () => {
+    mockedSearchParams.mockReturnValue(new URLSearchParams('scope=/clients/acme'))
+    const seen: unknown[] = []
+    const { rerender } = render(<Probe seen={seen} />)
+    rerender(<Probe seen={seen} />)
+    expect(seen.length).toBeGreaterThan(1)
+    expect(new Set(seen).size).toBe(1)
+  })
+
+  it('returns a NEW client when the scope changes, so the cache key moves with it', () => {
+    mockedSearchParams.mockReturnValue(new URLSearchParams('scope=/clients/acme'))
+    const seen: unknown[] = []
+    const { rerender } = render(<Probe seen={seen} />)
+    mockedSearchParams.mockReturnValue(new URLSearchParams('scope=/clients/globex'))
+    rerender(<Probe seen={seen} />)
+    expect(screen.getByTestId('scope').textContent).toBe('/clients/globex')
+    expect(new Set(seen).size).toBe(2)
+  })
+})

package/src/components/scope/index.ts

@@ -26,6 +26,12 @@ export {
   type ScopeHttp,
   type CreateScopeClientOptions,
 } from './client'
+/**
+ * The URL's scope bound onto the app's `CollectionClient` (bd startsim-nq39j) —
+ * the whole of a fork's adoption, because every review surface in
+ * '@startsimpli/ui/collection' is client-injected.
+ */
+export { useScopedCollectionClient } from './useScopedClient'
 export type {
   ScopeClient,
   ScopeNode,

package/src/components/scope/useScopedClient.ts

@@ -0,0 +1,44 @@
+'use client'
+
+/**
+ * The URL's scope, bound onto the app's injected tenant client — the two halves
+ * of bd startsim-nq39j joined in the one place an app has to touch.
+ *
+ * A fork wrapper is then the whole adoption:
+ *
+ *   const client = useScopedCollectionClient(collectionClient)
+ *   return <TopicReviewWorkspace client={client} />
+ *
+ * WHY THIS AND NOT `withScope(collectionClient, useScopeParam().scope)` INLINE.
+ * The returned client is a react-query input: it is the query function's closure
+ * and, through `scopeKey`, part of the query key. Built fresh on every render it
+ * is a new object every render, which is the same defect `ScopeClient` documents
+ * for the switcher's own reset key. The memo here is the point of the hook.
+ *
+ * THE HOOK LIVES IN `scope/`, NOT IN `collection/`, ON PURPOSE. Reading the URL
+ * means `next/navigation`; keeping that import out of `collection/` leaves the
+ * review workspaces and `withScope` framework-agnostic, so a host that keeps its
+ * scope somewhere else (a native shell, a test, a server component passing a
+ * value down) calls `withScope` directly and loses nothing.
+ */
+import * as React from 'react'
+
+import { withScope, type ScopedCollectionClient } from '../collection/scoped-client'
+import type { CollectionClient } from '../collection/types'
+import { useScopeParam, type UseScopeParamOptions } from './useScopeParam'
+
+/**
+ * Bind the URL's active scope onto a `CollectionClient`.
+ *
+ * The result is stable while the scope and the underlying client are — so pass a
+ * module-level or memoized `client`, exactly as an unwrapped one would need to
+ * be. Options are forwarded to {@link useScopeParam} verbatim.
+ */
+export function useScopedCollectionClient(
+  client: CollectionClient,
+  options: UseScopeParamOptions = {},
+): ScopedCollectionClient {
+  const { param, remember, rememberKey, history } = options
+  const { scope } = useScopeParam({ param, remember, rememberKey, history })
+  return React.useMemo(() => withScope(client, scope), [client, scope])
+}