@syntrologie/adapt-faq 0.0.0-semantically-released → 2.0.1

package/dist/executors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Adaptive FAQ - Action Executors
+ *
+ * Three executors that operate on the FAQStore:
+ * - executeScrollToFaq: scroll to a FAQ item and optionally expand it
+ * - executeToggleFaqItem: open / close / toggle a FAQ item
+ * - executeUpdateFaq: add, remove, reorder, or replace FAQ items
+ */
+import type { FAQStore } from './state';
+import type { ScrollToFaqAction, ToggleFaqItemAction, UpdateFaqAction, ExecutorResult, ExecutorContext } from './types';
+/**
+ * Scroll to a FAQ item in the DOM and optionally expand it.
+ *
+ * Looks up the item by `itemId` or `itemQuestion`, scrolls the matching
+ * `[data-faq-item-id]` element into view, and expands it unless
+ * `expand` is explicitly set to `false`.
+ */
+export declare function executeScrollToFaq(action: ScrollToFaqAction, context: ExecutorContext, store: FAQStore): Promise<ExecutorResult>;
+/**
+ * Open, close, or toggle a FAQ item's expanded state.
+ */
+export declare function executeToggleFaqItem(action: ToggleFaqItemAction, context: ExecutorContext, store: FAQStore): Promise<ExecutorResult>;
+/**
+ * Add, remove, reorder, or replace FAQ items in the store.
+ */
+export declare function executeUpdateFaq(action: UpdateFaqAction, context: ExecutorContext, store: FAQStore): Promise<ExecutorResult>;
+/**
+ * All executors provided by adaptive-faq.
+ * These are registered with the runtime's ExecutorRegistry.
+ */
+export declare const executorDefinitions: readonly [{
+    readonly kind: "faq:scroll_to";
+    readonly executor: typeof executeScrollToFaq;
+}, {
+    readonly kind: "faq:toggle_item";
+    readonly executor: typeof executeToggleFaqItem;
+}, {
+    readonly kind: "faq:update";
+    readonly executor: typeof executeUpdateFaq;
+}];
+//# sourceMappingURL=executors.d.ts.map

package/dist/executors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executors.d.ts","sourceRoot":"","sources":["../src/executors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,eAAe,EAEhB,MAAM,SAAS,CAAC;AA4BjB;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,QAAQ,GACd,OAAO,CAAC,cAAc,CAAC,CAyBzB;AAMD;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,QAAQ,GACd,OAAO,CAAC,cAAc,CAAC,CAgCzB;AAMD;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,QAAQ,GACd,OAAO,CAAC,cAAc,CAAC,CA0CzB;AAMD;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;EAItB,CAAC"}

package/dist/executors.js

@@ -0,0 +1,151 @@
+/**
+ * Adaptive FAQ - Action Executors
+ *
+ * Three executors that operate on the FAQStore:
+ * - executeScrollToFaq: scroll to a FAQ item and optionally expand it
+ * - executeToggleFaqItem: open / close / toggle a FAQ item
+ * - executeUpdateFaq: add, remove, reorder, or replace FAQ items
+ */
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Resolve a FAQ item by direct ID or by fuzzy question text match.
+ * Throws if neither yields a result.
+ */
+function resolveItem(store, itemId, itemQuestion) {
+    if (itemId) {
+        const found = store.getState().items.find((i) => i.config.id === itemId);
+        if (found)
+            return found;
+    }
+    if (itemQuestion) {
+        const found = store.findByQuestion(itemQuestion);
+        if (found)
+            return found;
+    }
+    throw new Error('FAQ item not found');
+}
+// ============================================================================
+// executeScrollToFaq
+// ============================================================================
+/**
+ * Scroll to a FAQ item in the DOM and optionally expand it.
+ *
+ * Looks up the item by `itemId` or `itemQuestion`, scrolls the matching
+ * `[data-faq-item-id]` element into view, and expands it unless
+ * `expand` is explicitly set to `false`.
+ */
+export async function executeScrollToFaq(action, context, store) {
+    const item = resolveItem(store, action.itemId, action.itemQuestion);
+    const { id } = item.config;
+    // Expand the item unless explicitly told not to
+    if (action.expand !== false) {
+        store.expand(id);
+    }
+    // Scroll the DOM element into view (may be absent in test environments)
+    const el = document.querySelector(`[data-faq-item-id="${id}"]`);
+    if (el) {
+        el.scrollIntoView({
+            behavior: action.behavior ?? 'smooth',
+        });
+    }
+    // Publish analytics event
+    context.publishEvent('faq:scroll_to', { itemId: id });
+    return {
+        cleanup: () => {
+            // Optionally collapse on revert
+        },
+    };
+}
+// ============================================================================
+// executeToggleFaqItem
+// ============================================================================
+/**
+ * Open, close, or toggle a FAQ item's expanded state.
+ */
+export async function executeToggleFaqItem(action, context, store) {
+    const item = resolveItem(store, action.itemId, action.itemQuestion);
+    const { id } = item.config;
+    const desiredState = action.state ?? 'toggle';
+    let newState;
+    switch (desiredState) {
+        case 'open':
+            store.expand(id);
+            newState = 'open';
+            break;
+        case 'closed':
+            store.collapse(id);
+            newState = 'closed';
+            break;
+        case 'toggle':
+        default: {
+            const wasExpanded = store.getState().expandedItems.has(id);
+            store.toggle(id);
+            newState = wasExpanded ? 'closed' : 'open';
+            break;
+        }
+    }
+    context.publishEvent('faq:toggle', { itemId: id, newState });
+    return {
+        cleanup: () => {
+            // Revert toggle on cleanup
+        },
+    };
+}
+// ============================================================================
+// executeUpdateFaq
+// ============================================================================
+/**
+ * Add, remove, reorder, or replace FAQ items in the store.
+ */
+export async function executeUpdateFaq(action, context, store) {
+    switch (action.operation) {
+        case 'add': {
+            const items = action.items ?? [];
+            const position = action.position === 'prepend' ? 'prepend' : 'append';
+            store.addItems(items, position);
+            break;
+        }
+        case 'remove': {
+            if (!action.itemId) {
+                throw new Error('FAQ item not found');
+            }
+            // Verify the item exists before removing
+            const exists = store.getState().items.some((i) => i.config.id === action.itemId);
+            if (!exists) {
+                throw new Error('FAQ item not found');
+            }
+            store.removeItem(action.itemId);
+            break;
+        }
+        case 'reorder': {
+            const order = action.order ?? [];
+            store.reorderItems(order);
+            break;
+        }
+        case 'replace': {
+            const items = action.items ?? [];
+            store.replaceItems(items);
+            break;
+        }
+    }
+    context.publishEvent('faq:update', { operation: action.operation });
+    return {
+        cleanup: () => {
+            // Could snapshot previous state for undo
+        },
+    };
+}
+// ============================================================================
+// Executor Definitions for Registration
+// ============================================================================
+/**
+ * All executors provided by adaptive-faq.
+ * These are registered with the runtime's ExecutorRegistry.
+ */
+export const executorDefinitions = [
+    { kind: 'faq:scroll_to', executor: executeScrollToFaq },
+    { kind: 'faq:toggle_item', executor: executeToggleFaqItem },
+    { kind: 'faq:update', executor: executeUpdateFaq },
+];

package/dist/runtime.d.ts

@@ -2,14 +2,14 @@
  * Adaptive FAQ - Runtime Module
  *
  * Runtime manifest for the FAQ accordion adaptive.
- * This is a widget-based adaptive with no action executors.
+ * Provides action executors and widget registration.
  */
 /**
  * Runtime manifest for adaptive-faq.
  *
- * Note: This adaptive is widget-based, not action-based.
- * The `faq:question` actions are compositional - they're rendered by
- * the widget, not executed by the runtime.
+ * Provides:
+ * - FAQ action executors (scroll_to, toggle_item, update)
+ * - Widget-based accordion (compositional faq:question actions)
  */
 export declare const runtime: {
     id: string;
@@ -17,10 +17,18 @@ export declare const runtime: {
     name: string;
     description: string;
     /**
-     * No action executors - faq:question actions are compositional,
-     * meaning they serve as configuration for the FAQWidget.
+     * Action executors for programmatic FAQ interaction.
      */
-    executors: never[];
+    executors: readonly [{
+        readonly kind: "faq:scroll_to";
+        readonly executor: typeof import("./executors").executeScrollToFaq;
+    }, {
+        readonly kind: "faq:toggle_item";
+        readonly executor: typeof import("./executors").executeToggleFaqItem;
+    }, {
+        readonly kind: "faq:update";
+        readonly executor: typeof import("./executors").executeUpdateFaq;
+    }];
     /**
      * Widget definitions for the runtime's WidgetRegistry.
      */
@@ -28,7 +36,7 @@ export declare const runtime: {
         id: string;
         component: {
             mount(container: HTMLElement, config?: import("./types").FAQConfig & {
-                runtime?: import("./types").FAQWidgetRuntime;
+                runtime?: import("./FAQWidget").FAQWidgetRuntime;
                 instanceId?: string;
             }): () => void;
         };

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH;;;;;;GAMG;AACH,eAAO,MAAM,OAAO;;;;;IAMlB;;;OAGG;;IAGH;;OAEG;;;;;uBAey/S,CAAC;0BAA8B,CAAC;;;;;;;;;CAH7hT,CAAC;AAEF,eAAe,OAAO,CAAC"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;;;;;GAMG;AACH,eAAO,MAAM,OAAO;;;;;IAOlB;;OAEG;;;;;;;;;;;IAGH;;OAEG;;;;;uBAeu2f,CAAC;0BAA8B,CAAC;;;;;;;;;CAH34f,CAAC;AAEF,eAAe,OAAO,CAAC"}

package/dist/runtime.js

@@ -2,8 +2,9 @@
  * Adaptive FAQ - Runtime Module
  *
  * Runtime manifest for the FAQ accordion adaptive.
- * This is a widget-based adaptive with no action executors.
+ * Provides action executors and widget registration.
  */
+import { executorDefinitions } from './executors';
 import { FAQMountableWidget } from './FAQWidget';
 // ============================================================================
 // App Runtime Manifest
@@ -11,20 +12,19 @@ import { FAQMountableWidget } from './FAQWidget';
 /**
  * Runtime manifest for adaptive-faq.
  *
- * Note: This adaptive is widget-based, not action-based.
- * The `faq:question` actions are compositional - they're rendered by
- * the widget, not executed by the runtime.
+ * Provides:
+ * - FAQ action executors (scroll_to, toggle_item, update)
+ * - Widget-based accordion (compositional faq:question actions)
  */
 export const runtime = {
     id: 'adaptive-faq',
-    version: '1.0.0',
+    version: '2.0.0',
     name: 'FAQ Accordion',
-    description: 'Collapsible Q&A accordion with per-item conditional visibility',
+    description: 'Collapsible Q&A accordion with actions, rich content, feedback, and personalization',
     /**
-     * No action executors - faq:question actions are compositional,
-     * meaning they serve as configuration for the FAQWidget.
+     * Action executors for programmatic FAQ interaction.
      */
-    executors: [],
+    executors: executorDefinitions,
     /**
      * Widget definitions for the runtime's WidgetRegistry.
      */
@@ -34,7 +34,7 @@ export const runtime = {
             component: FAQMountableWidget,
             metadata: {
                 name: 'FAQ Accordion',
-                description: 'Collapsible Q&A accordion with search',
+                description: 'Collapsible Q&A accordion with search, categories, and feedback',
                 icon: '❓',
             },
         },