@termix-ssh/plugin-sdk 1.0.0 → 1.0.1

package/dist/host/types/src/ui/components/list-kit.d.ts

@@ -0,0 +1,102 @@
+import type React from "react";
+export type ListRowTone = "brand" | "muted" | "success" | "warning" | "destructive" | "none";
+/** Scrolling list body. Rows sit flush, divided by their own borders. */
+export declare function PanelList({ empty, className, children, }: {
+    /** Shown instead of the rows when there are none. */
+    empty?: React.ReactNode;
+    className?: string;
+    children?: React.ReactNode;
+}): React.JSX.Element;
+/**
+ * One row in a sidebar list, drawn like the host list: a coloured stripe on
+ * the left, a name with an optional line under it, and a row of action
+ * buttons that opens under it on hover.
+ */
+export declare function ListRow({ title, icon, badges, meta, stripe, tone, color, selected, active, dimmed, leading, trailing, actions, onClick, className, children, ...rest }: {
+    title: React.ReactNode;
+    icon?: React.ReactNode;
+    /** Small chips after the title. */
+    badges?: React.ReactNode;
+    /** Muted line under the title, like a description or Facts. */
+    meta?: React.ReactNode;
+    /** Position in the list, odd rows get the zebra tint. */
+    stripe?: number;
+    tone?: ListRowTone;
+    /** A custom stripe colour, like a group's own colour. */
+    color?: string;
+    selected?: boolean;
+    /** Keeps the tray open, like while its menu is showing. */
+    active?: boolean;
+    dimmed?: boolean;
+    /** Sits between the stripe and the text, like a drag handle. */
+    leading?: React.ReactNode;
+    /** Always visible on the right, like a switch. */
+    trailing?: React.ReactNode;
+    /** Buttons under the row that open on hover, like the host list. */
+    actions?: React.ReactNode;
+    onClick?: () => void;
+    className?: string;
+    /** Extra lines under the meta. */
+    children?: React.ReactNode;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "title" | "onClick" | "children">): React.JSX.Element;
+/** Square icon button for a ListRow tray. */
+export declare function ListRowAction({ label, tone, className, children, ...rest }: {
+    label: string;
+    tone?: "default" | "brand" | "destructive";
+    className?: string;
+    children: React.ReactNode;
+} & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
+    ref?: React.Ref<HTMLButtonElement>;
+}): React.JSX.Element;
+/** Small uppercase chip for a ListRow's badges. */
+export declare function ListBadge({ tone, className, children, }: {
+    tone?: "muted" | "brand" | "warning" | "destructive" | "success";
+    className?: string;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** A collapsible group in a ListRow list, drawn like a host folder. */
+export declare function ListRowFolder({ name, icon, count, open, onToggle, stripe, actions, dropActive, onDropItem, emptyText, className, children, }: {
+    name: React.ReactNode;
+    icon?: React.ReactNode;
+    count?: number;
+    open: boolean;
+    onToggle: () => void;
+    stripe?: number;
+    /** Shown on hover, usually a DropdownMenu trigger. */
+    actions?: React.ReactNode;
+    /** True while something is being dragged that could drop in here. */
+    dropActive?: boolean;
+    onDropItem?: () => void;
+    emptyText?: React.ReactNode;
+    className?: string;
+    children?: React.ReactNode;
+}): React.JSX.Element;
+/** The one "add" button, placed beside a panel's search box. */
+export declare function AddButton({ label, compact, className, ...rest }: {
+    label?: string;
+    /** Icon only, for tight toolbars. */
+    compact?: boolean;
+    className?: string;
+} & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
+    ref?: React.Ref<HTMLButtonElement>;
+}): React.JSX.Element;
+/** The one Save bar, for a PanelShell or InlineView footer. */
+export declare function FormFooter({ onCancel, onSave, saveLabel, cancelLabel, saving, dirty, status, disabled, onDelete, deleteLabel, extra, saveType, form, }: {
+    onCancel?: () => void;
+    onSave?: () => void;
+    saveLabel?: string;
+    cancelLabel?: string;
+    saving?: boolean;
+    /** Shows the unsaved changes note. */
+    dirty?: boolean;
+    /** Replaces the unsaved note, like an error count. */
+    status?: React.ReactNode;
+    disabled?: boolean;
+    onDelete?: () => void;
+    deleteLabel?: string;
+    /** More buttons, placed before Save. */
+    extra?: React.ReactNode;
+    saveType?: "button" | "submit";
+    /** Id of the form a submit Save belongs to. */
+    form?: string;
+}): React.JSX.Element;

package/dist/host/types/src/ui/components/panel-layout.d.ts

@@ -37,13 +37,18 @@ export declare function BackButton({ onClick, label, className, }: {
     className?: string;
 }): React.JSX.Element;
 /** Search box sized to match toolbar buttons. Esc clears it. */
-export declare function PanelSearch({ value, onChange, placeholder, fill, autoFocus, className, }: {
+export declare function PanelSearch({ value, onChange, placeholder, fill, autoFocus, disabled, title, onEnter, inputRef, className, }: {
     value: string;
     onChange: (next: string) => void;
     placeholder?: string;
     /** Takes the whole toolbar, for panels where search is the only control. */
     fill?: boolean;
     autoFocus?: boolean;
+    disabled?: boolean;
+    title?: string;
+    /** Runs on Enter, for searches that query a server. */
+    onEnter?: () => void;
+    inputRef?: React.Ref<HTMLInputElement>;
     className?: string;
 }): React.JSX.Element;
 /** Square segmented control. */

package/dist/host/types/src/ui/components/surface/surface-scope.d.ts

@@ -13,8 +13,10 @@ export interface ConfirmOptions {
     /** Red confirm button. Defaults to true, since most confirms delete. */
     destructive?: boolean;
 }
-export declare function SurfaceScope({ kind, onEditingChange, className, children, }: {
+export declare function SurfaceScope({ kind, onEditingChange, onClose, className, children, }: {
     kind?: SurfaceKind;
+    /** Closes whatever this surface is, like the tab it fills. */
+    onClose?: () => void;
     /** Gets the widest open inline view, so a sidebar can widen for it. */
     onEditingChange?: (editing: EditingWidth) => void;
     className?: string;
@@ -22,6 +24,8 @@ export declare function SurfaceScope({ kind, onEditingChange, className, childre
 }): React.JSX.Element;
 /** Which kind of surface this code renders in, or null outside any. */
 export declare function useSurfaceKind(): SurfaceKind | null;
+/** Closes the surface this code renders in, or null when it can't be closed. */
+export declare function useSurfaceClose(): (() => void) | null;
 /**
  * Asks a yes or no question over the surface that called it. Enter confirms
  * and Esc cancels, before a terminal can see the key.

package/dist/host/types/src/ui/contexts/UiPreferencesContext.d.ts

@@ -8,7 +8,18 @@ interface UiPreferencesContextValue {
     setOverride: <A extends UiAreaKey, K extends keyof UiAreaPreferences[A]>(area: A, key: K, value: UiAreaPreferences[A][K] | null) => void;
     clearArea: (area: UiAreaKey) => void;
     clearAllOverrides: () => void;
-    completeOnboarding: (skipped: boolean) => void;
+    /**
+     * Records onboarding steps as seen (per-step max, never lowered).
+     * `completed` stamps completedAt the first time a run finishes, and
+     * `baselineDone` clears the carried-over-user flag.
+     */
+    markOnboardingSeen: (seen: Record<string, number>, options?: {
+        completed?: boolean;
+        skipped?: boolean;
+        baselineDone?: boolean;
+    }) => void;
+    /** Sends any queued change now instead of after the debounce. */
+    flushNow: () => Promise<void>;
     /** A plugin's own area, from the presets it declared. */
     resolvePlugin: (pluginId: string, presets: UiPluginPresets | undefined) => Record<string, unknown>;
     setPluginOverride: (pluginId: string, key: string, value: unknown) => void;
@@ -23,8 +34,10 @@ interface UiPreferencesContextValue {
  * deep and treats null as "clear this", so handing a knob back to the preset is
  * a single PUT rather than a read-modify-write of the whole document.
  */
-export declare function UiPreferencesProvider({ children }: {
+export declare function UiPreferencesProvider({ children, initial, }: {
     children: ReactNode;
+    /** Already fetched (by the onboarding gate), so no second request. */
+    initial?: UiPreferences | null;
 }): import("react").JSX.Element;
 export declare function useUiPreferencesContext(): UiPreferencesContextValue | null;
 /**

package/dist/host/types/src/ui/hooks/use-permissions.d.ts

@@ -7,6 +7,8 @@ export interface PermissionsState {
 }
 /** The same answer usePermissions().has gives, for code outside a component. */
 export declare function hasPermission(permission: string): Promise<boolean>;
+/** A sync has() over the current grants, for code outside a component. */
+export declare function loadPermissionChecker(): Promise<(permission: string) => boolean>;
 /**
  * Warms the permissions cache before the shell mounts, so permission-gated
  * rail items are already known on first paint instead of popping in once

package/dist/host/types/src/ui/lib/embedded-frame.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The two places this web UI runs only to sign someone in for another app:
+ * the Termix mobile app's WebView, and the iframe a desktop app shows a
+ * server's login in while linking. Neither should ever show onboarding.
+ */
+export interface EmbeddedFrameWindow extends Window {
+    IS_ELECTRON_WEBVIEW?: boolean;
+    ReactNativeWebView?: {
+        postMessage: (msg: string) => void;
+    };
+}
+export declare function isInMobileWebView(): boolean;
+export declare function isInElectronWebView(): boolean;
+export declare function isEmbeddedAuthFrame(): boolean;

package/dist/host/types/src/ui/onboarding/onboarding-registry.d.ts

@@ -0,0 +1,49 @@
+import type { ComponentType } from "react";
+import type { LucideIcon } from "lucide-react";
+import type { OnboardingMode, OnboardingSection, OnboardingStepProps } from "@termix-ssh/plugin-sdk/frontend";
+import type { SlotContribution } from "../shell/action-registry";
+export type { OnboardingMode, OnboardingSection, OnboardingStepProps };
+export interface OnboardingCtx {
+    mode: OnboardingMode;
+    isAdmin: boolean;
+    isDesktop: boolean;
+    has: (permission: string) => boolean;
+    /** True on a fresh install until an admin confirms the plugin picker. */
+    pluginSetupPending: boolean;
+    /** A linked desktop runs what its server runs. */
+    pluginsManagedElsewhere: boolean;
+    /** Whether a sign in plugin offers a passkey or authenticator to set up. */
+    canEnrollSecondFactor?: boolean;
+}
+export interface OnboardingStepDef {
+    /** The key stored in the seen map: a core id, or `<pluginId>:<id>`. */
+    id: string;
+    pluginId?: string;
+    version: number;
+    titleKey: string;
+    descriptionKey?: string;
+    icon?: LucideIcon | ComponentType<{
+        size?: number;
+        className?: string;
+    }>;
+    Component: ComponentType<OnboardingStepProps>;
+    audience: "all" | "admin";
+    permission?: string;
+    /** Position in the flow; plugin steps get theirs from their section. */
+    position: number;
+    isRelevant?: (ctx: OnboardingCtx) => boolean;
+    /** Shown in a partial run even when already seen. */
+    forcePending?: (ctx: OnboardingCtx) => boolean;
+    /** Skip stays hidden until this step has been confirmed. */
+    required?: boolean;
+}
+/** Where each section of plugin steps sits among the core steps. */
+export declare const SECTION_POSITION: Record<OnboardingSection, number>;
+export declare const onboardingSteps: import("../lib/registry").Registry<OnboardingStepDef>;
+/** Plugin steps sort inside their section by order, then key. */
+export declare function sectionPosition(section: OnboardingSection | undefined, order?: number): number;
+export declare function sortSteps(steps: OnboardingStepDef[]): OnboardingStepDef[];
+/** Steps still on the deprecated onboarding.steps slot, read as version 1. */
+export declare function legacyStepDefs(contributions: SlotContribution[]): OnboardingStepDef[];
+/** Core, registered and legacy steps in flow order, registered winning ties. */
+export declare function mergeStepDefs(core: OnboardingStepDef[], registered: OnboardingStepDef[], legacy: OnboardingStepDef[]): OnboardingStepDef[];

package/dist/host/types/src/ui/plugin-host/sdk-ui.d.ts

@@ -87,6 +87,7 @@ export { getAdaptiveResourceBudget, markAdaptiveResourceUsed, runAdaptiveBackgro
 export { getDeviceId } from "../lib/device-id";
 export { createQuickConnectHost } from "../sidebar/quick-connect-host";
 export { BackButton, Facts, GroupHeading, PANEL, PanelSearch, PanelShell, Segmented, ViewToggle, type PanelDensity, type PanelViewMode, } from "../components/panel-layout";
+export { AddButton, FormFooter, ListBadge, ListRow, ListRowAction, ListRowFolder, PanelList, type ListRowTone, } from "../components/list-kit";
 export { DataView, type DataColumn, type GridColumns, } from "../components/data-view";
 export { TabStrip, type TabStripItem } from "../components/tab-strip";
 export { CardMasonry } from "../components/card-masonry";

package/dist/host/types/src/ui/plugins/open-plugins.d.ts

@@ -0,0 +1,5 @@
+/** Asks the shell to open the Plugins tab. */
+export declare const OPEN_PLUGINS_EVENT = "termix:open-plugins";
+/** Asks the shell to open Settings at a plugin's page; detail is the plugin id. */
+export declare const OPEN_PLUGIN_SETTINGS_EVENT = "termix:open-plugin-settings";
+export declare function openPluginSettings(pluginId: string): void;

package/dist/host/types/src/ui/sidebar/host-contributions.d.ts

@@ -56,6 +56,8 @@ export interface HostContextMenuItemDef {
 }
 export declare const registerHostAction: (item: HostActionDef) => () => void;
 export declare const useHostActions: () => HostActionDef[];
+/** Plugin actions sort by order; connect actions default to the end. */
+export declare function actionOrder(action: HostActionDef): number;
 export declare const listHostActions: () => HostActionDef[];
 export declare const registerHostBadge: (item: HostBadgeDef) => () => void;
 export declare const useHostBadges: () => HostBadgeDef[];

package/dist/host/types/src/ui/sidebar/rail-items.d.ts

@@ -87,6 +87,16 @@ export declare function permittedRailItems(items: RailItemDef[], permissions: {
  * the items the user's permissions hide.
  */
 export declare function useRailItems(): RailItemDef[];
+/**
+ * Items in the user's order. Listed ids come first in that order within the
+ * default sequence; unlisted ones keep their default place relative to it.
+ */
+export declare function applyRailOrder(items: RailItemDef[], order: string[] | undefined): RailItemDef[];
+/**
+ * The order after moving `id` to sit before `beforeId` (or to the end of its
+ * band when null), as a full list of the given items' ids.
+ */
+export declare function moveRailItem(items: RailItemDef[], id: string, beforeId: string | null): string[];
 /** Places outside the rail that still need a title, like the Settings tab. */
 export declare const RAIL_UTILITY_ITEMS: RailItemDef[];
 /** Ids that may be opened in the right dock. */