@sparkelf/dsh-knowledge-base 0.1.0 → 0.1.1

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

@@ -0,0 +1,53 @@
+/**
+ * The progress strip at the bottom of the knowledge base panel.
+ *
+ * Uploading a document and extracting its text are two waits a reader cannot see
+ * otherwise: the drop appears to do nothing until the bytes land, and a scanned PDF
+ * looks uploaded while its `.md` sibling is still being produced. Both are reported
+ * here, in one place, at the bottom of the surface the reader is already looking at.
+ *
+ * It is a resident strip rather than a toast on purpose. A toast is gone before a slow
+ * parse finishes, and the reader's next question ("did it work?") has nowhere to go;
+ * this stays until the work is done and then folds to one line so it stops taking
+ * space without taking the record away.
+ *
+ * Nothing here is persisted. A refresh loses the history, which is the right trade: the
+ * files themselves are on disk, and a stale "uploading 40%" from yesterday would be a
+ * lie the reader cannot clear.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** One file's upload, as the strip shows it. */
+export interface UploadTaskView {
+    /** The file's path relative to the drop target: the name the reader dropped. */
+    name: string;
+    /** The tree-relative directory it is landing in, `''` for the mount root. */
+    dir: string;
+    /** Where this file is in its own lifecycle. */
+    state: 'waiting' | 'uploading' | 'done' | 'failed';
+    /** Why it failed, in the Host's own words. */
+    reason?: string;
+}
+/** Props for the progress strip. */
+export interface KnowledgeProgressPanelProps {
+    /** Locale-bound copy resolver. */
+    t: (key: string) => string;
+    /** The batch currently uploading, oldest first; empty when nothing is in flight. */
+    uploads: readonly UploadTaskView[];
+    /**
+     * Whether to read extraction progress at all.
+     *
+     * False on a surface that cannot extract (no mount, or a caller without write
+     * access): polling a route whose answer can never be acted on is a request per
+     * reader that buys nothing.
+     */
+    watchExtraction: boolean;
+    /** Called after a retry was accepted, so the caller can refresh its own views. */
+    onRetried?: (relPath: string) => void;
+}
+/**
+ * Render the bottom progress strip.
+ * @param props - the upload batch, whether to watch extraction, and the copy resolver.
+ * @returns The strip, or nothing when there is no work to show.
+ */
+export declare function KnowledgeProgressPanel(props: KnowledgeProgressPanelProps): import("react").JSX.Element | null;

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

@@ -33,6 +33,22 @@ export interface KnowledgeReferencePickerProps {
     path: string;
     /** Whether that entry is a directory (a folder mention rather than a file chip). */
     isDir: boolean;
+    /**
+     * Every entry a multi-row selection asked to reference.
+     *
+     * Present only when the `@` button was pressed with several rows selected; the
+     * single-row case keeps using `path`/`isDir`. Each entry carries its own `isDir`
+     * because a selection may mix folders and documents, and the mention spelling
+     * differs between them.
+     *
+     * This is one dialog for both cases on purpose: "where should this go" is the same
+     * question whether one row or five are being referenced, and a second batch-only
+     * dialog would be a second place for the insertion contract to drift.
+     */
+    targets?: readonly {
+        path: string;
+        isDir: boolean;
+    }[];
     /** The client context; both the draft insert and the service lookups need it. */
     ctx: unknown;
     /** Locale-bound copy for this package's namespace. */

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

@@ -0,0 +1,40 @@
+/**
+ * Ordering for the audit trail.
+ *
+ * Only the ordering lives here. Paging is the shared `paging.ts` utility that the other
+ * tables in this package use, adopted rather than duplicated: two implementations of
+ * "slice a page and clamp it" drift, and the one that is not used by the table next door
+ * is the one that gets the fix.
+ *
+ * The order is a correctness rule, not a presentation detail. The Host happens to append
+ * newest-last to its log, so a table that drew the array as received would look right
+ * until the writer changed. The reader's question is "what happened most recently", and
+ * that answer is computed here from the timestamps.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** The fields the ordering rule needs. */
+export interface AuditRow {
+    /** ISO-8601 instant the row records. */
+    at: string;
+    /** Path the action concerned, used as the tie-breaker. */
+    relPath: string;
+    /** What was done, used as the second tie-breaker. */
+    action: string;
+    /** Destination for a move, used as the last tie-breaker. */
+    toRelPath?: string;
+}
+/**
+ * Order rows newest first, with a stable tie-break.
+ *
+ * The secondary keys are what stop rows from swapping places between renders when several
+ * share an instant -- the normal case for a batch, where one action writes several rows
+ * with the same `at`. Without them the platform sort could order equal keys either way,
+ * and a reader paging forward would see a row twice or not at all.
+ *
+ * Ordering is total: `relPath`, then `action`, then `toRelPath` are all compared, and two
+ * rows equal in every one of those are indistinguishable to this table anyway.
+ * @param rows - the rows as received.
+ * @returns A new array; the input is not mutated.
+ */
+export declare function sortAuditRows<T extends AuditRow>(rows: readonly T[]): T[];

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

@@ -18,7 +18,20 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
         'settings.knowledgeBase': KnowledgeKey;
     }
 }
-/** Client services required for these contributions. */
+/**
+ * Client services required for these contributions.
+ *
+ * `sessions` and `workspaces` are here because the `@`-reference dialog inserts into a
+ * conversation draft, and that insert resolves the target session's scope through
+ * `ctx.sessions` before it can write anything. Without the injection the service is not
+ * on this plugin's ctx at all: the call throws `cannot get property "sessions" without
+ * inject`, `referenceInChat` catches it into a `console.warn`, and the reader sees a
+ * dialog that closes and inserts nothing -- the exact "clicked, nothing happened"
+ * symptom this injection fixes at the root rather than by reporting the failure.
+ *
+ * `workspaces` is the other half: the mention is spelled relative to the workspace that
+ * owns the session, so the insert needs that root to project the path.
+ */
 export declare const inject: string[];
 /**
  * Register the knowledge-base navigation entry and Settings section.

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

@@ -0,0 +1,60 @@
+/**
+ * When to keep waiting for a freshly created conversation, and when to give up.
+ *
+ * Lifted out of the picker's `createNew` because the part worth testing is a decision,
+ * not a render: "retry, insert, or report failure" is a pure function of two booleans
+ * and a clock, and the failure mode when it is wrong is silence — the dialog closes and
+ * nothing happens, which is exactly the bug class this whole surface exists to end.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** What one readiness attempt found. */
+export interface ReadinessProbe {
+    /** Whether a session id could be resolved at all (the catalog has it). */
+    hasTarget: boolean;
+    /** Whether the insert actually landed (the workspace could resolve the root). */
+    inserted: boolean;
+}
+/** What the caller should do next. */
+export type ReadinessAction = 
+/** Try again shortly: the ordinary race, not a refusal. */
+'retry'
+/** Everything landed. */
+ | 'done'
+/** Out of time with no session to target. */
+ | 'failed-no-target'
+/** Out of time with a session but nothing inserted. */
+ | 'failed-insert';
+/**
+ * Decide the next move for one readiness attempt.
+ *
+ * The deadline is passed in rather than read here so the decision is reproducible in a
+ * test: a function that read the clock itself could only be tested by waiting.
+ *
+ * The ordering matters. "No target yet" and "target but no insert" are different
+ * failures and get different messages; collapsing them would tell a reader "could not
+ * insert" when in fact no conversation was ever identified.
+ * @param probe - what this attempt observed.
+ * @param expired - whether the wait budget is already spent.
+ * @returns The action the caller should take.
+ */
+export declare function decideReadiness(probe: ReadinessProbe, expired: boolean): ReadinessAction;
+/**
+ * Whether the wait budget is spent.
+ *
+ * Split out and tested because the naive version of this comparison is what broke: a
+ * deadline computed inside the retry function is recomputed on every pass, so it never
+ * expires and the "report a failure" branch becomes unreachable. A test that pins
+ * `deadline === now` to `true` is the cheapest way to keep that from coming back.
+ * @param now - current epoch milliseconds.
+ * @param deadline - the instant the budget runs out.
+ * @returns True once `now` has reached the deadline.
+ */
+export declare function isExpired(now: number, deadline: number): boolean;
+/**
+ * The deadline for a wait that starts now.
+ * @param now - current epoch milliseconds.
+ * @param budgetMs - how long the caller is willing to wait.
+ * @returns The instant the budget runs out.
+ */
+export declare function deadlineFrom(now: number, budgetMs: number): number;

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

@@ -73,7 +73,7 @@ export declare const en: {
     readonly homeTemplateBody: "Start from a template the team already uses.";
     readonly homeTabRecent: "Recently opened";
     readonly homeTabMine: "Owned by me";
-    readonly homeTabShared: "Shared with me";
+    readonly homeTabShared: "Shares";
     readonly homeTabStarred: "Starred";
     readonly homeColTitle: "Title";
     readonly homeColLocation: "Location";
@@ -342,6 +342,73 @@ export declare const en: {
     readonly 'step.sshfs-mount': "Mount the share over SSHFS";
     readonly 'step.sshfs-verify': "Verify the SSHFS mount";
     readonly deployLocalOnly: "Deployment steps run on a remote host. This workspace stores documents locally, so there is nothing to deploy.";
+    readonly shareGroupReceived: "Inbound";
+    readonly shareGroupGiven: "Outbound";
+    readonly shareColRelation: "Sharing";
+    readonly shareColAudience: "Shared with";
+    readonly shareColPermission: "Permission";
+    readonly shareReceivedEmpty: "Nothing has been shared with you yet.";
+    readonly shareGivenEmpty: "You have not shared anything yet.";
+    readonly shareGivenRelation: "Me → {audience}";
+    readonly shareReceivedRelation: "From resource owner";
+    readonly shareUnknownAudience: "Unknown principal";
+    readonly refPickerBack: "Back";
+    readonly actionFavoriteMany: "Add {n} to favourites";
+    readonly actionUnfavoriteMany: "Remove {n} from favourites";
+    readonly actionCopyMany: "Copy {n} items";
+    readonly actionCutMany: "Cut {n} items";
+    readonly actionDeleteMany: "Delete {n} items (move to trash)";
+    readonly refPickerBatchTitle: "Reference {n} items in a chat";
+    readonly refPickerFailed: "Could not insert the reference into that chat.";
+    readonly dropHomeHint: "Drop to upload into your personal folder";
+    readonly progressTitle: "Progress";
+    readonly progressRoot: "Root";
+    readonly overviewByRole: "By role";
+    readonly sourceDirect: "Direct";
+    readonly sourceViaRole: "Via role {role}";
+    readonly sourceUnavailable: "Inheritance unavailable (requires admin access)";
+    readonly emptyByPerson: "No account is granted access directly.";
+    readonly emptyByRole: "No role is granted access.";
+    readonly emptyByResource: "No resource is granted access.";
+    readonly actionsUnknown: "Unknown";
+    readonly actionsUnknownHint: "Could not determine the full permission set";
+    readonly colAccount: "Account";
+    readonly colSource: "Source";
+    readonly roleMemberCount: "{count} member(s)";
+    readonly homeStarredEmpty: "Nothing starred yet.";
+    readonly menuExtractMarkdown: "Extract Markdown";
+    readonly extractRunning: "Extracting…";
+    readonly extractDone: "Markdown extracted";
+    readonly extractExists: "Markdown already exists";
+    readonly extractUnsupported: "This file type cannot be extracted";
+    readonly extractFailed: "Extraction failed: {reason}";
+    readonly dropFailed: "{ok} uploaded, {n} failed: {names}";
+    readonly dropDismiss: "Dismiss";
+    readonly dropUploading: "Uploading…";
+    readonly dropNeedsFolder: "Drop onto a folder";
+    readonly dropNoFiles: "No files to upload";
+    readonly progressUploadGroup: "Uploads";
+    readonly progressExtractGroup: "Extractions";
+    readonly progressUploading: "Uploading {done}/{total}";
+    readonly progressPending: "Queued";
+    readonly progressExtracting: "Extracting";
+    readonly progressExtractingVia: "Extracting ({via})";
+    readonly progressSucceeded: "Done";
+    readonly progressFailed: "Failed: {reason}";
+    readonly progressUnsupported: "This file type has no extractor";
+    readonly progressRetry: "Retry";
+    readonly progressCollapse: "Collapse";
+    readonly progressExpand: "Expand";
+    readonly progressSummary: "{uploaded} uploaded, {failed} failed";
+    readonly progressSummaryExtract: "{done} extracted, {failed} failed";
+    readonly progressRetrying: "Retrying…";
+    readonly progressRetryFailed: "Retry failed: {reason}";
+    readonly auditPagePrev: "Previous";
+    readonly auditPageNext: "Next";
+    readonly auditPageOf: "Page {page} of {pages}";
+    readonly auditPageSize: "Rows";
+    readonly auditPageSizeOption: "{size}";
+    readonly auditPageTotal: "{total} entries";
     readonly settingsMineruHeading: "MinerU service address";
     readonly settingsMineruHint: "Where documents are parsed. Leave it empty to use the port this deployment was configured with.";
     readonly settingsMineruPlaceholder: "Leave empty to derive from the configured port";

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

@@ -0,0 +1,69 @@
+/**
+ * Page slicing for every table in the knowledge surface.
+ *
+ * A pure module rather than a hook: the rule worth testing is arithmetic, and a hook
+ * would need a renderer to exercise. The component owns the page and size as state;
+ * this answers what that state should display.
+ *
+ * The one rule that matters is the clamp. A reader can be on page 7 of a table when a
+ * filter, a search word or a re-read shrinks it to two pages, and obeying "page 7"
+ * literally renders an empty table with a pager that still says there is data. So the
+ * requested page is clamped into range and the clamped value is returned, which is what
+ * the owner writes back into its own state.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client/paging
+ */
+/** Page sizes every table offers, in the order the control shows them. */
+export declare const PAGE_SIZES: readonly [20, 50, 100];
+/** The page size a fresh table starts on. */
+export declare const DEFAULT_PAGE_SIZE = 20;
+/** One page of rows plus the numbers a pager draws. */
+export interface Page<T> {
+    /** The rows on this page, in order. */
+    rows: T[];
+    /** 1-based page actually shown, clamped into range. */
+    page: number;
+    /** Total number of pages; never zero, so no pager can say "page 1 of 0". */
+    pageCount: number;
+    /** Total row count across all pages. */
+    total: number;
+}
+/**
+ * Whether a table of this size needs a pager at all.
+ *
+ * A single page has nothing to page through, so the control row is not drawn: an
+ * always-visible pager on a three-row table is furniture that implies the reader is
+ * missing something. Empty is the same answer for the same reason.
+ * @param total - row count before slicing.
+ * @param pageSize - rows per page.
+ * @returns true when there is more than one page.
+ */
+export declare function needsPager(total: number, pageSize: number): boolean;
+/**
+ * Slice one page out of a list that is already in display order.
+ *
+ * Ordering is the caller's job and happens BEFORE this call: pagination must never
+ * reorder, or turning a page would appear to sort the table differently. The same
+ * applies to filtering -- a filtered list is what gets paged, so the count in the pager
+ * is the count of matches rather than of the whole table.
+ *
+ * @param rows - rows already filtered and ordered.
+ * @param page - 1-based page requested; clamped into range.
+ * @param pageSize - rows per page; a non-positive or non-integer value falls back.
+ * @returns The page and the numbers to draw.
+ */
+export declare function paginate<T>(rows: readonly T[], page: number, pageSize: number): Page<T>;
+/**
+ * The 1-based page a size change should land on.
+ *
+ * Keeping the first visible row in view is the point: a reader who switches from 20 to
+ * 100 rows is looking at row 41, so the page they want is the one containing it, not
+ * page 1 and not page 3 of the old numbering. Clamping in {@link paginate} then keeps
+ * that answer in range if the list is shorter than expected.
+ *
+ * @param currentPage - page shown before the change.
+ * @param previousSize - size in force before the change.
+ * @param nextSize - size being chosen.
+ * @returns The 1-based page to request.
+ */
+export declare function pageAfterSizeChange(currentPage: number, previousSize: number, nextSize: number): number;

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

@@ -50,16 +50,64 @@ export interface ResourceHoldings {
         grants: GrantView[];
     }>;
 }
+/**
+ * The result of reading a set of grants as permissions.
+ *
+ * `known: false` carries a reason rather than an empty list, because "we could not
+ * work this out" and "this principal holds nothing" must not render the same way: the
+ * first is a fault the reader should see, and collapsing it into an empty set is how a
+ * denial gets invented. See {@link resolveActions}.
+ */
+export interface ResolvedActions {
+    /** Actions held, in display order. Empty when `known` is false. */
+    actions: string[];
+    /**
+     * Whether the full set could be determined.
+     *
+     * False when part of the input could not be read -- an inheritance path that was
+     * unavailable, or a grant whose action is a word this build does not know.
+     */
+    known: boolean;
+    /** Why the set is incomplete, when it is. Shown to the reader beside the actions. */
+    reason?: string;
+}
+/**
+ * Union a principal's grants into the permission set it actually holds.
+ *
+ * UNION, never intersection and never "the first row": a principal reaches a resource
+ * through several grants (a direct one and one inherited from each role), and what
+ * they may do is everything any of those grants allows. Reading one row is what made
+ * an administrator display as read-only.
+ *
+ * An unrecognised action word makes the whole answer unknown rather than being
+ * skipped. Skipping it would under-report, and under-reporting a permission is the
+ * direction that misleads an operator into thinking access is safe to ignore.
+ *
+ * @param actions - every action string from every grant reaching this principal.
+ * @returns The unioned set, or an explicit unknown with the reason.
+ */
+export declare function resolveActions(actions: readonly string[]): ResolvedActions;
+/**
+ * Whether a resolved set confers the ability to change a document.
+ *
+ * Used by the page to check itself against what the reader can actually do. `manage`
+ * implies write in this model: it is the full-control level, and a principal holding
+ * it can move and delete.
+ * @param resolved - the unioned permission set.
+ * @returns true when writing is possible, or unknown.
+ */
+export declare function canWriteWith(resolved: ResolvedActions): boolean | undefined;
 /**
  * Collapse a set of action strings into the shortest describing list.
  *
- * Mirrors the server's collapse rule without importing it: this file is bundled
- * for the browser and must not pull the server module in. Keeping the rule in
- * two places is a real cost, so it is stated once here and covered by the same
- * expectations as the server's own test.
+ * A thin view over {@link resolveActions} so there is ONE vocabulary and ONE union
+ * rule in the browser: this used to be a second implementation filtering on
+ * `create`/`update`/`delete`, which silently dropped every `write` and `manage` grant.
  *
+ * Kept as an exported name because the older callers and their tests use it.
  * @param actions - raw action strings from grants.
- * @returns `['all']` when everything is held, else the concrete subset in order.
+ * @returns The unioned actions in display order; unknown words are dropped here,
+ *   which is why a surface that must not under-report calls {@link resolveActions}.
  */
 export declare function summarizeActions(actions: readonly string[]): string[];
 /**
@@ -92,3 +140,126 @@ export declare function groupHoldingsByResource(grants: readonly GrantView[], la
  * @returns The formatted instant, or a dash when there is nothing to show.
  */
 export declare function formatGrantInstant(value: string): string;
+/**
+ * One DataOps account as the user directory reports it, reduced to what grouping needs.
+ *
+ * `roles` is what makes inheritance visible: a role grant names the ROLE, so without
+ * the membership list the page can only show role grants as belonging to nobody. The
+ * directory is the only source for it, and it is administrator-only -- see
+ * {@link DirectoryState}.
+ */
+export interface DirectoryUser {
+    /** DataOps user id, which is what a `user` grant names. */
+    userId: string;
+    /** Login name, shown beside the display name so two "张伟" can be told apart. */
+    username: string;
+    /** Display name, when the account has one. */
+    displayName: string;
+    /** Role codes this account belongs to. */
+    roleCodes: string[];
+}
+/**
+ * Whether the user directory could be read.
+ *
+ * Three states, not two. "Nobody holds a role" and "we could not look" produce the same
+ * empty membership map, and rendering them the same way is how a page ends up telling
+ * an operator that nobody has inherited access when the truth is that the read failed.
+ */
+export type DirectoryState = {
+    kind: 'available';
+    users: readonly DirectoryUser[];
+} | {
+    kind: 'unavailable';
+    reason: string;
+};
+/** One account's holdings, as the by-person view renders them. */
+export interface AccountHoldings {
+    /** The account id. */
+    userId: string;
+    /** Login name, for disambiguating identical display names. */
+    username?: string;
+    /** Display name, or the id when the account is not in the directory. */
+    label: string;
+    /** Distinct paths this account reaches, directly or through a role. */
+    paths: string[];
+    /** The unioned permission set, never narrowed by a single grant. */
+    resolved: ResolvedActions;
+    /** Direct grants the account holds itself. */
+    directGrants: GrantView[];
+    /**
+     * Role codes the account inherits through.
+     *
+     * Empty when the directory could not be read; {@link inheritanceKnown} says which.
+     */
+    viaRoles: string[];
+    /** Whether the inheritance half of this row was actually determined. */
+    inheritanceKnown: boolean;
+    /** Why inheritance is unknown, when it is. */
+    inheritanceReason?: string;
+    /** Most recent grant instant across the rows this account covers. */
+    latestAt: string;
+}
+/** One role's holdings, as the by-role view renders them. */
+export interface RoleHoldings {
+    /** Role code, which is what a `role` grant names. */
+    roleCode: string;
+    /** Role display name when the directory resolved one, else the code. */
+    label: string;
+    /** Distinct paths the role covers. */
+    paths: string[];
+    /** The unioned permission set for this role. */
+    resolved: ResolvedActions;
+    /** Grants that name this role. */
+    grants: GrantView[];
+    /** How many directory accounts belong to this role, when the directory is known. */
+    memberCount?: number;
+    /** Most recent grant instant across this role's rows. */
+    latestAt: string;
+}
+/**
+ * Group grants by the DataOps ACCOUNT that holds them.
+ *
+ * The account is the row grain because "who can see this" is a question about people.
+ * A role grant confers access on every member of that role, so its paths are attributed
+ * to each member here -- otherwise a reader whose access is entirely role-derived would
+ * appear on no row at all, and the page would say "nobody has access" to somebody who
+ * can write.
+ *
+ * Three sources are merged, and the merge is a UNION:
+ * 1. direct `user` grants;
+ * 2. grants held by any role the account belongs to (inherited);
+ * 3. nothing else -- the built-in administrator levels are already rows in the grant
+ *    table (`source: 'seed'`), so hard-coding them here would create a second authority
+ *    that could disagree with the backend.
+ *
+ * @param grants - the whole grant table.
+ * @param directory - the user directory, or the reason it could not be read.
+ * @param labels - display names by `principalType:principalId`, optional.
+ * @returns One row per account that holds or inherits at least one grant, sorted by label.
+ */
+export declare function groupHoldingsByAccount(grants: readonly GrantView[], directory: DirectoryState, labels?: Readonly<Record<string, string>>): AccountHoldings[];
+/**
+ * Group grants by the ROLE they name.
+ *
+ * The same grants the old "by person" table showed, now labelled as what they are: a
+ * role is not a person, and putting it under "by person" told the reader that the
+ * administrators were the only people with access.
+ *
+ * A role whose grants are all unreadable still gets a row with `known: false`: that is
+ * the safety net against rendering "no permission" for a read failure.
+ *
+ * @param grants - the whole grant table.
+ * @param labels - display names by `principalType:principalId`, optional.
+ * @param memberCounts - role code -> member count, when the directory is known.
+ * @returns One row per role named by at least one grant, sorted by label.
+ */
+export declare function groupHoldingsByRole(grants: readonly GrantView[], labels?: Readonly<Record<string, string>>, memberCounts?: ReadonlyMap<string, number>): RoleHoldings[];
+/**
+ * Build the role -> member-count map from a directory.
+ *
+ * Only meaningful when the directory is known; returns undefined otherwise so the row
+ * omits the count rather than claiming zero members.
+ * @param directory - the user directory state.
+ * @returns Counts by role code, or undefined when unavailable.
+ */
+export declare function roleMemberCounts(directory: DirectoryState): Map<string, number> | undefined;

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

@@ -0,0 +1,54 @@
+/**
+ * The progress strip's two decisions, kept out of the component.
+ *
+ * Both are answers about data rather than about React: whether a batch is finished, and
+ * whether a retry button would help. They live here because a `.tsx` module that imports
+ * the UI primitives cannot be loaded by the test runner (the primitives package imports
+ * CSS at module scope, which the runner cannot resolve), so a test that imported the
+ * component would fail before reaching any assertion.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/**
+ * Whether the strip may fold now.
+ *
+ * Folded means "one summary line instead of a list". It folds when every task in both
+ * groups reached a terminal state AND the batch has not been folded before -- the
+ * second half is what stops it re-folding after a reader expanded a finished batch to
+ * read which file failed.
+ * @param uploads - the current batch's rows.
+ * @param extractions - the extraction tasks the Host reports.
+ * @param alreadyFolded - whether a fold already happened for this batch.
+ * @returns Whether to fold.
+ */
+export declare function shouldFoldStrip(uploads: readonly {
+    state: string;
+}[], extractions: readonly {
+    state: string;
+}[], alreadyFolded: boolean): boolean;
+/**
+ * Whether a retry button would help for this state.
+ *
+ * Only a failure is worth retrying. `unsupported` means no extractor exists for the
+ * type, so a retry fails identically and the button would be a lie; the pending and
+ * running states are already being handled.
+ * @param state - the extraction state.
+ * @returns Whether to offer a retry.
+ */
+export declare function canRetryExtraction(state: string): boolean;
+/**
+ * A failure reason that survives a response which is not JSON.
+ *
+ * A gateway answering 502 sends HTML, and `response.json()` rejects on it. If that
+ * rejection escaped, the row would report "failed" with no reason at all -- which is
+ * exactly the silence this strip exists to remove. So the body is attempted, and an
+ * unreadable body falls back to the status code, which still tells the reader whether
+ * the server refused them (4xx) or broke (5xx).
+ * @param body - the parsed body, when it parsed.
+ * @param status - the HTTP status.
+ * @returns A sentence a reader can act on.
+ */
+export declare function failureReason(body: {
+    error?: unknown;
+    code?: unknown;
+} | undefined, status: number): string;

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

@@ -0,0 +1,60 @@
+/**
+ * Pure helpers for the reference picker and the batch menu.
+ *
+ * Kept out of the components because the parts worth testing are the decisions, not the
+ * rendering: how a selection becomes a target list, what the batch label says, and which
+ * entries a paste loop should attempt. The components are wired to these, so a change in
+ * behaviour here is what the tests below pin down; the real DOM interaction is covered by
+ * the browser walkthrough instead.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** One entry a reference will be inserted for, in absolute path form. */
+export interface ReferenceTarget {
+    /** Absolute path as the tree and the routes speak it. */
+    path: string;
+    /** True for a directory (folder mention) rather than a document (file chip). */
+    isDir: boolean;
+}
+/** One row a batch action covers. */
+export interface BatchRow {
+    /** Path relative to the knowledge root. */
+    relPath: string;
+    /** Display name, for menu copy. */
+    name: string;
+    /** Whether the row is a directory. */
+    isDir: boolean;
+}
+/**
+ * The entries a picker opened on `relPath` should insert.
+ *
+ * A multi-row selection wins when it contains the clicked row, because that is the set
+ * the reader could see highlighted. Otherwise the click is a single-row action on the row
+ * under the pointer -- which is also what happens when the clicked row sits outside the
+ * selection, since acting on a batch the reader did not point at would be a surprise.
+ * @param relPath - the row the `@` button was pressed on.
+ * @param selection - the rows the explorer reports as selected, if any.
+ * @returns One target, or every selected row when the click was inside the selection.
+ */
+export declare function referenceTargetsFor(relPath: string, selection?: readonly BatchRow[]): ReferenceTarget[];
+/**
+ * The rows a menu opened on one row should act on.
+ *
+ * Mirrors {@link referenceTargetsFor}: a right-click inside a multi-selection acts on the
+ * whole selection, and anywhere else acts on the one row. The menu and the picker must
+ * agree, or a "delete 3 items" dialog would reference four.
+ * @param target - the row under the pointer.
+ * @param selection - the rows marked selected, if any.
+ * @returns The rows the batch entries cover, or an empty list for a single-row menu.
+ */
+export declare function batchRowsFor(target: BatchRow, selection?: readonly BatchRow[]): BatchRow[];
+/**
+ * Fill a batch label's `{n}` placeholder.
+ *
+ * A separate function so the count is formatted in one place: a label that prints the
+ * rows it will touch must never print a different number from the rows it does touch.
+ * @param template - the locale string, containing `{n}`.
+ * @param count - how many rows.
+ * @returns The label with the count substituted.
+ */
+export declare function batchLabel(template: string, count: number): string;