@termix-ssh/plugin-sdk 1.0.0 → 1.0.2

package/dist/frontend.d.ts

@@ -636,7 +636,11 @@ export interface ActionSlotDefinition {
 export interface SlotContribution {
     actionId: string;
     titleKey: string;
-    /** Secondary text, for slots that show one (onboarding cards). */
+    /**
+     * Secondary text, for slots that show one. The onboarding.* slots that
+     * used it are deprecated: use registerOnboardingStep. The feature and
+     * workflow card slots are no longer shown.
+     */
     descriptionKey?: string;
     icon?: IconComponent;
     kind?: "button" | "component" | string;
@@ -646,6 +650,61 @@ export interface SlotContribution {
     when?: (context: Record<string, unknown>) => boolean;
     order?: number;
 }
+export type OnboardingMode = "full" | "partial" | "rerun";
+/**
+ * Where a plugin step sits in onboarding. "setup" comes right after the
+ * appearance steps, for things that need doing before the feature works
+ * (like pointing at a guacd server). "explore" (the default) comes after
+ * that, "security" after the account security step. Onboarding is for
+ * choices, not for explaining features.
+ */
+export type OnboardingSection = "setup" | "explore" | "security";
+export interface OnboardingStepProps {
+    /**
+     * "full" is a new user's first run, "partial" shows only steps they have
+     * not seen yet (a plugin installed later, a step whose version went up),
+     * "rerun" is the user running setup again from settings.
+     */
+    mode: OnboardingMode;
+    isAdmin: boolean;
+    isDesktop: boolean;
+    /** Blocks or allows Next. Steps can continue by default. */
+    setCanContinue: (ok: boolean) => void;
+    /**
+     * Runs when Next is pressed, before moving on. Return false to stay on the
+     * step (to show an error, say). Pass null to clear it.
+     */
+    setBeforeNext: (fn: (() => boolean | Promise<boolean>) | null) => void;
+    /**
+     * False on a first run, which shows before the app shell exists: app.tabs
+     * and the shell callbacks do nothing until it is true.
+     */
+    shellReady: boolean;
+}
+export interface OnboardingStepContribution {
+    /** Unique within the plugin. Lowercase letters, digits and dashes. */
+    id: string;
+    /**
+     * Starts at 1. Raise it when the step changes enough that people who saw
+     * it should see it again; they get just this step, not all of onboarding.
+     */
+    version?: number;
+    titleKey: string;
+    descriptionKey?: string;
+    icon?: IconComponent;
+    component: ComponentType<OnboardingStepProps>;
+    /** "admin" shows it only to users who can manage plugins. */
+    audience?: "all" | "admin";
+    /** A permission the user must hold, like registerAction's. */
+    permission?: string;
+    section?: OnboardingSection;
+    order?: number;
+    when?: (context: {
+        isAdmin: boolean;
+        isDesktop: boolean;
+        mode: OnboardingMode;
+    }) => boolean;
+}
 export interface SshAuthEditorProps {
     form: Record<string, unknown>;
     setField: (key: string, value: unknown) => void;
@@ -800,6 +859,13 @@ export interface TermixApp extends TermixAppInfo {
     }) => Disposer;
     declareActionSlot: (slot: ActionSlotDefinition) => Disposer;
     registerSlotContribution: (slotId: string, contribution: SlotContribution) => Disposer;
+    /**
+     * Adds a step to onboarding. New users see it in their first run; people
+     * who already finished onboarding see just this step the next time they
+     * open Termix (or right away, if they install the plugin mid-session).
+     * Needs plugin API 1.1.
+     */
+    registerOnboardingStep: (step: OnboardingStepContribution) => Disposer;
     invokeAction: (id: string, ...args: unknown[]) => Promise<unknown>;
     /**
      * Offers a component to other plugins and to core by id, rendered where

package/dist/host/{chunk-F3SDZDDG.js → chunk-LKYAVM4T.js}

@@ -4759,6 +4759,18 @@ async function buildOriginWsUrl({
   };
 }
 
+// src/types/onboarding.ts
+var LEGACY_SEEN = Object.freeze({
+  plugins: 1,
+  "desktop-sync": 1,
+  preset: 1,
+  appearance: 1,
+  security: 1
+});
+function pluginStepKey(pluginId, id) {
+  return `${pluginId}:${id}`;
+}
+
 // src/types/ui-preferences.ts
 var SIMPLE_RAIL_VISIBLE = ["hosts", "credentials", "connections"];
 var CORE_HIDEABLE_RAIL_VIEWS = [
@@ -4870,6 +4882,7 @@ var AREA_SPECS = {
   },
   rail: {
     hiddenTabs: { kind: "stringArray" },
+    order: { kind: "stringArray" },
     hidePluginItems: { kind: "bool" }
   },
   dashboard: {
@@ -5024,7 +5037,7 @@ async function updateRole(roleId, roleData) {
   try {
     const response = await rbacApi.put(`/rbac/roles/${roleId}`, roleData);
     if (roleData.permissions) {
-      const { notifyPermissionsChanged } = await import("./use-permissions-NULZL43J.js");
+      const { notifyPermissionsChanged } = await import("./use-permissions-5CZEA3P4.js");
       notifyPermissionsChanged();
     }
     return response.data;
@@ -5574,7 +5587,7 @@ function createRemoteOriginApiInstance(path) {
   });
   instance.interceptors.request.use(
     async (config) => {
-      const { getLinkedSession: getLinkedSession2 } = await import("./linked-server-FZGWQW32.js");
+      const { getLinkedSession: getLinkedSession2 } = await import("./linked-server-DW5P3NLZ.js");
       const linked = await getLinkedSession2();
       config.baseURL = linked ? `${linked.serverUrl}${path}` : "http://no-server-configured";
       if (config.headers.set) {
@@ -5926,6 +5939,7 @@ function notifySyncChanged() {
 }
 
 export {
+  getPluginStoreState,
   usePluginStore,
   setPluginSummaries,
   markPluginsSettled,
@@ -5957,6 +5971,7 @@ export {
   notifySyncChanged,
   resolveConnectionOrigin,
   buildOriginWsUrl,
+  pluginStepKey,
   PRESETS,
   hydrateLocalSharedHostAuth,
   resolveRemoteHostId,