dsh-over-ssh 0.1.0 → 0.2.0

package/lib/types/src/client/file-tree.d.ts

@@ -1,271 +0,0 @@
-/**
- * The remote file tree (FR-2.2.1 / FR-2.2.2).
- *
- * Why this is a pure module plus a thin view: the interesting behaviour is not the markup, it is **which
- * level is loaded, what is expanded, what the last failure was, and what a mutation invalidates**. That is a
- * state machine, and a state machine that lives inside a component cannot be tested in this repository (the
- * view tests call the section functions directly, outside a React render — see `controls.ts`).
- *
- * Three rules it inherits from the rest of the client half:
- *
- *  - **Every call is injected** (红线 3): the tests drive the tree with a scripted IO and no server.
- *  - **Nothing is assumed about the wire**: rows are narrowed field by field, and an unknown kind is a file.
- *  - **A mutation refreshes what it invalidated** rather than guessing: after a rename or a delete the parent
- *    directory is re-listed from the host, because a locally patched tree is a second source of truth that
- *    drifts the first time the user has another window open.
- *
- * @module dsh-remote-workspace/client/file-tree
- */
-import { type ReactNode } from 'react';
-import type { ApiResult } from './roots-panel.ts';
-/** One row of a remote directory, as this tree renders it. */
-export interface RemoteFileRow {
-    readonly name: string;
-    readonly kind: 'directory' | 'file' | 'symlink';
-}
-/** One loaded directory level. */
-export interface RemoteFileLevel {
-    /** Absolute path the host actually listed (it resolves an empty request to the login user's home). */
-    readonly path: string;
-    readonly entries: readonly RemoteFileRow[];
-    /** True when the host cut the listing at its own bound. */
-    readonly truncated: boolean;
-}
-/** Where the tree is rooted. */
-export interface FileTreeRoot {
-    readonly connectionId: string;
-    readonly path: string;
-}
-/** What the tree asks the host for. Injected, so tests run with no server. */
-export interface FileTreeIo {
-    list(input: {
-        readonly connectionId: string;
-        readonly path: string;
-    }): Promise<ApiResult<RemoteFileLevel>>;
-    mkdir(input: {
-        readonly connectionId: string;
-        readonly path: string;
-        readonly recursive: boolean;
-    }): Promise<ApiResult<unknown>>;
-    rename(input: {
-        readonly connectionId: string;
-        readonly from: string;
-        readonly to: string;
-        readonly createParents: boolean;
-    }): Promise<ApiResult<unknown>>;
-    remove(input: {
-        readonly connectionId: string;
-        readonly path: string;
-        readonly recursive: boolean;
-    }): Promise<ApiResult<unknown>>;
-}
-/** A mutation the tree can ask for; `undefined` means nothing is being edited. */
-export type FileTreeDraft = {
-    readonly kind: 'new-directory';
-    readonly parent: string;
-    readonly name: string;
-} | {
-    readonly kind: 'new-file';
-    readonly parent: string;
-    readonly name: string;
-} | {
-    readonly kind: 'rename';
-    readonly path: string;
-    readonly name: string;
-} | {
-    readonly kind: 'remove';
-    readonly path: string;
-    readonly recursive: boolean;
-};
-/** Everything the tree renders from. */
-export interface FileTreeState {
-    readonly root: FileTreeRoot;
-    /** Loaded levels, keyed by absolute path. */
-    readonly levels: ReadonlyMap<string, RemoteFileLevel>;
-    /** Paths whose children are shown. */
-    readonly expanded: ReadonlySet<string>;
-    /** Levels with a request in flight. */
-    readonly loading: ReadonlySet<string>;
-    /** Per-level failures, keyed by the level that failed. */
-    readonly errors: ReadonlyMap<string, string>;
-    /** The open mutation form, if any. */
-    readonly draft?: FileTreeDraft;
-    /** The last mutation failure, shown above the tree. */
-    readonly actionError?: string;
-    /** True while a mutation is in flight. */
-    readonly busy: boolean;
-}
-/** Start a tree at a root; nothing is loaded yet. */
-export declare function initialFileTreeState(root: FileTreeRoot): FileTreeState;
-/** Load a level (the root, or a directory the user opened). */
-export declare function fileTreeLoading(state: FileTreeState, path: string): FileTreeState;
-/** A level arrived. */
-export declare function fileTreeLoaded(state: FileTreeState, path: string, level: RemoteFileLevel): FileTreeState;
-/** A level failed; the message is kept **per level**, so one unreadable directory does not blank the tree. */
-export declare function fileTreeFailed(state: FileTreeState, path: string, error: string): FileTreeState;
-/** Open or close a directory. */
-export declare function fileTreeToggled(state: FileTreeState, path: string): FileTreeState;
-/** Open a mutation form. */
-export declare function fileTreeDraftOpened(state: FileTreeState, draft: FileTreeDraft): FileTreeState;
-/** Change the name being typed in an open form. */
-export declare function fileTreeDraftRenamed(state: FileTreeState, name: string): FileTreeState;
-/** Close the form without doing anything. */
-export declare function fileTreeDraftClosed(state: FileTreeState): FileTreeState;
-/** A mutation started. */
-export declare function fileTreeBusy(state: FileTreeState): FileTreeState;
-/**
- * A mutation succeeded.
- *
- * The form closes and the affected levels are **dropped**, so the next render re-lists them from the host.
- * Dropping rather than patching is deliberate: a locally edited tree would be a second source of truth.
- */
-export declare function fileTreeSettled(state: FileTreeState, invalidated: readonly string[]): FileTreeState;
-/** A mutation failed. */
-export declare function fileTreeActionFailed(state: FileTreeState, error: string): FileTreeState;
-/**
- * Narrow one `list-remote` answer.
- *
- * Same discipline as `parseRootsSnapshot`: an unknown kind is treated as a **file** rather than dropped, and a
- * row with no usable name is dropped. A directory the host reports as something this build does not know would
- * otherwise be silently missing from the tree.
- *
- * @param value - the parsed body.
- * @param requested - the path that was asked for, used when the answer names none.
- * @returns a level safe to render.
- */
-export declare function parseRemoteFileLevel(value: unknown, requested: string): RemoteFileLevel;
-/** Join a POSIX child onto a POSIX parent, without doubling or dropping the separator. */
-export declare function remoteJoin(parent: string, name: string): string;
-/** The parent of a POSIX path, or `undefined` at the root (so a caller cannot walk above it). */
-export declare function remoteParent(path: string): string | undefined;
-/**
- * The name a user typed, or the reason it cannot be used.
- *
- * Refused here rather than at the host because these are *shape* rules the tree can check for free: an empty
- * name, a name with a slash (which would silently mean "create a subdirectory"), `.`/`..`, and a leading `-`
- * (which some POSIX tools read as an option).
- *
- * @param name - the typed name.
- * @returns the trimmed name, or the reason.
- */
-export declare function validateRemoteName(name: string): {
-    readonly ok: true;
-    readonly value: string;
-} | {
-    readonly ok: false;
-    readonly reason: 'empty' | 'slash' | 'dot' | 'dash';
-};
-/**
- * The levels a mutation invalidates.
- *
- * Exported because it is the one piece of this module a reviewer should be able to check by reading: creating
- * or deleting `p` changes `p`'s **parent**, and renaming changes the parents of both ends.
- *
- * @param draft - the mutation.
- * @returns the absolute paths whose listings are now stale.
- */
-export declare function invalidatedBy(draft: FileTreeDraft): readonly string[];
-/** The rows of one level, directories first then files, each group by name. */
-export declare function sortRows(rows: readonly RemoteFileRow[]): readonly RemoteFileRow[];
-/** The stateful half. */
-export interface FileTreeController {
-    readonly getState: () => FileTreeState;
-    readonly subscribe: (listener: () => void) => () => void;
-    /** Load the root if it has not been loaded. */
-    readonly start: () => void;
-    /** Re-list one level from the host. */
-    readonly refresh: (path: string) => Promise<void>;
-    /** Open or close a directory, loading it the first time. */
-    readonly toggle: (path: string) => Promise<void>;
-    /** Ask to create something inside a directory. */
-    readonly askNewDirectory: (parent: string) => void;
-    readonly askRename: (path: string) => void;
-    readonly askRemove: (path: string) => void;
-    /** Change the name in the open form. */
-    readonly changeName: (name: string) => void;
-    /** Close the open form. */
-    readonly cancel: () => void;
-    /** Commit the open form. */
-    readonly submit: () => Promise<void>;
-    readonly dispose: () => void;
-}
-/**
- * Build the tree's controller.
- *
- * @param options - the injected IO and the root to show.
- * @returns the controller a container subscribes to.
- */
-export declare function createFileTree(options: {
-    readonly io: FileTreeIo;
-    readonly root: FileTreeRoot;
-}): FileTreeController;
-/** The strings the tree renders; passed in so the view needs no dictionary import. */
-export interface FileTreeCopy {
-    readonly title: string;
-    readonly empty: string;
-    readonly loading: string;
-    readonly truncated: string;
-    readonly newDirectory: string;
-    readonly rename: string;
-    readonly remove: string;
-    readonly refresh: string;
-    readonly confirmRemove: string;
-    readonly confirmRemoveTree: string;
-    readonly accept: string;
-    readonly cancel: string;
-    readonly nameLabel: string;
-    readonly directoryBadge: string;
-    readonly symlinkBadge: string;
-    readonly errorEmptyName: string;
-    readonly errorNameSlash: string;
-    readonly errorNameDot: string;
-    readonly errorNameDash: string;
-}
-/** What the view's controls call. */
-export interface FileTreeActions {
-    readonly onToggle: (path: string) => void;
-    readonly onRefresh: (path: string) => void;
-    readonly onNewDirectory: (parent: string) => void;
-    readonly onRename: (path: string) => void;
-    readonly onRemove: (path: string) => void;
-    readonly onNameChange: (name: string) => void;
-    readonly onCancel: () => void;
-    readonly onSubmit: () => void;
-}
-/** One rendered row. */
-export interface FileTreeRow {
-    readonly path: string;
-    readonly name: string;
-    readonly depth: number;
-    readonly isDirectory: boolean;
-    readonly isSymlink: boolean;
-    readonly expanded: boolean;
-    readonly loading: boolean;
-    readonly error?: string;
-}
-/**
- * Flatten the loaded levels into the rows to render.
- *
- * Depth-first, directories before files at each level, and a directory's children are only walked when it is
- * expanded. A level that is loading but has no cached entries still produces its row (with `loading`), which
- * is what makes the spinner appear where the user clicked rather than at the top of the tree.
- *
- * @param state - the tree state.
- * @returns the rows, in display order.
- */
-export declare function fileTreeRows(state: FileTreeState): readonly FileTreeRow[];
-/**
- * The tree's markup.
- *
- * A flat `<ul>` of rows with an indent per depth, because the platform ships no Tree primitive and a nested
- * list would make the row controls (rename/delete on hover) reach into parents. Depth is presentation.
- *
- * @param props - state, copy and callbacks.
- * @returns the tree section.
- */
-export declare function FileTreeSection(props: {
-    readonly copy: FileTreeCopy;
-    readonly state: FileTreeState;
-    readonly actions: FileTreeActions;
-}): ReactNode;
-//# sourceMappingURL=file-tree.d.ts.map