@startsimpli/ui 0.4.122 → 0.4.124

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.122",
+  "version": "0.4.124",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -47,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.59",
+    "@startsimpli/i18n": "^0.1.3",
+    "@startsimpli/auth": "^0.4.35"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -123,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/states/ScopeAbsence.tsx

@@ -0,0 +1,61 @@
+import * as React from 'react'
+import { Absence, type AbsenceTier } from './Absence'
+import { scopeAbsence, scopeNotice, type ScopeAbsenceInput, type ScopeAbsenceState } from './scope-access'
+
+export interface ScopeAbsenceProps extends ScopeAbsenceInput {
+  /** How much room to give it. A whole table's worth of nothing is a `page`. */
+  tier?: AbsenceTier
+  className?: string
+  /** Rendered when the view is NOT scope-blocked — the collection's own empty state. */
+  fallback?: React.ReactNode
+}
+
+/**
+ * The Absence a scope-gated reader gets instead of "No results found."
+ *
+ * Decides with {@link scopeAbsence} and renders with {@link Absence}, so the
+ * vocabulary is the one every other missing thing already speaks. When the view
+ * is not scope-blocked it renders `fallback` — usually nothing, which lets the
+ * table draw its ordinary empty row.
+ */
+export function ScopeAbsence({
+  tier = 'page',
+  className,
+  fallback = null,
+  ...input
+}: ScopeAbsenceProps) {
+  const state = scopeAbsence(input)
+  if (!state) return <>{fallback}</>
+  return (
+    <div data-scope-absence={state.reason} className={className}>
+      <Absence
+        tier={tier}
+        title={state.title}
+        description={state.description}
+        why={state.why}
+      />
+    </div>
+  )
+}
+
+/**
+ * The standing one-line "your counts cover one scope" disclosure, on the same
+ * Absence vocabulary at its quietest tier. Renders nothing for an exempt or
+ * ungated reader, so it is safe to leave in a shared header.
+ */
+export function ScopeNotice({
+  access,
+  typeKey,
+  typeLabel,
+  className,
+}: Pick<ScopeAbsenceProps, 'access' | 'typeKey' | 'typeLabel' | 'className'>) {
+  const note = scopeNotice({ access, typeKey, typeLabel })
+  if (!note) return null
+  return (
+    <div data-scope-notice="narrowed" className={className}>
+      <Absence tier="note" title="Scoped view" description={note} />
+    </div>
+  )
+}
+
+export type { ScopeAbsenceState }

package/src/components/states/__tests__/scope-access.test.tsx

@@ -0,0 +1,214 @@
+/**
+ * bd startsim-44bar — a scope-gated reader is told WHY a list is empty.
+ *
+ * The wire fixtures here are the two spellings the same report really arrives
+ * in: snake_case straight off Django (`apps/api/pagination.py`, and every
+ * tenant-starter test), camelCase after the shared @startsimpli/api client has
+ * transformed the response. Both are exercised because a reader that handles
+ * only one is a reader that works in unit tests and not in the browser, or the
+ * reverse. The values are the live marketing-agents report, copied from
+ * `GET /api/v1/entities/?type=draft` on 2026-09-17.
+ */
+import * as React from 'react'
+import { render, screen } from '@testing-library/react'
+import { readScopeAccess, scopeAbsence, scopeNotice } from '../scope-access'
+import { ScopeAbsence, ScopeNotice } from '../ScopeAbsence'
+
+const WIRE_SNAKE = {
+  count: 0,
+  results: [],
+  scope_access: {
+    scoped_types: ['draft', 'scope', 'topic'],
+    exempt: false,
+    granted_paths: ['/ogmc-agent-test'],
+  },
+}
+
+const WIRE_CAMEL = {
+  count: 0,
+  results: [],
+  scopeAccess: {
+    scopedTypes: ['draft', 'scope', 'topic'],
+    exempt: false,
+    grantedPaths: ['/ogmc-agent-test'],
+  },
+}
+
+const NO_GRANT_DETAIL =
+  'records of draft, scope, topic are scoped, and this account holds no scope ' +
+  'grant, so it reads none of them. An admin grants a scope by sharing that ' +
+  'scope’s own record (POST /api/v1/grants/ naming the scope row and this user).'
+
+const WIRE_NO_GRANT = {
+  count: 0,
+  results: [],
+  scope_access: {
+    scoped_types: ['draft', 'scope', 'topic'],
+    exempt: false,
+    granted_paths: [],
+    detail: NO_GRANT_DETAIL,
+  },
+}
+
+describe('readScopeAccess', () => {
+  it('reads the report off a list envelope in EITHER spelling', () => {
+    for (const wire of [WIRE_SNAKE, WIRE_CAMEL]) {
+      expect(readScopeAccess(wire)).toEqual({
+        scopedTypes: ['draft', 'scope', 'topic'],
+        exempt: false,
+        grantedPaths: ['/ogmc-agent-test'],
+      })
+    }
+  })
+
+  it('reads a bare report, as /whoami/ nests it and as a caller may pass it', () => {
+    expect(readScopeAccess(WIRE_SNAKE.scope_access)?.grantedPaths).toEqual(['/ogmc-agent-test'])
+    expect(
+      readScopeAccess({ sub: 'u1', role: 'admin', scope_access: { scoped_types: ['draft'], exempt: true, granted_paths: [] } }),
+    ).toEqual({ scopedTypes: ['draft'], exempt: true, grantedPaths: [] })
+  })
+
+  it('carries the backend’s own detail sentence through', () => {
+    expect(readScopeAccess(WIRE_NO_GRANT)?.detail).toBe(NO_GRANT_DETAIL)
+  })
+
+  it('is null for an envelope that carries no report — every tenant today', () => {
+    expect(readScopeAccess({ count: 0, next: null, previous: null, results: [] })).toBeNull()
+    expect(readScopeAccess(null)).toBeNull()
+    expect(readScopeAccess(undefined)).toBeNull()
+    expect(readScopeAccess('nope')).toBeNull()
+    // A report with no gated types is not one.
+    expect(readScopeAccess({ scope_access: { scoped_types: [], exempt: false, granted_paths: [] } })).toBeNull()
+  })
+})
+
+describe('scopeAbsence', () => {
+  const held = readScopeAccess(WIRE_SNAKE)
+  const none = readScopeAccess(WIRE_NO_GRANT)
+
+  it('names the missing GRANT when the account holds no scope at all', () => {
+    const state = scopeAbsence({ access: none, typeKey: 'draft', typeLabel: 'Draft', readableCount: 0 })
+    expect(state?.reason).toBe('no-grant')
+    // The remedy is the backend's own sentence, not a second copy of it here.
+    expect(state?.why).toBe(NO_GRANT_DETAIL)
+    expect(state?.description).toContain('missing grant')
+  })
+
+  it('names the scopes held — and never the ones it cannot see — otherwise', () => {
+    const state = scopeAbsence({ access: held, typeKey: 'topic', typeLabel: 'Topic', readableCount: 0 })
+    expect(state?.reason).toBe('other-scope')
+    expect(state?.description).toContain('/ogmc-agent-test')
+    // It must not claim to know where the rows it cannot read actually are.
+    expect(`${state?.title} ${state?.description} ${state?.why}`).not.toContain('/ogmc,')
+  })
+
+  it('says NOTHING about a type the axis does not gate', () => {
+    // The report rides on every list a gated caller makes, news_item included.
+    expect(scopeAbsence({ access: held, typeKey: 'news_item', readableCount: 0 })).toBeNull()
+  })
+
+  it('says nothing when the reader CAN reach rows — a filter emptying the view is not a scope gap', () => {
+    // The live marketing-agents sandbox: four drafts readable, a "last 7 days"
+    // facet matching none of them. That empty table is the filter's doing and
+    // must stay the ordinary empty state.
+    expect(scopeAbsence({ access: held, typeKey: 'draft', readableCount: 4 })).toBeNull()
+    expect(scopeAbsence({ access: held, typeKey: 'draft', readableCount: 0, loading: true })).toBeNull()
+    expect(
+      scopeAbsence({
+        access: readScopeAccess({ scope_access: { scoped_types: ['draft'], exempt: true, granted_paths: [] } }),
+        typeKey: 'draft',
+        readableCount: 0,
+      }),
+    ).toBeNull()
+  })
+
+  it('says nothing at all when no report came back', () => {
+    expect(scopeAbsence({ access: null, typeKey: 'draft', readableCount: 0 })).toBeNull()
+  })
+
+  it('is pending-safe — it never accuses a read that has not answered yet', () => {
+    expect(
+      scopeAbsence({ access: undefined, typeKey: 'draft', readableCount: 0, loading: true }),
+    ).toBeNull()
+  })
+
+  it('A FAILED probe is not a scope gap', () => {
+    // The shape a 500, a 401-refresh race or a network blip leaves behind: the
+    // query has SETTLED (loading false), so there is no pending flag to hide
+    // behind, and `readableCount` has coerced to 0 on the caller's `?? 0`. The
+    // report is what carries the claim, and there is none — so this says
+    // nothing and the collection keeps its ordinary empty state. Asserting a
+    // permissions failure we did not observe would be startsim-4ipm's fallback
+    // bug pointed the other way: a confident verdict from a read that failed.
+    expect(
+      scopeAbsence({ access: undefined, typeKey: 'draft', readableCount: 0, loading: false }),
+    ).toBeNull()
+    expect(scopeNotice({ access: undefined, typeKey: 'draft' })).toBeNull()
+  })
+
+  it('falls back to a remedy of its own when the backend sent no detail', () => {
+    const state = scopeAbsence({
+      access: readScopeAccess({ scope_access: { scoped_types: ['draft'], exempt: false, granted_paths: [] } }),
+      typeKey: 'draft',
+      readableCount: 0,
+    })
+    expect(state?.reason).toBe('no-grant')
+    expect(state?.why).toContain('An admin grants a scope')
+  })
+})
+
+describe('<ScopeAbsence />', () => {
+  it('renders the Absence, not the collection’s empty state', () => {
+    const { container } = render(
+      <ScopeAbsence
+        access={readScopeAccess(WIRE_NO_GRANT)}
+        typeKey="draft"
+        typeLabel="Draft"
+        readableCount={0}
+        fallback={<p>No results found.</p>}
+      />,
+    )
+    expect(container.querySelector('[data-scope-absence="no-grant"]')).toBeTruthy()
+    expect(
+      screen.getByText('This account holds no scope, so it reads no records'),
+    ).toBeInTheDocument()
+    expect(screen.queryByText('No results found.')).not.toBeInTheDocument()
+  })
+
+  it('hands back to the collection’s own empty state when scope is not the reason', () => {
+    render(
+      <ScopeAbsence access={null} typeKey="draft" readableCount={0} fallback={<p>No results found.</p>} />,
+    )
+    expect(screen.getByText('No results found.')).toBeInTheDocument()
+  })
+})
+
+describe('scopeNotice', () => {
+  const held = readScopeAccess(WIRE_SNAKE)
+
+  it('says which scope the counts cover, whether or not the view is empty', () => {
+    const note = scopeNotice({ access: held, typeKey: 'topic', typeLabel: 'Topic' })
+    expect(note).toContain('/ogmc-agent-test')
+    expect(note).toContain('not shown')
+  })
+
+  it('is silent for an ungated type, an exempt caller, and a caller holding nothing', () => {
+    expect(scopeNotice({ access: held, typeKey: 'news_item' })).toBeNull()
+    expect(scopeNotice({ access: null, typeKey: 'draft' })).toBeNull()
+    expect(
+      scopeNotice({
+        access: readScopeAccess({ scope_access: { scoped_types: ['draft'], exempt: true, granted_paths: ['/ogmc'] } }),
+        typeKey: 'draft',
+      }),
+    ).toBeNull()
+    // Holding nothing is the Absence's case; two statements of it is one too many.
+    expect(scopeNotice({ access: readScopeAccess(WIRE_NO_GRANT), typeKey: 'draft' })).toBeNull()
+  })
+
+  it('renders nothing at all when it has nothing to say', () => {
+    const { container } = render(<ScopeNotice access={held} typeKey="news_item" />)
+    expect(container.querySelector('[data-scope-notice]')).toBeNull()
+    const shown = render(<ScopeNotice access={held} typeKey="draft" typeLabel="Draft" />)
+    expect(shown.container.querySelector('[data-scope-notice="narrowed"]')).toBeTruthy()
+  })
+})

package/src/components/states/index.ts

@@ -8,3 +8,12 @@ export { FootnoteScope, Footnote } from './Footnote'
 export type { FootnoteScopeProps, FootnoteProps } from './Footnote'
 export { Absence, ABSENCE_DASH } from './Absence'
 export type { AbsenceProps, AbsenceTier } from './Absence'
+export { ScopeAbsence, ScopeNotice } from './ScopeAbsence'
+export type { ScopeAbsenceProps } from './ScopeAbsence'
+export { readScopeAccess, scopeAbsence, scopeNotice } from './scope-access'
+export type {
+  ScopeAccess,
+  ScopeAbsenceInput,
+  ScopeAbsenceReason,
+  ScopeAbsenceState,
+} from './scope-access'

package/src/components/states/scope-access.ts

@@ -0,0 +1,221 @@
+/**
+ * WHY A LIST IS EMPTY WHEN THE READER IS SCOPE-GATED (bd startsim-44bar).
+ *
+ * A foundry tenant may file rows of a type under a `scope` path and show a
+ * reader only the scopes they hold a grant on. When it does, every list
+ * response for a non-exempt caller carries a `scope_access` report — which
+ * types are gated, whether this caller is exempt, and which paths they hold
+ * (tenant-starter `apps/schema_registry/access.py::scope_access_report`, put on
+ * the envelope by `apps/api/pagination.py`).
+ *
+ * THE REPORT EXISTS BECAUSE `count: 0` IS AMBIGUOUS. "There is nothing here"
+ * and "you were never granted the scope this lives in" are the same bytes on
+ * the wire, and a UI that renders both as a bare empty table turns a
+ * provisioning gap into "the app lost our content" — the 2026-08-20 blackout
+ * shape, and the reason bd startsim-4ipm established that an empty read is an
+ * Absence and not a fallback. The backend already states the cause AND the
+ * remedy; this module is the half that puts it on screen.
+ *
+ * NOT THE SAME AXIS AS `@startsimpli/ui/scope`, and the two are easy to
+ * confuse. That module is the scope SWITCHER — which scope the reader has
+ * chosen to browse, bound to the query string. This one is the read GATE —
+ * which scopes the reader is ENTITLED to, which is the server's answer and not
+ * a choice. A switcher offering one scope and a gate granting one scope look
+ * alike on screen and fail completely differently: the first is a filter the
+ * reader can clear, the second is a permission they cannot.
+ *
+ * READ CAMEL-TOLERANTLY. The shared @startsimpli/api client camelCases response
+ * keys, so a browser fetch spells the report `scopeAccess.grantedPaths` while
+ * Django's own JSON, a server-side fetch and every backend test spell it
+ * `scope_access.granted_paths`. Both are the same report under two names — the
+ * same asymmetry `marketing-agents-web/src/lib/scope.ts` documents for
+ * `scope_path`. Values inside (`draft`, `/ogmc-agent-test`) are untransformed.
+ */
+
+/** The `scope_access` report, normalised to one spelling. */
+export interface ScopeAccess {
+  /** Type keys the `scope` axis gates for this caller, e.g. `['draft','scope','topic']`. */
+  scopedTypes: string[]
+  /**
+   * True only when the caller reads EVERY gated type regardless of grant.
+   *
+   * Note this is all but decorative on a LIST envelope: the tenant sets the key
+   * there only for a non-exempt caller, so it arrives `false` or not at all. It
+   * carries a real `true` on `/api/v1/whoami/`, where the report is unconditional.
+   */
+  exempt: boolean
+  /** The scope paths this caller holds a grant on. Empty is the blackout shape. */
+  grantedPaths: string[]
+  /** The backend's own sentence naming the cause and the remedy, when it sent one. */
+  detail?: string
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : []
+}
+
+function pick(source: Record<string, unknown>, ...names: string[]): unknown {
+  for (const name of names) {
+    if (source[name] !== undefined) return source[name]
+  }
+  return undefined
+}
+
+/**
+ * The `scope_access` report carried by a list envelope, a `/whoami/` body, or
+ * the bare report itself — or `null` when there is none.
+ *
+ * `null` is the answer for every tenant that has not declared the axis and for
+ * every exempt caller, and it means "say nothing new": the ordinary empty state
+ * is the honest one there.
+ */
+export function readScopeAccess(source: unknown): ScopeAccess | null {
+  if (!source || typeof source !== 'object') return null
+  const body = source as Record<string, unknown>
+  const raw = pick(body, 'scopeAccess', 'scope_access') ?? body
+  if (!raw || typeof raw !== 'object') return null
+  const report = raw as Record<string, unknown>
+  const scopedTypes = stringList(pick(report, 'scopedTypes', 'scoped_types'))
+  // A report with no gated types is not a report — this is what tells the bare
+  // report apart from an envelope that never carried one.
+  if (scopedTypes.length === 0) return null
+  const detail = pick(report, 'detail')
+  return {
+    scopedTypes,
+    exempt: pick(report, 'exempt') === true,
+    grantedPaths: stringList(pick(report, 'grantedPaths', 'granted_paths')),
+    ...(typeof detail === 'string' && detail.trim() ? { detail: detail.trim() } : {}),
+  }
+}
+
+/** Which of the two scope absences a reader is looking at. */
+export type ScopeAbsenceReason =
+  /** Gated, and this account holds NO scope at all: a provisioning gap. */
+  | 'no-grant'
+  /** Gated, holds scopes, and nothing in them answers this view. */
+  | 'other-scope'
+
+export interface ScopeAbsenceState {
+  reason: ScopeAbsenceReason
+  title: string
+  description: string
+  why: string
+  /** The gated type keys, for a caller that wants to say more. */
+  scopedTypes: string[]
+  /** The paths this account holds — empty on `no-grant`. */
+  grantedPaths: string[]
+}
+
+export interface ScopeAbsenceInput {
+  /** The report, as {@link readScopeAccess} returned it. */
+  access: ScopeAccess | null | undefined
+  /** The type this view lists, e.g. `draft`. */
+  typeKey: string
+  /** Its human label, e.g. `Draft`. Falls back to the key. */
+  typeLabel?: string
+  /**
+   * How many records of this type the reader can reach AT ALL — the server's
+   * own unfiltered count, NOT the length of the filtered view.
+   *
+   * The distinction is the whole difference between a disclosure and a nag. A
+   * reader holding a scope with four drafts in it, who then narrows to "last 7
+   * days" and matches none, has an empty view for a reason they chose and can
+   * see; blaming the scope gate there would put a permissions banner over an
+   * ordinary filter, teach the reader to ignore it, and retire the warning
+   * exactly where it matters. Only a reader who can reach NOTHING of the type
+   * is looking at the blackout shape. The standing narrowing — "your counts
+   * cover one scope" — is {@link scopeNotice}, which is always true and says so
+   * quietly instead.
+   */
+  readableCount: number
+  /** True while the read is still in flight. A pending read is never an absence. */
+  loading?: boolean
+}
+
+/**
+ * The absence a scope-gated reader is owed in place of an empty table, or
+ * `null` when the ordinary empty state is the truthful one.
+ *
+ * IT NEVER NAMES THE ROWS IT CANNOT SEE. The client is on the far side of the
+ * gate: it knows which scopes the reader holds and nothing whatever about what
+ * is filed elsewhere, so it says "only the scopes you hold are counted here"
+ * and never "these rows are in /ogmc". Inventing the other side would be a new
+ * bug wearing this one's fix.
+ *
+ * `null` for: a pending read, a reader who can reach any row of the type, no
+ * report, an exempt caller, and a type the axis does not gate — that last one
+ * matters, because the report rides on EVERY list a gated caller makes,
+ * including the ungated types, and a news feed of 6,456 rows must not grow a
+ * scope disclaimer when a filter empties it.
+ */
+export function scopeAbsence({
+  access,
+  typeKey,
+  typeLabel,
+  readableCount,
+  loading,
+}: ScopeAbsenceInput): ScopeAbsenceState | null {
+  if (loading) return null
+  if (readableCount > 0) return null
+  if (!access || access.exempt) return null
+  if (!access.scopedTypes.includes(typeKey)) return null
+
+  const label = (typeLabel || typeKey).toLowerCase()
+  const shared = { scopedTypes: access.scopedTypes, grantedPaths: access.grantedPaths }
+
+  if (access.grantedPaths.length === 0) {
+    return {
+      reason: 'no-grant',
+      title: 'This account holds no scope, so it reads no records',
+      description:
+        `${label} records in this workspace are filed by scope, and a reader sees only ` +
+        'the scopes they were granted. This account was granted none — so the list ' +
+        'is empty because of a missing grant, not because the workspace is empty.',
+      why:
+        access.detail ??
+        'An admin grants a scope by sharing that scope’s own record with this account.',
+      ...shared,
+    }
+  }
+
+  const held = access.grantedPaths.join(', ')
+  return {
+    reason: 'other-scope',
+    title: 'Nothing here in the scopes this account holds',
+    description:
+      `${label} records in this workspace are filed by scope. This account reads ` +
+      `${held} and nothing else, so anything filed under another scope is neither ` +
+      'shown nor counted here.',
+    why:
+      `Scopes held: ${held}. An admin widens this by sharing another scope’s own ` +
+      'record with this account.',
+    ...shared,
+  }
+}
+
+/**
+ * THE STANDING DISCLOSURE: one line saying a reader's counts cover only the
+ * scopes they hold — rendered whether or not the view is empty.
+ *
+ * The Absence above fires only in the blackout shape, and that leaves the
+ * commonest scoped reading unsaid: a member holding one scope of several sees
+ * "1 total" over a type of ninety and has no way to tell that from a workspace
+ * with one record in it. Nothing is WRONG on that screen, which is precisely
+ * why it needs a line rather than a banner — the number is true of what the
+ * reader may read, and the sentence says what that is.
+ *
+ * `null` when there is no report, when the caller is exempt, when the type is
+ * not gated, or when the caller holds no scope at all — that last one is the
+ * Absence's case, and saying both would say it twice.
+ */
+export function scopeNotice({
+  access,
+  typeKey,
+  typeLabel,
+}: Pick<ScopeAbsenceInput, 'access' | 'typeKey' | 'typeLabel'>): string | null {
+  if (!access || access.exempt) return null
+  if (!access.scopedTypes.includes(typeKey)) return null
+  if (access.grantedPaths.length === 0) return null
+  const label = (typeLabel || typeKey).toLowerCase()
+  return `Counts and rows here cover ${access.grantedPaths.join(', ')} only \u2014 ${label} records filed under any other scope are not shown.`
+}