@sparkelf/dsh-knowledge-base 0.0.0-stage → 0.1.0

package/lib/types/client/KnowledgeContextMenu.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The row context menu for the knowledge tree.
+ *
+ * A right-click on a row used to jump straight to the permission surface, which meant a
+ * reader looking for "save this file" got an operator's dialog instead. The menu is the
+ * affordance a file list is expected to have, and it is built on the product's own `Menu`
+ * primitive rather than a hand-rolled popover: keyboard walking, Escape, outside click,
+ * and post-selection focus return are the primitive's behaviour, and a local copy of that
+ * would drift.
+ *
+ * The menu is positioned from the pointer rather than from an anchor element, which is
+ * what the primitive's `getAnchorRect` hook is for: a context menu opens where the reader
+ * clicked, not below the row's own control.
+ *
+ * Every action here is a call to a route that already exists. Sharing is `grant`, the
+ * star is `favorites.set`, and paste dispatches on what the clipboard holds: a cut pastes
+ * through `move`, a copy through `copy`. Both resolve the destination from the entry's own
+ * name, so a paste cannot rename; both carry a directory's whole subtree. The clipboard is
+ * a client-side pair of paths and a flag -- nothing about a pending paste is worth a
+ * server-side record, and a clipboard that survived a reload would be a paste the reader
+ * could no longer see they had armed.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+import { type ShareDialogCopy } from './KnowledgeShareDialog.tsx';
+/** One row the menu can act on. */
+export interface ContextTarget {
+    /** Path relative to the knowledge root. */
+    relPath: string;
+    /** Display name, used as the rename dialog's starting value. */
+    name: string;
+    /** Whether the row is a directory (renaming one renames the directory). */
+    isDir: boolean;
+}
+/** The clipboard the copy/cut entries fill. */
+export interface TreeClipboard {
+    /** The path that was copied or cut. */
+    relPath: string;
+    /** Its display name, so the paste label can name the entry. */
+    name: string;
+    /** True when the source is removed on paste (cut); false for a copy request. */
+    cut: boolean;
+}
+/** Props for the context menu. */
+export interface KnowledgeContextMenuProps {
+    /** The row the menu is open on, or null when closed. */
+    target: ContextTarget | null;
+    /** Where the pointer was, in viewport coordinates. */
+    at: {
+        x: number;
+        y: number;
+    } | null;
+    /** Copy resolver for this package's namespace. */
+    t: (key: string) => string;
+    /** Copy for the share dialog, which carries its own key set. */
+    shareCopy: ShareDialogCopy;
+    /** Close the menu. */
+    onClose: () => void;
+    /** Open the permission surface for this path. */
+    onGrant: (path: string) => void;
+    /** Toggle the pin state for this path. */
+    onPin: (path: string, pinned: boolean) => void;
+    /** Whether this path is currently pinned. */
+    pinned: boolean;
+    /** Toggle the favourite state for this path. */
+    onFavorite: (path: string, favorite: boolean) => void;
+    /** Whether this path is currently favourited. */
+    favorite: boolean;
+    /** Insert a reference to this path into the conversation. */
+    onReference: (path: string, isDir: boolean) => void;
+    /** Called after a rename succeeds, so the page reloads the tree. */
+    onRenamed: () => void;
+    /** Called after a delete-to-trash succeeds, so the page reloads the tree. */
+    onDeleted: () => void;
+    /** What the clipboard currently holds, or null when it is empty. */
+    clipboard: TreeClipboard | null;
+    /** Put one entry on the clipboard. Recording only; nothing moves until paste. */
+    onClipboard: (entry: TreeClipboard | null) => void;
+    /**
+     * The directory a paste would land in.
+     *
+     * For a directory row the target is that directory; for a file it is the file's
+     * parent. The menu states it so a paste never lands somewhere the reader cannot see,
+     * and `null` means the destination is unknown, which disables the entry rather than
+     * guessing.
+     */
+    pasteInto: string | null;
+    /** Called after a paste succeeds, so the page reloads both affected levels. */
+    onMoved: () => void;
+}
+/**
+ * The knowledge tree's row context menu.
+ * @param props - the target row, the pointer position, and the actions.
+ * @returns The menu, or nothing when it is closed.
+ */
+export declare function KnowledgeContextMenu(props: KnowledgeContextMenuProps): import("react").JSX.Element;

package/lib/types/client/KnowledgeCreateDialog.d.ts

@@ -0,0 +1,134 @@
+/**
+ * One official dialog behind the Home surface's three create/upload actions, plus the
+ * destination picker and name field they all share.
+ *
+ * The reference had a dropdown per card whose rows opened a browser `window.prompt` for
+ * a name and dropped the result into `global/`. Two things were wrong with that: a
+ * prompt cannot show where the file will land, and it cannot offer to change it -- so
+ * every new document silently published to the one bucket everybody reads.
+ *
+ * All three actions therefore share one dialog, because they ask the same two questions
+ * (what is it called, and where does it go) and differ only in what they write: `create`
+ * for a document, `create` with `kind: 'directory'` for a folder, and `upload` per file
+ * for an upload. Keeping them together means the validation, the destination default and
+ * the keyboard contract cannot drift apart between them.
+ *
+ * The dialog is a `Modal` and the fields are `Input`/`Button` from the primitives -- no
+ * hand-built layer -- so Escape, the mask, focus return and the card chrome all come
+ * from the same implementation every other DSH dialog uses. The directory picker reads
+ * the live tree one level at a time through the Host's own listing route (`KB_API.list`),
+ * so it can never offer a directory the caller may not read, and it takes a
+ * `defaultPath` chosen by {@link defaultDestination} rather than guessing.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/**
+ * Where a create or upload should land when the reader has not said otherwise.
+ *
+ * The order is the whole point of this function, and it is deliberately not
+ * "global first":
+ *
+ * 1. The directory the reader is looking at. If they navigated into
+ *    `department/OPS/specs` and then pressed New, that is where they mean -- a
+ *    create that jumps elsewhere makes the tree they are reading a lie.
+ * 2. The reader's own personal directory. Without a current directory this is the
+ *    only bucket that is theirs by construction, so it is the safe default: a file
+ *    created there cannot surprise a colleague.
+ * 3. `global`, last, and only as a last resort. It is the shared bucket, so
+ *    defaulting to it is how a private draft becomes a team announcement.
+ *
+ * @param currentDir - the tree-relative directory the reader is browsing, if any.
+ * @param userId - the caller's DataOps id, from the status route.
+ * @returns A tree-relative directory that exists or is expected to.
+ */
+export declare function defaultDestination(currentDir: string | undefined, userId: string | undefined): string;
+/** Props for the destination picker. */
+export interface KnowledgeDestinationPickerProps {
+    /** Tree-relative directory currently selected. */
+    value: string;
+    /** Called with a new tree-relative directory. */
+    onChange: (path: string) => void;
+    /** Locale-bound copy resolver. */
+    t: (key: string) => string;
+    /** Disables the control while the dialog is submitting. */
+    disabled?: boolean;
+}
+/**
+ * A breadcrumb-style directory chooser: the current path, a way back up, and the
+ * subdirectories of the level being shown.
+ * @param props - the selected path and its change handler.
+ * @returns The picker.
+ */
+export declare function KnowledgeDestinationPicker(props: KnowledgeDestinationPickerProps): import("react").JSX.Element;
+/** Props for the name field, shared by the document and folder forms. */
+export interface KnowledgeNameFieldProps {
+    /** What the reader has typed so far. */
+    value: string;
+    /** Called on every keystroke. */
+    onChange: (next: string) => void;
+    /** Locale-bound copy resolver. */
+    t: (key: string) => string;
+    /** Placeholder naming the kind being created. */
+    placeholder: string;
+    /** Set while submitting. */
+    disabled?: boolean;
+    /** A validation message to show under the field. */
+    error?: string;
+}
+/**
+ * Reject a name this tree cannot store.
+ *
+ * The rule mirrors the Host's `isContainedRelPath`: a name may not be empty, may not
+ * contain a separator (that would silently make the "name" a path), and may not be
+ * a traversal segment. Rejecting it here turns a refused request into an inline
+ * sentence before the reader presses Create.
+ * @param name - the candidate name, without any directory part.
+ * @returns A locale key naming the problem, or undefined when the name is fine.
+ */
+export declare function validateEntryName(name: string): 'createNameEmpty' | 'createNameSeparator' | 'createNameTraversal' | undefined;
+/**
+ * The name field with its inline validation.
+ * @param props - the field's state.
+ * @returns The labelled input.
+ */
+export declare function KnowledgeNameField(props: KnowledgeNameFieldProps): import("react").JSX.Element;
+/**
+ * Which of the three flows the dialog is running.
+ *
+ * `upload-file` and `upload-folder` differ only in how the browser's picker is
+ * configured (`webkitdirectory`), not in what the dialog asks; the destination is a
+ * single choice for the whole selection, which is what "choose where these go"
+ * means.
+ */
+export type CreateMode = 'new-doc' | 'new-folder' | 'upload-file' | 'upload-folder';
+/** One file a reader chose, with the path it should land at. */
+export interface PendingUpload {
+    /** The file as the browser handed it over. */
+    file: File;
+    /** Its name relative to the picked root: a folder upload keeps its shape. */
+    relative: string;
+}
+/** Props for the dialog. */
+export interface KnowledgeCreateDialogProps {
+    /** Whether the dialog is showing. */
+    open: boolean;
+    /** Which flow to run. */
+    mode: CreateMode;
+    /** Close without writing anything. */
+    onClose: () => void;
+    /** The directory the dialog should start in, from {@link defaultDestination}. */
+    defaultPath: string;
+    /** Locale-bound copy resolver. */
+    t: (key: string) => string;
+    /**
+     * Report the outcome and refresh the caller's listing.
+     * @param message - a locale-bound sentence to show under the cards.
+     */
+    onDone: (message: string) => void;
+}
+/**
+ * The create/upload dialog.
+ * @param props - the flow, its starting directory, and the outcome channel.
+ * @returns The dialog, or null while closed.
+ */
+export declare function KnowledgeCreateDialog(props: KnowledgeCreateDialogProps): import("react").JSX.Element;

package/lib/types/client/KnowledgeFileTree.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The knowledge tree, drawn by the product's own file explorer.
+ *
+ * The listing next door is a hand-built copy of `dsh-better-sidebar`'s explorer: its CSS
+ * module says so ("Copied from the file explorer in dsh-better-sidebar", with each metric
+ * measured against `.explorerRow`). A copy drifts -- the explorer gains sort controls,
+ * inline rename, an upload strip, git tones, an open-with submenu, none of which arrive
+ * in a copy -- so this component renders the REAL explorer instead, pointed at the
+ * knowledge root.
+ *
+ * That is possible because `/workspace/kb` is a symlink into the caller's view: the
+ * explorer's `cwd` is a plain absolute path, so pointing it there reads the knowledge tree
+ * through exactly the machinery that reads any other workspace directory. Measured before
+ * writing this: `POST /sidebar/api/fs.trees {cwd:'/workspace/kb'}` answers the tree's
+ * entries, so no new route and no second file API are involved.
+ *
+ * What the explorer does NOT know about is the knowledge base's own metadata files
+ * (`.kb-audit.jsonl`, `.kb-settings.json`, `.kb-tree-state.json`, `.pinned.json`,
+ * `.view-mode.json`, `.kb-favorites.json`, `.kb-trash.json`). They live in the view so
+ * every user's copy carries them, and they are neither knowledge documents nor anything
+ * a reader should rename. They are filtered with the `exclude` prop, which the host
+ * applies to the listing -- so they never arrive rather than being hidden after the fact.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+import type { UploadItem } from 'dsh-better-sidebar/src/client/upload.ts';
+import { type DepartmentPath } from './departmentFolders.ts';
+export interface KnowledgeFileTreeProps {
+    /** The conversation this tree belongs to; the explorer keys its fs requests by it. */
+    sessionId: string;
+    /** Absolute path of the knowledge root inside the workspace. */
+    root: string;
+    /** Directories the reader has expanded, by absolute path. */
+    expanded: readonly string[];
+    /** Files highlighted by a "show in folder" reveal, by absolute path. */
+    revealed: readonly string[];
+    /** Toggle one directory open or closed. */
+    onToggle: (path: string) => void;
+    /** Open one file for preview. */
+    onOpenFile: (path: string) => void;
+    /** Insert a reference to one path into the conversation draft. */
+    onReferenceFile: (path: string, isDir: boolean) => void;
+    /** Upload files into a directory (absolute, inside the knowledge root). */
+    onUploadRequest: (dir: string, items: UploadItem[]) => void;
+    /** True while an upload is in flight. */
+    busy: boolean;
+    /** Bump to reload the visible set after a change made elsewhere. */
+    refreshTick: number;
+    /** Called after the explorer's own inline rename lands. */
+    onPathRenamed?: (oldPath: string, newPath: string) => void;
+    /** Called after the explorer's own delete lands. */
+    onPathDeleted?: (path: string, isDir: boolean) => void;
+    /** Whether the owning surface is on screen. */
+    visible?: boolean;
+    /**
+     * Say the three buckets in the reader's language.
+     *
+     * `global` / `department` / `personal` are the folders' names on disk, and they have
+     * to stay that way: they are path segments the deployment shares and the caller's
+     * view is built from them. What the reader is being told by that folder is not its
+     * path but its AUDIENCE -- who may see what is inside -- so the row prints the
+     * audience and the path is left alone.
+     *
+     * Keyed by the tree-relative path, so the map can be built from copy alone.
+     */
+    bucketLabels?: Readonly<Record<string, string>>;
+    /**
+     * The reader's own organization chain, so department folders print their NAME.
+     *
+     * The department bucket stores folders by code (`nanning-psb`), because a code is a
+     * stable slug: renaming a department cannot move a document. The reader, though,
+     * knows their organization by name, so those same rows have to print
+     * 「南宁市公安局」 rather than the slug.
+     *
+     * Only the caller's own chain is translated, and only within the department bucket.
+     * A peer department's folder keeps printing its code: this build has no name for it,
+     * and the whole organization tree is readable only by an administrator. Deriving a
+     * "name" from the code would put an invented label in front of the reader, which is
+     * worse than the code they can at least match against their own department.
+     */
+    departmentPath?: DepartmentPath;
+}
+/**
+ * The knowledge tree, rendered by the product's file explorer.
+ * @param props - the root, the reader's expansion state, and the actions.
+ * @returns The explorer's tree, rooted at the knowledge directory.
+ */
+export declare function KnowledgeFileTree(props: KnowledgeFileTreeProps): import("react").JSX.Element;

package/lib/types/client/KnowledgeHome.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The Home surface: the page's landing view.
+ *
+ * Three ways to start, over a tabbed list of what the reader already has. The tabs
+ * select the SET, and the table shows that set's rows; nothing here invents data,
+ * so a tab with no rows says so rather than filling the table with placeholders.
+ *
+ * The listing comes from the same route the tree uses. Categorising a document as
+ * "owned by me" or "shared with me" would need an owner per file, and the
+ * knowledge tree carries none: it is a directory of documents whose authorization
+ * lives in DataOps grants. So the tabs narrow by what the tree can actually
+ * answer, and the Owner column is drawn from the grant data only when a caller
+ * supplies it. Filling that column with a guess would be worse than leaving it
+ * blank.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** Props for the Home surface. */
+export interface KnowledgeHomeProps {
+    /** Locale-bound copy resolver. */
+    t: (key: string) => string;
+    /** Locale tag, so dates match the reader's language. */
+    locale?: string;
+    /** Disabled when the tree is not mounted, so the cards cannot promise a tree. */
+    mountPoint: string;
+    /** Open one document in the preview. */
+    onOpen: (path: string) => void;
+    /**
+     * The caller's DataOps id, when the status route reported one.
+     *
+     * Used only to choose where a create lands by default: with no current directory
+     * the reader's own `personal/<id>` folder is the one place a new draft cannot
+     * surprise a colleague, so it is preferred over `global`.
+     */
+    callerId?: string;
+    /** The caller's own department code, so the owner cell can name it instead of a slug. */
+    departmentCode?: string;
+    /** The caller's own department name; the code stands in when this is absent. */
+    departmentName?: string;
+    /**
+     * The tab whose card should take focus on mount.
+     *
+     * Set when a reader arrives here from the tree's empty state, which is asking
+     * them to start a document: the blank-page card is the answer to that question,
+     * so it is the one that should be reachable by keyboard immediately.
+     */
+    focusNew?: boolean;
+    /**
+     * Star or unstar one row.
+     *
+     * The Home table is the surface a reader actually starts from, so the context menu
+     * lives here as well as on the tree. Omitted by a caller with no favourites store,
+     * which keeps the menu's star entry out rather than offering a write that cannot land.
+     */
+    onFavorite?: (path: string, favorite: boolean) => void;
+    /** Whether one path is currently favourited, so the row can draw its star. */
+    isFavorite?: (path: string) => boolean;
+    /** Open the permission surface for one path. */
+    onGrant?: (path: string) => void;
+    /** Insert a reference to this path into the conversation. */
+    onReference?: (path: string, isDir: boolean) => void;
+    /** Pin or unpin one row, offered by the same menu the tree uses. */
+    onPin?: (path: string, pinned: boolean) => void;
+    /** Whether one path is currently pinned. */
+    isPinned?: (path: string) => boolean;
+    /**
+     * Called after any menu action that changed the tree.
+     *
+     * The table holds its own rows, so a rename/delete/paste has to be followed by a
+     * re-read; the page owns the tick that triggers it.
+     */
+    onTreeChanged?: () => void;
+}
+/**
+ * Render the Home surface.
+ * @param props - copy resolver, mount state, and the open callback.
+ * @returns The Home view.
+ */
+export declare function KnowledgeHome(props: KnowledgeHomeProps): import("react").JSX.Element;

package/lib/types/client/KnowledgeIndexing.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The indexing surface of the management page.
+ *
+ * There is no separate index. Retrieval reads the mounted tree directly with grep
+ * and read, so a "rebuild" is a recount of what is mounted, and it answers
+ * synchronously. Presenting it as a background job would invent a queue the plugin
+ * does not have, so this surface says what it is in its own copy instead of
+ * implying an index process.
+ *
+ * The table reports per-directory facts the Host derived from the filesystem:
+ * how many files are below each directory, when the newest one changed, and
+ * whether the caller can read it. Those are measurements, not estimates, and a
+ * directory whose numbers are not known is absent rather than shown as zero.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+import { type ReactNode } from 'react';
+import { type KnowledgeStatusView } from '../api.ts';
+/** One directory's measured shape, as the Host reports it. */
+export interface IndexDirectory {
+    /** Path relative to the mount point; empty string means the root itself. */
+    relPath: string;
+    /** Files below this directory, counted recursively. */
+    fileCount: number;
+    /** Newest modification instant in Unix ms, absent when nothing could be read. */
+    mtimeMs?: number;
+    /** Whether this directory's own entries could be listed. */
+    readable: boolean;
+    /**
+     * Whether some part of the subtree could not be read, so `fileCount` is a lower
+     * bound rather than a total.
+     *
+     * Absent from an older Host, which is why it is optional here: a missing flag is
+     * treated as "not known to be partial" rather than as "complete", so the column
+     * never claims more than the Host measured.
+     */
+    partial?: boolean;
+}
+/** Props for the indexing surface. */
+export interface KnowledgeIndexingProps {
+    /**
+     * Publishes this page's primary control to the panel header.
+     *
+     * The header is the only band at the top of the page, so a page-level action has
+     * to be handed up rather than drawn in a second title row.
+     */
+    onAction?: (action: ReactNode) => void;
+    /** Status the page already loaded, used for the first paint. */
+    status: KnowledgeStatusView;
+    /** Called after a rescan, so the page can refresh what it shows. */
+    onChanged: () => void;
+    /** Locale-bound copy for this package's namespace. */
+    t: (key: string) => string;
+}
+/**
+ * Render the index state as a per-directory table.
+ * @param props - the loaded status and a refresh callback.
+ * @returns The indexing surface.
+ */
+export declare function KnowledgeIndexing(props: KnowledgeIndexingProps): import("react").JSX.Element;

package/lib/types/client/KnowledgeListing.d.ts

@@ -0,0 +1,160 @@
+/**
+ * A directory listing with the modification time each entry carries.
+ *
+ * The row is the file explorer's own row from `dsh-better-sidebar`, copied from
+ * `src/client/FileTree.tsx` (`FileRow`/`DirRow`) and `src/client/sidebar.module.css`
+ * (`.explorerRow`): the same `div[role=button]`, the same 14px glyph, the same
+ * ellipsised name, the same trailing modified time that yields its right edge to
+ * the same hover-revealed `@` reference button, and the same `depth * 22 + 6`
+ * indent. A reader sees that tree in this window's right sidebar, so a second
+ * design beside it reads as bolted on -- which is why this is a copy rather than
+ * a re-drawing.
+ *
+ * What the borrowed tree cannot carry is why this list exists. Its host entry
+ * shape (`FsEntry`: name, path, isDir, hidden, isSymlink, broken) has no
+ * timestamp, so a row built from it can never show when a document last changed;
+ * and its rows decide visibility from a shared curated store rather than from
+ * per-user grants. This panel reads the same directories through the plugin's own
+ * route, which stats each child, and its row carries a right-click into the grant
+ * form the tree has no place for.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+import { type ReactNode } from 'react';
+/** Props for the listing panel. */
+export interface KnowledgeListingProps {
+    /** Locale-bound copy resolver. */
+    t: (key: string) => string;
+    /** Called with a chosen path so the page can show its preview. */
+    onOpen: (path: string) => void;
+    /** Re-read trigger, so a rescan from elsewhere refreshes this too. */
+    refreshTick?: number;
+    /** Locale tag, so dates match the reader's language. */
+    locale?: string;
+    /**
+     * Open the permission surface for one path.
+     *
+     * Exists because the borrowed tree's context menu is built inside it with no way
+     * to add a row, so the grant entry lives here instead: this is the plugin's own
+     * listing, where a right-click can mean what the knowledge base needs it to mean.
+     */
+    onGrant?: (path: string) => void;
+    /**
+     * Insert one row's reference into the conversation draft.
+     *
+     * The borrowed tree reveals this affordance on hover; the listing mirrors that so
+     * a reader gets the same `@` action from either tree.
+     */
+    onReference?: (path: string, isDir: boolean) => void;
+    /**
+     * Pin or unpin one row.
+     *
+     * Omitted by a caller that has no pin store, which is how the search results list
+     * stays free of an action that would only make sense inside the tree.
+     */
+    onPin?: (path: string, pinned: boolean) => void;
+    /** Whether one path is currently pinned, so the row can mark it. */
+    isPinned?: (path: string) => boolean;
+    /**
+     * Star or unstar one row.
+     *
+     * Omitted by a caller with no favourites store, which is how the search results list
+     * stays free of an entry that would only make sense inside the tree. A folder is
+     * favoured the same way a file is: the star marks a row, not a document.
+     */
+    onFavorite?: (path: string, favorite: boolean) => void;
+    /** Whether one path is currently favourited, so the row can draw its star. */
+    isFavorite?: (path: string) => boolean;
+    /**
+     * The path a paste would land in, given the row this menu was opened on.
+     *
+     * A directory row pastes INTO itself; a file row pastes beside itself. Kept a
+     * callback rather than derived in the menu because only the listing knows whether a
+     * row is the tree's root, which has no parent to paste beside.
+     */
+    pasteTargetFor?: (relPath: string, isDir: boolean) => string | null;
+    /**
+     * Called after a menu-driven delete or paste succeeded.
+     *
+     * Both change paths this component is currently holding -- a delete removes one, a
+     * paste adds one and empties another -- so the page has to reload rather than the
+     * component guessing which levels moved.
+     */
+    onTreeChanged?: () => void;
+    /**
+     * Called after a rename succeeded, so the page reloads the tree.
+     *
+     * The listing cannot reload itself: it reads through `refreshTick`, which the page
+     * owns, and a rename changes the paths this component is currently holding.
+     */
+    onRenamed?: () => void;
+    /**
+     * Render one row's action as "unpin" rather than "pin".
+     *
+     * The pinned band lists paths that are already pinned, so every row there offers
+     * the opposite action; deriving it from a flag keeps one row shape for both bands.
+     */
+    unpinOnly?: boolean;
+    /**
+     * Narrow the tree to rows whose name contains this text.
+     *
+     * Filtering happens over the rows already read, so it costs no request: the tree
+     * section header's search is the in-place narrowing, while the rail's field is the
+     * cross-directory search. A filter that matched nothing read as an empty tree, so
+     * the two empty states are kept apart.
+     */
+    filter?: string;
+    /**
+     * Start with every directory expanded.
+     *
+     * Used by the pinned band, where a pinned folder is only useful if its contents
+     * are already visible.
+     */
+    expandAll?: boolean;
+    /**
+     * The action offered when the tree genuinely holds no documents.
+     *
+     * Distinct from a filter that matched nothing: an empty tree wants a way to make
+     * a document, while an unmatched filter wants a different search term.
+     */
+    emptyAction?: ReactNode;
+    /**
+     * Move one entry into a directory, or pin it when the target is the pin band.
+     *
+     * Omitted by a caller that must stay read-only, which is how the search results
+     * list keeps its rows free of a gesture the Host would refuse there.
+     */
+    onMove?: (from: string, toDirectory: string) => void;
+    /**
+     * The layout to render. `list` is the tree; `grid` is the document cards.
+     *
+     * Defaults to the tree so a caller that does not persist a preference behaves
+     * exactly as it did before the card view existed.
+     */
+    viewMode?: 'list' | 'grid';
+    /**
+     * Enter multi-select. A callback rather than internal state because the batch
+     * bar's actions are the host's (they move and pin through the same routes a
+     * single drag uses), so the selection has to be visible to it.
+     */
+    onSelectionChange?: (paths: readonly string[]) => void;
+    /** The current selection, so a batch action can act on it. */
+    selection?: readonly string[];
+}
+/**
+ * The drag payload's MIME type.
+ *
+ * Exported because the drop target that pins is NOT in this component: the pin
+ * band lives in the panel, and the two have to agree on the name of the thing
+ * being carried. The native drag payload is used rather than lifted React state
+ * for exactly that reason -- it crosses the component boundary the gesture
+ * crosses, without the panel having to hold a second copy of the tree's state.
+ */
+export declare const KB_DRAG_MIME = "application/x-dsh-kb-path";
+/**
+ * Render the listing for the mount's top level, and one level per expanded
+ * directory.
+ * @param props - copy resolver and the open callback.
+ * @returns The listing panel.
+ */
+export declare function KnowledgeListing(props: KnowledgeListingProps): import("react").JSX.Element;

package/lib/types/client/KnowledgeLoading.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The loading state, as a book whose page turns.
+ *
+ * The knowledge base is a library of documents, so a turning page says what is
+ * happening in the product's own terms rather than with a generic spinner. The
+ * animation is CSS and inline SVG: no animation library, because this plugin ships
+ * as one bundled file and a dependency would grow it and add a supply-chain surface
+ * for a decoration.
+ *
+ * The motion is a real 3D turn rather than a sequence of drawn frames: the leaf is a
+ * zero-thickness plane inside a `perspective` container, rotated about the spine with
+ * `rotateY`. That keeps the whole effect to two keyframes and makes the direction of
+ * travel read correctly at any moment, which a frame sequence does not.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** Props for the loading surface. */
+export interface KnowledgeLoadingProps {
+    /**
+     * What is being loaded, in the reader's language.
+     *
+     * Optional because a card or a table cell may have no label of its own; the
+     * animation then stands alone and the accessible name falls back to the shared
+     * loading sentence.
+     */
+    label?: string;
+    /**
+     * Accessible name for the animation itself.
+     *
+     * Required rather than derived: the animation is decorative, so it must either be
+     * hidden from assistive technology or carry a name, and hiding it silently would
+     * leave a screen-reader user with no announcement that anything is loading.
+     */
+    announce?: string;
+}
+/**
+ * Render the book-turning loading animation.
+ * @param props - the optional label and the accessible announcement.
+ * @returns The centred loading surface.
+ */
+export declare function KnowledgeLoading(props: KnowledgeLoadingProps): import("react").JSX.Element;