@termix-ssh/plugin-sdk 1.0.0 → 1.0.1

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-XGWE7BTJ.js → chunk-3KG44G55.js}

@@ -21,7 +21,7 @@ var inFlight = null;
 function load() {
   if (cache) return Promise.resolve(cache);
   if (inFlight) return inFlight;
-  inFlight = import("./rbac-api-6KDMBVDZ.js").then(({ getMyPermissions }) => getMyPermissions()).then((result) => {
+  inFlight = import("./rbac-api-7GHDJLU4.js").then(({ getMyPermissions }) => getMyPermissions()).then((result) => {
     cache = {
       permissions: result.permissions ?? [],
       isAdmin: !!result.isAdmin
@@ -39,6 +39,10 @@ async function hasPermission(permission) {
   const { permissions, isAdmin } = await load();
   return matchesPermission(permissions, isAdmin, permission);
 }
+async function loadPermissionChecker() {
+  const { permissions, isAdmin } = await load();
+  return (permission) => matchesPermission(permissions, isAdmin, permission);
+}
 function preloadPermissions() {
   return load().then(() => void 0);
 }
@@ -82,6 +86,7 @@ function setPermissionsForTesting(permissions, isAdmin = false) {
 
 export {
   hasPermission,
+  loadPermissionChecker,
   preloadPermissions,
   notifyPermissionsChanged,
   usePermissions,