@kispace-io/extension-howto-system 0.8.0

package/src/howto-contribution.ts

@@ -0,0 +1,98 @@
+import { Contribution } from '@kispace-io/core';
+
+/**
+ * HowTo Contribution System
+ * 
+ * Allows extensions to register step-by-step workflows that guide users
+ * through specific processes with pre and post condition checks.
+ */
+
+/**
+ * Condition function that checks if a requirement is met or outcome is achieved.
+ * Returns a promise that resolves to true if the condition is satisfied.
+ */
+export type ConditionFunction = () => Promise<boolean> | boolean;
+
+/**
+ * A single step in a HowTo workflow
+ */
+export interface HowToStep {
+    /** Unique identifier for this step */
+    id: string;
+    
+    /** Human-readable title of the step */
+    title: string;
+    
+    /** Detailed description of what the user should do in this step */
+    description: string;
+    
+    /** 
+     * Pre-condition check: verifies that requirements are met before this step can be executed.
+     * If this returns false, the step cannot be started.
+     */
+    preCondition?: ConditionFunction;
+    
+    /** 
+     * Post-condition check: verifies that the step was completed successfully.
+     * If this returns false, the step is not considered complete.
+     */
+    postCondition?: ConditionFunction;
+    
+    /** Optional command to execute when the step is activated */
+    command?: string;
+    
+    /** Optional command parameters */
+    commandParams?: Record<string, any>;
+    
+    /** Whether this step is optional */
+    optional?: boolean;
+}
+
+/**
+ * Context provided to HowTo initialization function
+ */
+export interface HowToContext {
+    /** Callback to notify the panel that conditions should be re-checked */
+    requestUpdate: () => void;
+    
+    /** The contribution ID of this HowTo */
+    contributionId: string;
+}
+
+/**
+ * Initialization function for a HowTo
+ * Allows the HowTo to set up its own subscriptions and manage its lifecycle
+ */
+export type HowToInitializeFunction = (context: HowToContext) => (() => void) | void;
+
+/**
+ * A HowTo Contribution defines a complete workflow with multiple steps.
+ * Extends Contribution to work with the contribution registry.
+ */
+export interface HowToContribution extends Contribution {
+    /** Unique identifier for this HowTo */
+    id: string;
+    
+    /** Human-readable title of the workflow (can be a function for dynamic values) */
+    title: string | (() => string);
+    
+    /** Description of what this workflow helps accomplish (can be a function for dynamic values) */
+    description?: string | (() => string);
+    
+    /** Icon identifier (FontAwesome or custom icon) */
+    icon?: string;
+    
+    /** List of steps in the workflow */
+    steps: HowToStep[];
+    
+    /** Optional category for grouping related workflows */
+    category?: string;
+    
+    /** 
+     * Optional initialization function that runs when the HowTo is started.
+     * Can set up subscriptions, listeners, etc.
+     * Should return a cleanup function (optional) that will be called when the HowTo is closed.
+     */
+    initialize?: HowToInitializeFunction;
+}
+

package/src/howto-extension.ts

@@ -0,0 +1,107 @@
+import { createLogger } from '@kispace-io/core';
+import { rootContext } from '@kispace-io/core';
+import { howToService } from './howto-service';
+import { HOWTO_CONTRIBUTION_TARGET } from './howto-service';
+import './contributions/onboarding-howto-contributions';
+import './contributions/ai-setup-howto-contributions';
+import { TOPIC_SHOW_HOWTO_PANEL, TOPIC_TOGGLE_HOWTO_PANEL } from './k-howto-panel';
+import { registerAll } from '@kispace-io/core';
+import { publish } from '@kispace-io/core';
+import { TOOLBAR_BOTTOM_END } from '@kispace-io/core';
+import './k-howto-panel';
+
+const logger = createLogger('HowToExtension');
+
+/**
+ * HowTo System Extension
+ * 
+ * Provides a system for registering and displaying step-by-step workflows
+ * that guide users through specific processes with pre and post condition checks.
+ * 
+ * Features:
+ * - Register HowToContributions via contribution registry
+ * - Floating, draggable UI panel
+ * - Sequential step execution
+ * - Pre and post condition validation
+ * - Step status tracking
+ */
+export default function howToExtension(context: any) {
+    logger.info('HowTo system extension loaded');
+
+    // Register the HowTo service in the dependency injection context
+    rootContext.put('howToService', howToService);
+
+    // Ensure the panel is added to the DOM
+    const ensurePanelInDOM = () => {
+        // Check if panel already exists
+        if (document.querySelector('k-howto-panel')) {
+            return;
+        }
+
+        // Create and append the panel
+        const panel = document.createElement('k-howto-panel');
+        document.body.appendChild(panel);
+        logger.info('HowTo panel added to DOM');
+    };
+
+    // Add panel to DOM - use requestAnimationFrame to ensure DOM is ready
+    if (document.body) {
+        requestAnimationFrame(() => {
+            ensurePanelInDOM();
+        });
+    } else {
+        // Wait for DOM to be ready
+        const checkDOM = () => {
+            if (document.body) {
+                ensurePanelInDOM();
+            } else {
+                requestAnimationFrame(checkDOM);
+            }
+        };
+        requestAnimationFrame(checkDOM);
+    }
+
+    // Register command to show/toggle the HowTo panel
+    registerAll({
+        command: {
+            id: 'howto.show-panel',
+            name: 'Show HowTo Panel',
+            description: 'Shows the HowTo workflows panel',
+            icon: 'list-check',
+            parameters: []
+        },
+        handler: {
+            execute: () => {
+                publish(TOPIC_SHOW_HOWTO_PANEL, null);
+            }
+        }
+    });
+
+    registerAll({
+        command: {
+            id: 'howto.toggle-panel',
+            name: 'Toggle HowTo Panel',
+            description: 'Toggles the visibility of the HowTo workflows panel',
+            icon: 'list-check',
+            keyBinding: 'CTRL+SHIFT+H',
+            parameters: []
+        },
+        handler: {
+            execute: () => {
+                publish(TOPIC_TOGGLE_HOWTO_PANEL, null);
+            }
+        },
+        contribution: {
+            target: TOOLBAR_BOTTOM_END,
+            icon: 'list-check',
+            label: 'HowTo',
+        }
+    });
+
+    logger.info('HowTo system extension initialized');
+}
+
+// Export the service and types for direct imports
+export { howToService, HOWTO_CONTRIBUTION_TARGET } from './howto-service';
+export type { HowToContribution, HowToStep, ConditionFunction } from './howto-contribution';
+

package/src/howto-service.ts

@@ -0,0 +1,123 @@
+import { contributionRegistry, TOPIC_CONTRIBUTEIONS_CHANGED } from '@kispace-io/core';
+import { HowToContribution, HowToStep } from './howto-contribution';
+import { subscribe } from '@kispace-io/core';
+import { createLogger } from '@kispace-io/core';
+import { Signal } from '@lit-labs/signals';
+
+const logger = createLogger('HowToService');
+
+export const HOWTO_CONTRIBUTION_TARGET = 'system.howtos';
+
+/**
+ * HowTo Service
+ * 
+ * Manages HowTo contributions by reading from the contribution registry.
+ * Provides methods to retrieve and manage workflows.
+ */
+export class HowToService {
+    private contributions: Map<string, HowToContribution> = new Map();
+
+    constructor() {
+        // Load initial contributions
+        this.loadContributions();
+
+        // Subscribe to contribution changes
+        subscribe(TOPIC_CONTRIBUTEIONS_CHANGED, (event: any) => {
+            if (event.target === HOWTO_CONTRIBUTION_TARGET) {
+                this.loadContributions();
+            }
+        });
+    }
+
+    /**
+     * Load contributions from the contribution registry
+     */
+    private loadContributions(): void {
+        const contributions = contributionRegistry.getContributions(HOWTO_CONTRIBUTION_TARGET) as HowToContribution[];
+        
+        this.contributions.clear();
+        
+        for (const contribution of contributions) {
+            // Validate contribution
+            if (!contribution.id) {
+                logger.warn('HowTo contribution missing id, skipping');
+                continue;
+            }
+
+            if (!contribution.label) {
+                // Use title as label if label is not provided
+                // Handle both string and function types
+                const title = typeof contribution.title === 'function' 
+                    ? contribution.title() 
+                    : contribution.title;
+                contribution.label = title;
+            }
+
+            if (!contribution.steps || contribution.steps.length === 0) {
+                logger.warn(`HowTo contribution "${contribution.id}" has no steps, skipping`);
+                continue;
+            }
+
+            // Validate step IDs are unique
+            const stepIds = new Set<string>();
+            for (const step of contribution.steps) {
+                if (stepIds.has(step.id)) {
+                    logger.warn(`HowTo contribution "${contribution.id}" has duplicate step ID: "${step.id}"`);
+                    continue;
+                }
+                stepIds.add(step.id);
+            }
+
+            this.contributions.set(contribution.id, contribution);
+            const title = typeof contribution.title === 'function' 
+                ? contribution.title() 
+                : contribution.title;
+            logger.debug(`Loaded HowTo contribution: ${title} (${contribution.id})`);
+        }
+
+        logger.info(`Loaded ${this.contributions.size} HowTo contributions`);
+    }
+
+    /**
+     * Get a HowTo Contribution by ID
+     * 
+     * @param contributionId The ID of the contribution
+     * @returns The contribution or undefined if not found
+     */
+    getContribution(contributionId: string): HowToContribution | undefined {
+        return this.contributions.get(contributionId);
+    }
+
+    /**
+     * Get all registered HowTo Contributions
+     * 
+     * @returns Array of all contributions
+     */
+    getAllContributions(): HowToContribution[] {
+        return Array.from(this.contributions.values());
+    }
+
+    /**
+     * Get HowTo Contributions by category
+     * 
+     * @param category The category to filter by
+     * @returns Array of contributions in the category
+     */
+    getContributionsByCategory(category: string): HowToContribution[] {
+        return Array.from(this.contributions.values())
+            .filter(contrib => contrib.category === category);
+    }
+
+    /**
+     * Check if a contribution exists
+     * 
+     * @param contributionId The ID of the contribution
+     * @returns True if the contribution exists
+     */
+    hasContribution(contributionId: string): boolean {
+        return this.contributions.has(contributionId);
+    }
+}
+
+export const howToService = new HowToService();
+

package/src/i18n.json

@@ -0,0 +1,11 @@
+{
+  "namespace": "extensions",
+  "en": {
+    "EXT_HOWTO_NAME": "HowTo System",
+    "EXT_HOWTO_DESC": "Step-by-step workflow system with pre and post condition checks"
+  },
+  "de": {
+    "EXT_HOWTO_NAME": "HowTo-System",
+    "EXT_HOWTO_DESC": "Schritt-für-Schritt-Workflow-System mit Vor- und Nachbedingungsprüfungen"
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+import { extensionRegistry, i18nLazy, contributionRegistry, SYSTEM_LANGUAGE_BUNDLES } from '@kispace-io/core';
+import bundle from './i18n.json';
+
+contributionRegistry.registerContribution(SYSTEM_LANGUAGE_BUNDLES, bundle as any);
+
+const t = i18nLazy('extensions');
+
+extensionRegistry.registerExtension({
+  id: "system.howto",
+  name: t('EXT_HOWTO_NAME'),
+  description: t('EXT_HOWTO_DESC'),
+  loader: () => import("./howto-extension"),
+  icon: "list-check",
+  
+  
+});