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

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

@@ -0,0 +1,121 @@
+/**
+ * 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 {
+    /**
+     * Every entry taken, in the order they were selected.
+     *
+     * A list rather than one path because a multi-row copy is a normal gesture and the
+     * paste has to put all of them somewhere. A single-row copy is a one-element list,
+     * which is why there is no separate single-row clipboard: one shape means the paste
+     * path cannot be right for one row and wrong for five.
+     */
+    entries: readonly {
+        relPath: string;
+        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;
+    /**
+     * Every row the menu acts on, when the reader right-clicked inside a multi-selection.
+     *
+     * Absent or shorter than two means single-row behaviour, which is why the component
+     * stays one menu rather than gaining a batch twin: the entries, the handlers and the
+     * clipboard are identical, and only the LABELS change to say how many rows they will
+     * touch. A second menu is how the two surfaces drifted apart before.
+     *
+     * `target` is still the row under the pointer -- it anchors the menu and supplies the
+     * name used by rename/download, which have no batch meaning.
+     */
+    selection?: readonly ContextTarget[];
+    /** 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 references into a conversation, via the picker.
+     *
+     * `targets` is present only for a multi-row selection; the single-row case passes the
+     * one path. The picker renders one dialog either way.
+     */
+    onReference: (path: string, isDir: boolean, targets?: readonly ContextTarget[]) => 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,117 @@
+/**
+ * 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;
+    /**
+     * Whether one path is currently favourited, so its row can draw the star.
+     *
+     * The borrowed explorer has no row-decoration hook, so the star is applied by this
+     * wrapper observing the rows it renders (see `useRowFavorites`). Absent means the
+     * caller has no favourites store, which keeps the wrapper from touching the DOM at all.
+     */
+    isFavorite?: (relPath: string) => boolean;
+    /**
+     * Open the row context menu for one row.
+     *
+     * The explorer builds its own menu inside itself and marks the event handled, so the
+     * only place to intercept is a capture-phase listener above it. This wrapper does
+     * that and forwards the row here; the page then renders the SAME menu component the
+     * home table uses, so both surfaces offer one action set.
+     *
+     * Absent means "leave the explorer's own menu alone", which is what a read-only
+     * surface embedding this tree would want.
+     */
+    onRowContextMenu?: (relPath: string, isDir: boolean, at: {
+        x: number;
+        y: number;
+    }, selection?: readonly {
+        relPath: string;
+        name: string;
+        isDir: boolean;
+    }[]) => void;
+    /** The favourites star's accessible name. */
+    favoriteMarkLabel?: string;
+}
+/**
+ * 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,102 @@
+/**
+ * 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;
+    /**
+     * Upload files dropped onto the table area.
+     *
+     * The table lists documents only -- there is no directory row here to aim at -- so
+     * the whole surface is one target and the destination has to be decided rather than
+     * read off the row under the pointer. `dropDirectory` carries that decision.
+     * Omitted by a read-only caller, which keeps the surface from accepting a drop that
+     * would then be refused on the Host.
+     * @param directory - the tree-relative directory the files land in.
+     * @param files - the dropped files with paths relative to that directory.
+     */
+    onUpload?: (directory: string, files: readonly {
+        file: unknown;
+        relativePath: string;
+    }[]) => void;
+    /**
+     * Where a drop on this table lands, tree-relative.
+     *
+     * The reader's own folder is the right default: `global` is the bucket everyone
+     * reads, so defaulting there would publish a private draft without asking. Empty
+     * means the mount root, which is what a caller with no personal bucket gets.
+     */
+    dropDirectory?: string;
+}
+/**
+ * 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;