@startsimpli/integrations 0.2.34 → 0.2.35

package/src/__tests__/corpus-pages.test.tsx

@@ -161,11 +161,11 @@ describe('LibraryPage — filtering and paging are SERVER round trips', () => {
     });
     render(<LibraryPage api={api} scope={SCOPE} pageSize={2} />);
 
-    await screen.findByText(/page 1 of 3/);
+    await screen.findByText(/page 1 of \d+/);
     await user.click(screen.getByRole('button', { name: 'Next' }));
 
     await waitFor(() => expect(queries.some((query) => query.page === 2)).toBe(true));
-    expect(await screen.findByText(/page 2 of 3/)).toBeInTheDocument();
+    expect(await screen.findByText(/page 2 of \d+/)).toBeInTheDocument();
   });
 
   it('returns to page 1 when a filter changes', async () => {
@@ -178,9 +178,9 @@ describe('LibraryPage — filtering and paging are SERVER round trips', () => {
     });
     render(<LibraryPage api={api} scope={SCOPE} pageSize={2} />);
 
-    await screen.findByText(/page 1 of 3/);
+    await screen.findByText(/page 1 of \d+/);
     await user.click(screen.getByRole('button', { name: 'Next' }));
-    await screen.findByText(/page 2 of 3/);
+    await screen.findByText(/page 2 of \d+/);
 
     await user.selectOptions(screen.getByLabelText('Source'), 'dropbox');
 

package/src/components/FolderTree.tsx

@@ -0,0 +1,425 @@
+/**
+ * THE FOLDER TREE — a navigable directory over the corpus (bd startsim-ei8gm.5,
+ * decided on bd startsim-maios: "a navigable tree/directory system is 100%
+ * necessary").
+ *
+ * IT IS A FILE BROWSER AND THAT IS THE WHOLE DESIGN. bd startsim-nbhno settled
+ * that the corpus is ONE list categorised by folder structure — "everyone knows
+ * how folders work cause they use a computer. we don't need to create a new
+ * system here that will confuse people." So there is no second surface, no
+ * ranking and no invented taxonomy here: a triangle, a folder, a count, and
+ * clicking one shows what is inside it.
+ *
+ * ONE LEVEL PER REQUEST, PAGED (CLAUDE.md rule 8). Expanding a node asks the
+ * server for that node's children and nothing else:
+ *
+ *   GET /api/v1/entities/facets/?type=source_document&attr=path&under=/Contracts
+ *       -> {value, count, has_children}, paginated
+ *
+ * The alternative — read every document's path and assemble the tree in the
+ * browser — is what this exists to remove. It works on today's 247 records and
+ * expires in the low thousands, and it is the rule-8 failure the tenant shipped
+ * `/entities/facets/` (start-simpli-api#391) specifically to end.
+ *
+ * `has_children` IS WHY EXPANDING COSTS NOTHING TO OFFER. The row that names a
+ * folder also says whether anything is below it, so the disclosure triangle is
+ * drawn from data already in hand rather than from a probe request per node.
+ *
+ * NOTHING HERE MINTS A FOLDER (bd startsim-maios). A node is a value of the
+ * `path` attribute, derived at read time; there is no folder row and no folder
+ * id, so a rename re-mints nothing and orphans nothing. That is the correct
+ * shape rather than a shortcut — it is how a file browser has always worked.
+ *
+ * THE SECURITY PROPERTY, AND IT IS THE REASON FOR THE SHAPE OF THE STATE BELOW.
+ * The facet read is gated server-side out of `EntityViewSet.get_queryset()`
+ * itself, so a member is shown the folders their own documents are in. On a
+ * tenant whose `source_document` is `row_scope: personal` that is the entire
+ * protection, and a folder name leaks plenty on its own — `/Legal/Terminations`,
+ * `/Acquisition-TargetCo`. So every container's children are stored under that
+ * container's OWN `under=` key and rendered from that key alone. Nothing here
+ * merges two responses, fills one level from another level's answer, or keeps a
+ * flat set of every folder ever seen: 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.
+ *
+ * PATHS GO BACK OUT VERBATIM. The next `under=` and the file list's
+ * `attr.path=` are the exact string the server returned; a client that re-joins
+ * segments has a small escaping bug in it, and the server returns whole paths
+ * precisely so no client has to. `folderName()` takes one apart for DISPLAY, and
+ * `folderTrail()` does for a breadcrumb — see its own note for why that one is
+ * not the same act.
+ */
+import * as React from 'react';
+
+import { FOLDER_ROOT, folderName } from '../corpus/entities';
+import type { CorpusFolder, CorpusPage, FolderQuery } from '../corpus/types';
+
+
+export type FolderTreeSlot = 'root' | 'node' | 'nodeSelected' | 'count' | 'muted' | 'error' | 'more';
+
+const DEFAULTS: Record<FolderTreeSlot, 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 text-gray-700 hover:bg-gray-100',
+  nodeSelected: 'bg-gray-100 font-medium text-gray-900',
+  count: 'ml-auto shrink-0 text-xs tabular-nums text-gray-400',
+  muted: 'px-2 py-1 text-xs text-gray-500',
+  error: 'px-2 py-1 text-xs text-red-600',
+  more: 'px-2 py-1 text-xs font-medium text-gray-600 underline underline-offset-2 hover:text-gray-900 disabled:no-underline disabled:opacity-50',
+};
+
+/** Just the read the tree needs, so a caller can hand it a whole `CorpusApi`. */
+export interface FolderSource {
+  listFolders?(query: FolderQuery): Promise<CorpusPage<CorpusFolder>>;
+}
+
+export interface FolderTreeProps {
+  api: FolderSource;
+  /** The folder whose contents are on screen, or `null` for the whole corpus. */
+  selected: string | null;
+  /** A full path the server returned, or `null` for "everything". */
+  onSelect: (folder: string | null) => void;
+  /**
+   * The label on the root row. It is not a folder — selecting it clears the
+   * path filter entirely, which is the only thing that keeps records with NO
+   * path (a meeting note, an email) reachable. The facet read skips them by
+   * construction (`Q(_v__isnull=False)`), so if the root row narrowed anything
+   * the majority of today's corpus would be unreachable from this screen.
+   */
+  rootLabel?: string;
+  /** Folders per request. The server pages; this is the page size it is asked for. */
+  pageSize?: number;
+  /**
+   * Told once when the corpus cannot enumerate folders at all — a fork that
+   * predates the facet route 404s, an older one 400s. The Library uses it to
+   * stop reserving space for a tree that will never draw, and falls back to the
+   * flat list it rendered before. Never a half-drawn tree.
+   */
+  onUnavailable?: () => void;
+  classNames?: Partial<Record<FolderTreeSlot, string>>;
+}
+
+/** What is known about ONE container's children. Keyed by that container's path. */
+interface LevelState {
+  rows: CorpusFolder[];
+  /** The server's 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;
+}
+
+const EMPTY: LevelState = { rows: [], total: 0, page: 0, loading: false, error: '' };
+
+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 folders.';
+  return (err as { message?: string })?.message || 'Could not load folders.';
+}
+
+/**
+ * A 404/400 means "this corpus has no folder enumeration", not "no folders".
+ *
+ * BOTH CODES, because both are real deployments. A fork built before
+ * start-simpli-api#391 has no `/entities/facets/` route at all 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, and the
+ * honest response to both is the list that was there before the tree existed.
+ */
+function isUnsupported(err: unknown): boolean {
+  const status = (err as { status?: number })?.status;
+  return status === 404 || status === 400 || status === 501;
+}
+
+export function FolderTree({
+  api,
+  selected,
+  onSelect,
+  rootLabel = 'All documents',
+  pageSize = 100,
+  onUnavailable,
+  classNames = {},
+}: FolderTreeProps) {
+  const cn = { ...DEFAULTS, ...classNames };
+
+  /**
+   * container path -> its children. A map keyed by the request that produced
+   * the rows, never a flattened list of every folder seen: keeping them under
+   * their own key is what makes it structurally impossible to draw a node out
+   * of a response that was not about it.
+   */
+  const [levels, setLevels] = React.useState<Record<string, LevelState>>({});
+  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 api object 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 folder list is exactly the leak this file is careful about.
+  React.useEffect(() => {
+    requested.current = new Set();
+    told.current = false;
+    setLevels({});
+    setExpanded({});
+    setUnavailable(false);
+  }, [api]);
+
+  const load = React.useCallback(async (under: string, page: number) => {
+    if (!api.listFolders) {
+      setUnavailable(true);
+      return;
+    }
+    setLevels((prev) => ({
+      ...prev,
+      [under]: { ...(prev[under] ?? EMPTY), loading: true, error: '' },
+    }));
+    try {
+      const result = await api.listFolders({ under, page, pageSize });
+      setLevels((prev) => {
+        const before = prev[under] ?? EMPTY;
+        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 (isUnsupported(err)) {
+        setUnavailable(true);
+        return;
+      }
+      setLevels((prev) => ({
+        ...prev,
+        [under]: { ...(prev[under] ?? EMPTY), loading: false, error: failure(err) },
+      }));
+    }
+  }, [api, pageSize]);
+
+  /**
+   * Fetch a container's first page, once. 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 load(under, 1);
+  }, [load]);
+
+  React.useEffect(() => {
+    if (!unavailable) ensure(FOLDER_ROOT);
+  }, [ensure, unavailable]);
+
+  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]);
+
+  if (unavailable) return null;
+
+  const root = levels[FOLDER_ROOT] ?? EMPTY;
+
+  return (
+    <nav className={cn.root} aria-label="Folders">
+      <div className="flex items-center">
+        <span aria-hidden="true" className="w-4 shrink-0" />
+        <button
+          type="button"
+          className={`${cn.node} ${selected === null ? cn.nodeSelected : ''}`}
+          aria-current={selected === null ? 'true' : undefined}
+          onClick={() => onSelect(null)}
+        >
+          <span className="truncate">{rootLabel}</span>
+        </button>
+      </div>
+
+      {root.loading && root.rows.length === 0 ? (
+        <p className={cn.muted}>Loading folders…</p>
+      ) : null}
+      {root.error ? <p className={cn.error} role="alert">{root.error}</p> : null}
+
+      <FolderLevel
+        under={FOLDER_ROOT}
+        depth={0}
+        levels={levels}
+        expanded={expanded}
+        selected={selected}
+        onSelect={onSelect}
+        onToggle={toggle}
+        onMore={load}
+        classNames={cn}
+      />
+    </nav>
+  );
+}
+
+// ---------------------------------------------------------------------------
+
+/**
+ * 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
+ * recursion needs no context, and each frame touches exactly its own key. There
+ * is no path arithmetic here at all: `folder.path` is what the server said, and
+ * it is what goes to the next frame.
+ */
+function FolderLevel({
+  under, depth, levels, expanded, selected, onSelect, onToggle, onMore, classNames: cn,
+}: {
+  under: string;
+  depth: number;
+  levels: Record<string, LevelState>;
+  expanded: Record<string, boolean>;
+  selected: string | null;
+  onSelect: (folder: string) => void;
+  onToggle: (path: string) => void;
+  onMore: (under: string, page: number) => void;
+  classNames: Record<FolderTreeSlot, 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((folder) => {
+        const open = Boolean(expanded[folder.path]);
+        const child = levels[folder.path];
+        return (
+          <li key={folder.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 * 14 }} className="shrink-0" />
+              {folder.hasChildren ? (
+                <button
+                  type="button"
+                  className="w-4 shrink-0 rounded text-xs text-gray-400 hover:text-gray-700"
+                  aria-expanded={open}
+                  aria-label={`${open ? 'Collapse' : 'Expand'} ${folder.name}`}
+                  onClick={() => onToggle(folder.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 === folder.path ? cn.nodeSelected : ''}`}
+                aria-current={selected === folder.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 was "Contracts3" — which is what a screen reader would
+                // have said. The `title` is the FULL path, because the visible
+                // label is only the last segment and a truncated one at that.
+                //
+                // "INSIDE", not "records": the number is DESCENDANTS, and a
+                // reader who has narrowed the list to the shelf would otherwise
+                // hear "Decks, 8 records" beside a list of none. The word has to
+                // be true of the count whatever the list is currently bounded to.
+                aria-label={`${folder.name}, ${folder.count} document${folder.count === 1 ? '' : 's'} inside`}
+                title={folder.path}
+                onClick={() => onSelect(folder.path)}
+              >
+                <span className="truncate">{folder.name}</span>
+                {/* DESCENDANTS, not direct children — which is why a folder can
+                    say 12 and open onto no files of its own. */}
+                <span className={cn.count} aria-hidden="true">{folder.count}</span>
+              </button>
+            </div>
+
+            {open ? (
+              <>
+                {child?.loading && child.rows.length === 0 ? (
+                  <p className={cn.muted} style={{ paddingLeft: (depth + 1) * 14 + 16 }}>Loading…</p>
+                ) : null}
+                {child?.error ? (
+                  <p className={cn.error} role="alert" style={{ paddingLeft: (depth + 1) * 14 + 16 }}>
+                    {child.error}
+                  </p>
+                ) : null}
+                <FolderLevel
+                  under={folder.path}
+                  depth={depth + 1}
+                  levels={levels}
+                  expanded={expanded}
+                  selected={selected}
+                  onSelect={onSelect}
+                  onToggle={onToggle}
+                  onMore={onMore}
+                  classNames={cn}
+                />
+              </>
+            ) : null}
+          </li>
+        );
+      })}
+
+      {/* MORE FOLDERS AT THIS LEVEL. The server's own `count` for this container
+          against what has been drawn, so a directory with 900 subfolders costs
+          one page until somebody asks for the next — rule 8 applies to folders
+          exactly as it applies to rows. */}
+      {remaining > 0 ? (
+        <li>
+          <button
+            type="button"
+            className={cn.more}
+            disabled={level.loading}
+            style={{ marginLeft: depth * 14 + 16 }}
+            onClick={() => onMore(under, level.page + 1)}
+          >
+            {level.loading ? 'Loading…' : `Show ${remaining} more folder${remaining === 1 ? '' : 's'}`}
+          </button>
+        </li>
+      ) : null}
+    </ul>
+  );
+}
+
+/**
+ * The ancestors of a path, for a breadcrumb — `/A/B/C` -> `/A`, `/A/B`, `/A/B/C`.
+ *
+ * SPLITTING IS SAFE HERE AND THE MODULE HEADER'S RULE STILL HOLDS, because this
+ * is not the act that rule forbids. It takes apart a path the server ALREADY
+ * RETURNED TO THIS READER, purely to label controls; clicking a crumb then
+ * issues its own gated request for that container and renders whatever comes
+ * back. It puts no folder on screen that was not already on screen, fills no
+ * level from another level's response, and invents no node. The forbidden act is
+ * SYNTHESISING a node — deciding a folder exists, or what is in it, from data
+ * the server did not return about it — and a breadcrumb over the current
+ * selection does none of that.
+ */
+export function folderTrail(path: string): Array<{ path: string; name: string }> {
+  const segments = String(path ?? '').split('/').filter(Boolean);
+  const trail: Array<{ path: string; name: string }> = [];
+  let at = '';
+  for (const segment of segments) {
+    at = `${at}/${segment}`;
+    trail.push({ path: at, name: folderName(at) });
+  }
+  return trail;
+}

package/src/components/index.ts

@@ -34,6 +34,12 @@ export type {
 // The corpus layer (bd startsim-768w.38.6, startsim-768w.38.7): the READ side of
 // connections. Same rule as above — the page composers ship, not just the parts.
 export * from './pages/LibraryPage';
+// The navigable folder tree the Library stands on (bd startsim-ei8gm.5). Shipped
+// SEPARATELY as well as inside the composer, because "browse this corpus by
+// where things live" is a question every file-shaped source raises and the next
+// surface to ask it should not fork the Library to get an answer.
+export { FolderTree, folderTrail } from './FolderTree';
+export type { FolderSource, FolderTreeProps, FolderTreeSlot } from './FolderTree';
 export * from './pages/AskPage';
 export * from './pages/TrackerPage';