@achasoft/dsh-advanced-sidebar 0.1.0

package/types/client/controller.d.ts

@@ -0,0 +1,224 @@
+/**
+ * The one piece of state shared by this plugin's four slot registrations.
+ *
+ * The menu trigger, the dock, and the confirmation dialog are separate slot entries with no common
+ * React ancestor, so the panel a person opened cannot live in a component. It lives here, in
+ * a `HostObservable` the registrations hand down through their inject faces' reserved `hooks`
+ * compartment; the renderer binds each source into a `use<Name>` selector hook, so a component
+ * re-renders for the slice it selected and nothing else.
+ * @module @achasoft/dsh-advanced-sidebar/client/controller
+ */
+import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots';
+/** Which panel is showing in the dock. */
+export type PanelKind = 'changes' | 'terminal' | 'files' | 'tasks' | 'preview';
+/** The session an operation acts on, resolved once at the moment the menu is opened. */
+export interface OperationTarget {
+    /** Session the operation acts on. */
+    readonly sessionId: string;
+    /** Human label for dialogs and the dock header. */
+    readonly title: string;
+    /**
+     * Absolute Host directory the panels work in: the session's own cwd, or its workspace path when
+     * the session has none. Absent leaves every Host-backed entry disabled, because there is nothing
+     * for git, a terminal, or a file listing to be relative to.
+     */
+    readonly directory: string | undefined;
+}
+/** The open panel, if any. */
+export interface PanelState {
+    /** Which panel is showing; undefined while the dock is closed. */
+    readonly panel: PanelKind | undefined;
+    /** What the panel acts on. */
+    readonly target: OperationTarget | undefined;
+}
+/** One shell the Terminal panel holds open. */
+export interface TerminalTab {
+    /** Identifies the tab for its whole life, including while its shell is still being allocated. */
+    readonly tabId: string;
+    /** The Host handle; absent while the allocation is in flight or after it failed. */
+    readonly terminalId: string | undefined;
+    /** Which shell answered. */
+    readonly shell: string | undefined;
+    /** Why the allocation failed. */
+    readonly error: string | undefined;
+}
+/** Every shell one target's Terminal panel holds, and which of them is showing. */
+export interface TerminalGroup {
+    /** The tabs, in the order they were opened. */
+    readonly tabs: readonly TerminalTab[];
+    /** The tab whose screen is showing; absent only while the group is empty. */
+    readonly activeId: string | undefined;
+}
+/** A pending Delete waiting for confirmation. */
+export interface ConfirmState {
+    /** What Delete would act on. */
+    readonly target: OperationTarget;
+    /** What the Host says Delete would actually do, so the dialog cannot promise a removal twice. */
+    readonly purges: boolean;
+    /** True while the request is in flight; the dialog's buttons are disabled. */
+    readonly busy: boolean;
+}
+/** A short-lived message shown under the dock, for outcomes that have no surface of their own. */
+export interface NoticeState {
+    /** Monotonic id, so an identical repeated message still restarts the dismissal timer. */
+    readonly id: number;
+    /** Whether the message reports a failure. */
+    readonly tone: 'info' | 'error';
+    /** The message. */
+    readonly text: string;
+}
+/** Everything the surfaces read. */
+export interface SidebarState {
+    /** The open panel. */
+    readonly panel: PanelState;
+    /** The pending Delete confirmation. */
+    readonly confirm: ConfirmState | undefined;
+    /** The current notice. */
+    readonly notice: NoticeState | undefined;
+    /**
+     * The dock's width in pixels after a resize, which outranks the settings value for this browser
+     * session. Undefined leaves the settings section in charge.
+     */
+    readonly dockWidth: number | undefined;
+    /**
+     * Terminal groups by {@link terminalKey}. Held here rather than in the panel so a shell survives
+     * switching to another panel or closing the dock, exactly as a terminal in an editor does; the
+     * Host retains its scrollback, so a reopened tab replays rather than restarts.
+     */
+    readonly terminals: Readonly<Record<string, TerminalGroup>>;
+}
+/**
+ * The key one target's terminal group is held under.
+ *
+ * The directory is part of it: a session whose working directory changed is a different place to
+ * have a shell in, and reusing the group would leave a tab labelled with a path its shell is not in.
+ * @param target - the session and directory the panel acts on.
+ * @returns the group key.
+ */
+export declare function terminalKey(target: OperationTarget): string;
+/**
+ * Holds the plugin's cross-registration state and notifies its subscribers.
+ *
+ * It is a plain observable rather than a cordis service: nothing outside this package reads it, and
+ * a service key would be a public name for something private to four registrations.
+ */
+export declare class PanelController implements HostObservable<SidebarState> {
+    private state;
+    private readonly listeners;
+    private nextNoticeId;
+    /**
+     * Current state.
+     * @returns the snapshot; identity changes only when something actually moved.
+     */
+    getSnapshot(): SidebarState;
+    /**
+     * Subscribe to state changes.
+     * @param listener - called after every commit.
+     * @returns the unsubscribe.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Show one panel in the dock. Choosing the panel that is already open on the same session closes
+     * the dock, which is what makes the menu entry read as a toggle.
+     * @param panel - which panel.
+     * @param target - what it acts on.
+     */
+    open(panel: PanelKind, target: OperationTarget): void;
+    /** Close the dock. */
+    close(): void;
+    /**
+     * Ask for confirmation before Delete commits.
+     * @param target - what Delete would act on.
+     * @param purges - whether the Host would also remove the durable log.
+     */
+    askDelete(target: OperationTarget, purges: boolean): void;
+    /** Mark the pending Delete as in flight. */
+    markDeleting(): void;
+    /** Dismiss the Delete confirmation without acting. */
+    dismissDelete(): void;
+    /**
+     * Show one message.
+     * @param tone - whether the message reports a failure.
+     * @param text - the message.
+     */
+    notify(tone: NoticeState['tone'], text: string): void;
+    /**
+     * Dismiss one message, ignoring a request for a message that has already been replaced.
+     * @param id - the notice to dismiss.
+     */
+    dismissNotice(id: number): void;
+    /**
+     * Withdraw everything a session owned, because that session is gone.
+     * @param sessionId - the session that disappeared.
+     */
+    forget(sessionId: string): void;
+    /**
+     * Store the dock width a resize settled on.
+     *
+     * Kept here as well as written to the settings section: the section is read-only on every remote
+     * Web Client, and a drag that cannot be persisted must still resize the dock.
+     * @param width - the width in pixels.
+     */
+    setDockWidth(width: number): void;
+    /**
+     * The terminal group one target holds.
+     * @param key - the group key from {@link terminalKey}.
+     * @returns the group; the empty group when nothing has been opened yet.
+     */
+    terminals(key: string): TerminalGroup;
+    /**
+     * Add one tab, in the state a tab has before its shell has been allocated, and show it.
+     * @param key - the group key.
+     * @param tabId - the caller-generated tab id, so the caller can allocate against it immediately.
+     */
+    addTerminal(key: string, tabId: string): void;
+    /**
+     * Record what a tab's allocation answered.
+     * @param key - the group key.
+     * @param tabId - the tab the allocation was for.
+     * @param outcome - the handle and the shell, or the failure.
+     */
+    settleTerminal(key: string, tabId: string, outcome: {
+        terminalId: string;
+        shell: string;
+    } | {
+        error: string;
+    }): void;
+    /**
+     * Show one tab's screen.
+     * @param key - the group key.
+     * @param tabId - the tab to show.
+     */
+    activateTerminal(key: string, tabId: string): void;
+    /**
+     * Drop one tab and show its neighbour.
+     * @param key - the group key.
+     * @param tabId - the tab to drop.
+     * @returns the Host handle the caller must now close, when the tab had one.
+     */
+    removeTerminal(key: string, tabId: string): string | undefined;
+    /**
+     * Drop every terminal one session owns, whatever directory it had them in.
+     * @param sessionId - the session.
+     * @returns the Host handles the caller must now close.
+     */
+    dropTerminals(sessionId: string): readonly string[];
+    /**
+     * Every open handle, for the teardown that must close them.
+     * @returns the Host handles this browser half still holds.
+     */
+    allTerminals(): readonly string[];
+    /** Close everything. Called from the plugin's teardown effect. */
+    reset(): void;
+    /**
+     * Replace one target's terminal group.
+     * @param key - the group key.
+     * @param group - the group after the change; an empty one is dropped rather than stored.
+     */
+    private putTerminals;
+    /**
+     * Store one state and notify.
+     * @param next - the committed state.
+     */
+    private commit;
+}

package/types/client/cx.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Class-name joining.
+ *
+ * `clsx` is what the harness's own components use, but it is not a module-table specifier, so an
+ * out-of-tree browser half would have to bundle a private copy of it into every plugin. Three lines
+ * cover everything this package needs.
+ * @module @achasoft/dsh-advanced-sidebar/client/cx
+ */
+/** One class-name argument: a name, or a falsy value to skip. */
+export type ClassValue = string | false | null | undefined;
+/**
+ * Join class names, dropping the falsy ones.
+ * @param values - names and conditional names.
+ * @returns the joined class attribute, empty when nothing applied.
+ */
+export declare function cx(...values: readonly ClassValue[]): string;

package/types/client/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Advanced sidebar plugin, browser half: three registrations over one Host endpoint and one shared
+ * piece of state.
+ *
+ * - `conversation.session.header.utilities` — the menu on the open session.
+ * - `shell.overlay` — the resizable dock holding whichever panel is open, plus the Delete
+ *   confirmation.
+ * - `settings.plugin.item` — the card on the plugin-configuration tab, keyed by the namespace.
+ *
+ * There was a fourth, at the sidebar foot; it was withdrawn, so the column has no action of this
+ * plugin's in it and the menu acts only on the session it sits in.
+ *
+ * The seats have no common React ancestor, so what a person opened lives in a {@link PanelController}
+ * this module owns and hands to each registration through its inject face. Archiving and directory
+ * navigation go through the Web Client's own `ctx.workspaces`; everything a browser structurally
+ * cannot do goes through this plugin's own Remote namespace.
+ * @module @achasoft/dsh-advanced-sidebar/client
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+export type { AdvancedSidebarKey } from './locales.ts';
+export type { HeaderMenuProps, MenuInjected, PanelHostInjected, PanelHostProps, SettingsCardInjected, SettingsCardProps, Translate, } from './contract.ts';
+export type { OperationTarget, PanelKind, SidebarState, TerminalGroup, TerminalTab, } from './controller.ts';
+/**
+ * Required services of the OUTER plugin: locale and the Remote mount point.
+ *
+ * Deliberately NOT `remote.advancedSidebar`. This plugin's apply creates that namespace by mounting
+ * its own contribution, so it cannot also wait for it — and Cordis refuses to read a service the
+ * fiber did not inject. Both halves of that bind are resolved by the child plugin below, which
+ * injects `remote.advancedSidebar` after the parent has provided it.
+ */
+export declare const inject: string[];
+/**
+ * Client plugin body: mount this plugin's Remote namespace, register the dictionaries, then hand
+ * the surface to a child fiber that can inject the namespace its parent just provided.
+ * @param ctx - client root context.
+ * @returns after the `advancedSidebar` namespace is callable; its methods are withdrawn when this
+ * fiber unloads.
+ */
+export declare function apply(ctx: ClientContext): Promise<void>;