@hyperfixi/behaviors 2.0.0 → 2.1.0

package/src/behaviors/integration.test.ts

@@ -5,6 +5,12 @@ import { registerToggleable, toggleableSource } from './toggleable';
 import { registerRemovable, removableSource } from './removable';
 import { registerSortable, sortableSource } from './sortable';
 import { registerResizable, resizableSource } from './resizable';
+import { registerClipboard, clipboardSource } from './clipboard';
+import { registerAutoDismiss, autoDismissSource } from './autodismiss';
+import { registerClickOutside, clickOutsideSource } from './clickoutside';
+import { registerFocusTrap, focusTrapSource } from './focustrap';
+import { registerScrollReveal, scrollRevealSource } from './scrollreveal';
+import { registerTabs, tabsSource } from './tabs';
 
 function createMockInstance(overrides: Partial<LokaScriptInstance> = {}): LokaScriptInstance {
   return {
@@ -15,66 +21,135 @@ function createMockInstance(overrides: Partial<LokaScriptInstance> = {}): LokaSc
   };
 }
 
-const behaviors = [
+// Source-compiled behaviors (use compileSync + execute)
+const compiledBehaviors = [
+  { name: 'Removable', register: registerRemovable, source: removableSource },
+] as const;
+
+// Imperative behaviors (use synthetic node with imperativeInstaller)
+const imperativeBehaviors = [
   { name: 'Draggable', register: registerDraggable, source: draggableSource },
   { name: 'Toggleable', register: registerToggleable, source: toggleableSource },
-  { name: 'Removable', register: registerRemovable, source: removableSource },
   { name: 'Sortable', register: registerSortable, source: sortableSource },
   { name: 'Resizable', register: registerResizable, source: resizableSource },
+  { name: 'Clipboard', register: registerClipboard, source: clipboardSource },
+  { name: 'AutoDismiss', register: registerAutoDismiss, source: autoDismissSource },
+  { name: 'ClickOutside', register: registerClickOutside, source: clickOutsideSource },
+  { name: 'FocusTrap', register: registerFocusTrap, source: focusTrapSource },
+  { name: 'ScrollReveal', register: registerScrollReveal, source: scrollRevealSource },
+  { name: 'Tabs', register: registerTabs, source: tabsSource },
 ] as const;
 
 describe('behavior registration integration', () => {
-  for (const { name, register, source } of behaviors) {
-    describe(name, () => {
-      it('should compile with traditional parser', async () => {
-        const mock = createMockInstance();
-        await register(mock);
+  describe('source-compiled behaviors', () => {
+    for (const { name, register, source } of compiledBehaviors) {
+      describe(name, () => {
+        it('should compile with traditional parser', async () => {
+          const mock = createMockInstance();
+          await register(mock);
 
-        expect(mock.compileSync).toHaveBeenCalledWith(source, { traditional: true });
-      });
+          expect(mock.compileSync).toHaveBeenCalledWith(source, { traditional: true });
+        });
 
-      it('should create context and execute', async () => {
-        const mock = createMockInstance();
-        await register(mock);
+        it('should create context and execute', async () => {
+          const mock = createMockInstance();
+          await register(mock);
 
-        expect(mock.createContext).toHaveBeenCalled();
-        expect(mock.execute).toHaveBeenCalledWith(
-          { type: 'behavior' },
-          { locals: expect.any(Map), globals: expect.any(Map) }
-        );
-      });
+          expect(mock.createContext).toHaveBeenCalled();
+          expect(mock.execute).toHaveBeenCalledWith(
+            { type: 'behavior' },
+            { locals: expect.any(Map), globals: expect.any(Map) }
+          );
+        });
+
+        it('should throw on compile failure', async () => {
+          const mock = createMockInstance({
+            compileSync: vi.fn().mockReturnValue({
+              ok: false,
+              errors: [{ message: 'syntax error', line: 1 }],
+            }),
+          });
 
-      it('should throw on compile failure', async () => {
-        const mock = createMockInstance({
-          compileSync: vi.fn().mockReturnValue({
-            ok: false,
-            errors: [{ message: 'syntax error', line: 1 }],
-          }),
+          await expect(register(mock)).rejects.toThrowError(
+            new RegExp(`Failed to compile ${name}`)
+          );
         });
 
-        await expect(register(mock)).rejects.toThrowError(new RegExp(`Failed to compile ${name}`));
-      });
+        it('should throw when lokascript is not available', async () => {
+          await expect(register(undefined)).rejects.toThrowError(/LokaScript not found/);
+        });
+
+        it('should fall back to manual context when createContext is missing', async () => {
+          const mock = createMockInstance();
+          delete (mock as Partial<LokaScriptInstance>).createContext;
+
+          await register(mock);
 
-      it('should throw when lokascript is not available', async () => {
-        await expect(register(undefined)).rejects.toThrowError(/LokaScript not found/);
+          expect(mock.execute).toHaveBeenCalledWith(
+            { type: 'behavior' },
+            expect.objectContaining({
+              locals: expect.any(Map),
+              globals: expect.any(Map),
+            })
+          );
+        });
       });
+    }
+  });
+
+  describe('imperative behaviors', () => {
+    for (const { name, register } of imperativeBehaviors) {
+      describe(name, () => {
+        it('should register via synthetic node with imperativeInstaller', async () => {
+          const mock = createMockInstance();
+          await register(mock);
+
+          // Imperative behaviors do NOT call compileSync
+          expect(mock.compileSync).not.toHaveBeenCalled();
+
+          // They call execute with a synthetic node containing imperativeInstaller
+          expect(mock.execute).toHaveBeenCalledWith(
+            expect.objectContaining({
+              type: 'behavior',
+              name,
+              imperativeInstaller: expect.any(Function),
+            }),
+            expect.objectContaining({
+              locals: expect.any(Map),
+              globals: expect.any(Map),
+            })
+          );
+        });
+
+        it('should create context', async () => {
+          const mock = createMockInstance();
+          await register(mock);
+          expect(mock.createContext).toHaveBeenCalled();
+        });
+
+        it('should throw when lokascript is not available', async () => {
+          await expect(register(undefined)).rejects.toThrowError(/LokaScript not found/);
+        });
 
-      it('should fall back to manual context when createContext is missing', async () => {
-        const mock = createMockInstance();
-        // Remove createContext
-        delete (mock as Partial<LokaScriptInstance>).createContext;
-
-        await register(mock);
-
-        // Should still call execute with a fallback context
-        expect(mock.execute).toHaveBeenCalledWith(
-          { type: 'behavior' },
-          expect.objectContaining({
-            locals: expect.any(Map),
-            globals: expect.any(Map),
-          })
-        );
+        it('should fall back to manual context when createContext is missing', async () => {
+          const mock = createMockInstance();
+          delete (mock as Partial<LokaScriptInstance>).createContext;
+
+          await register(mock);
+
+          expect(mock.execute).toHaveBeenCalledWith(
+            expect.objectContaining({
+              type: 'behavior',
+              name,
+              imperativeInstaller: expect.any(Function),
+            }),
+            expect.objectContaining({
+              locals: expect.any(Map),
+              globals: expect.any(Map),
+            })
+          );
+        });
       });
-    });
-  }
+    }
+  });
 });

package/src/behaviors/removable.ts

@@ -13,7 +13,8 @@
  */
 
 import { removableSchema } from '../schemas/removable.schema';
-import type { LokaScriptInstance, LokaScriptWindow } from '../schemas/types';
+import type { LokaScriptInstance } from '../schemas/types';
+import { resolveRuntime } from '../schemas/types';
 
 // Re-export schema-derived values for backwards compatibility
 export const removableSource = removableSchema.source;
@@ -23,9 +24,7 @@ export const removableMetadata = removableSchema;
  * Register the Removable behavior with LokaScript.
  */
 export async function registerRemovable(hyperfixi?: LokaScriptInstance): Promise<void> {
-  const hf =
-    hyperfixi ||
-    (typeof window !== 'undefined' ? (window as unknown as LokaScriptWindow).lokascript : null);
+  const hf = hyperfixi || resolveRuntime();
 
   if (!hf) {
     throw new Error(
@@ -44,7 +43,7 @@ export async function registerRemovable(hyperfixi?: LokaScriptInstance): Promise
 }
 
 // Auto-register when loaded as a script tag
-if (typeof window !== 'undefined' && (window as unknown as LokaScriptWindow).lokascript) {
+if (resolveRuntime()) {
   registerRemovable().catch(console.error);
 }
 

package/src/behaviors/resizable.ts

@@ -1,7 +1,7 @@
 /**
- * Resizable Behavior
+ * Resizable Behavior — Imperative Implementation
  *
- * A behavior that makes elements resizable by dragging edges or corners.
+ * Makes elements resizable by dragging edges or corners.
  * Supports minimum/maximum dimensions and resize handles.
  *
  * @example
@@ -13,19 +13,67 @@
  */
 
 import { resizableSchema } from '../schemas/resizable.schema';
-import type { LokaScriptInstance, LokaScriptWindow } from '../schemas/types';
+import type { LokaScriptInstance } from '../schemas/types';
+import { resolveRuntime } from '../schemas/types';
 
 // Re-export schema-derived values for backwards compatibility
 export const resizableSource = resizableSchema.source;
 export const resizableMetadata = resizableSchema;
 
+/**
+ * Imperative installer for Resizable behavior.
+ */
+function installResizable(element: HTMLElement, params: Record<string, any>): void {
+  // Resolve handle element
+  let handleEl: HTMLElement = element;
+  if (params.handle && params.handle !== 'me') {
+    if (typeof params.handle === 'string') {
+      const found = element.querySelector(params.handle);
+      if (found instanceof HTMLElement) handleEl = found;
+    } else if (params.handle instanceof HTMLElement) {
+      handleEl = params.handle;
+    }
+  }
+
+  const minW = params.minWidth ?? 50;
+  const minH = params.minHeight ?? 50;
+  const maxW = params.maxWidth ?? 9999;
+  const maxH = params.maxHeight ?? 9999;
+
+  handleEl.addEventListener('pointerdown', (e: PointerEvent) => {
+    e.preventDefault();
+    element.dispatchEvent(new CustomEvent('resizable:start', { bubbles: true }));
+
+    const startWidth = element.offsetWidth;
+    const startHeight = element.offsetHeight;
+    const startX = e.clientX;
+    const startY = e.clientY;
+
+    function onMove(ev: PointerEvent) {
+      const newWidth = Math.max(minW, Math.min(maxW, startWidth + (ev.clientX - startX)));
+      const newHeight = Math.max(minH, Math.min(maxH, startHeight + (ev.clientY - startY)));
+
+      element.style.width = `${newWidth}px`;
+      element.style.height = `${newHeight}px`;
+      element.dispatchEvent(new CustomEvent('resizable:resize', { bubbles: true }));
+    }
+
+    function onUp() {
+      document.removeEventListener('pointermove', onMove);
+      document.removeEventListener('pointerup', onUp);
+      element.dispatchEvent(new CustomEvent('resizable:end', { bubbles: true }));
+    }
+
+    document.addEventListener('pointermove', onMove);
+    document.addEventListener('pointerup', onUp);
+  });
+}
+
 /**
  * Register the Resizable behavior with LokaScript.
  */
 export async function registerResizable(hyperfixi?: LokaScriptInstance): Promise<void> {
-  const hf =
-    hyperfixi ||
-    (typeof window !== 'undefined' ? (window as unknown as LokaScriptWindow).lokascript : null);
+  const hf = hyperfixi || resolveRuntime();
 
   if (!hf) {
     throw new Error(
@@ -33,18 +81,19 @@ export async function registerResizable(hyperfixi?: LokaScriptInstance): Promise
     );
   }
 
-  const result = hf.compileSync(resizableSchema.source, { traditional: true });
-
-  if (!result.ok) {
-    throw new Error(`Failed to compile Resizable behavior: ${JSON.stringify(result.errors)}`);
-  }
-
+  const syntheticNode = {
+    type: 'behavior',
+    name: 'Resizable',
+    parameters: ['handle', 'minWidth', 'minHeight', 'maxWidth', 'maxHeight'],
+    eventHandlers: [],
+    imperativeInstaller: installResizable,
+  };
   const ctx = hf.createContext ? hf.createContext() : { locals: new Map(), globals: new Map() };
-  await hf.execute(result.ast, ctx);
+  await hf.execute(syntheticNode, ctx);
 }
 
 // Auto-register when loaded as a script tag
-if (typeof window !== 'undefined' && (window as unknown as LokaScriptWindow).lokascript) {
+if (resolveRuntime()) {
   registerResizable().catch(console.error);
 }
 

package/src/behaviors/scrollreveal.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect, vi } from 'vitest';
+
+describe('ScrollReveal behavior', () => {
+  describe('registerScrollReveal', () => {
+    it('should register with synthetic node via execute', async () => {
+      const { registerScrollReveal } = await import('./scrollreveal');
+      const mock = {
+        compileSync: vi.fn(),
+        execute: vi.fn().mockResolvedValue(undefined),
+        createContext: vi.fn().mockReturnValue({ locals: new Map(), globals: new Map() }),
+      };
+
+      await registerScrollReveal(mock);
+
+      expect(mock.compileSync).not.toHaveBeenCalled();
+      expect(mock.execute).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'behavior',
+          name: 'ScrollReveal',
+          imperativeInstaller: expect.any(Function),
+        }),
+        expect.objectContaining({ locals: expect.any(Map), globals: expect.any(Map) })
+      );
+    });
+
+    it('should throw when no runtime available', async () => {
+      const { registerScrollReveal } = await import('./scrollreveal');
+      await expect(registerScrollReveal(undefined)).rejects.toThrowError(/LokaScript not found/);
+    });
+  });
+
+  describe('schema', () => {
+    it('should export valid metadata', async () => {
+      const { scrollRevealMetadata } = await import('./scrollreveal');
+      expect(scrollRevealMetadata.name).toBe('ScrollReveal');
+      expect(scrollRevealMetadata.category).toBe('layout');
+      expect(scrollRevealMetadata.tier).toBe('common');
+    });
+
+    it('should have source containing behavior declaration', async () => {
+      const { scrollRevealSource } = await import('./scrollreveal');
+      expect(scrollRevealSource).toContain('behavior ScrollReveal');
+      expect(scrollRevealSource).toContain('IntersectionObserver');
+    });
+
+    it('should document enter/exit events', async () => {
+      const { scrollRevealMetadata } = await import('./scrollreveal');
+      const eventNames = scrollRevealMetadata.events.map(e => e.name);
+      expect(eventNames).toContain('scrollreveal:enter');
+      expect(eventNames).toContain('scrollreveal:exit');
+    });
+
+    it('should document IntersectionObserver requirement', async () => {
+      const { scrollRevealMetadata } = await import('./scrollreveal');
+      const reqs = scrollRevealMetadata.requirements!.join(' ');
+      expect(reqs).toContain('IntersectionObserver');
+    });
+  });
+});

package/src/behaviors/scrollreveal.ts

@@ -0,0 +1,78 @@
+/**
+ * ScrollReveal Behavior — Imperative Implementation
+ *
+ * Adds a class or fires events when the element enters or exits the viewport.
+ * Uses the IntersectionObserver web standard API.
+ */
+
+import { scrollRevealSchema } from '../schemas/scrollreveal.schema';
+import type { LokaScriptInstance } from '../schemas/types';
+import { resolveRuntime } from '../schemas/types';
+
+// Re-export schema-derived values
+export const scrollRevealSource = scrollRevealSchema.source;
+export const scrollRevealMetadata = scrollRevealSchema;
+
+/**
+ * Imperative installer for ScrollReveal behavior.
+ */
+function installScrollReveal(element: HTMLElement, params: Record<string, any>): void {
+  const cls = typeof params.cls === 'string' ? params.cls : 'revealed';
+  const threshold = typeof params.threshold === 'number' ? params.threshold : 0.1;
+  const once = params.once !== false;
+  const rootMargin = typeof params.rootMargin === 'string' ? params.rootMargin : '0px';
+
+  const observer = new IntersectionObserver(
+    entries => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          element.classList.add(cls);
+          element.dispatchEvent(new CustomEvent('scrollreveal:enter', { bubbles: true }));
+          if (once) {
+            observer.disconnect();
+          }
+        } else if (!once) {
+          element.classList.remove(cls);
+          element.dispatchEvent(new CustomEvent('scrollreveal:exit', { bubbles: true }));
+        }
+      }
+    },
+    { threshold, rootMargin }
+  );
+
+  observer.observe(element);
+}
+
+/**
+ * Register the ScrollReveal behavior with LokaScript.
+ */
+export async function registerScrollReveal(hyperfixi?: LokaScriptInstance): Promise<void> {
+  const hf = hyperfixi || resolveRuntime();
+
+  if (!hf) {
+    throw new Error(
+      'LokaScript not found. Make sure @hyperfixi/core is loaded before registering behaviors.'
+    );
+  }
+
+  const syntheticNode = {
+    type: 'behavior',
+    name: 'ScrollReveal',
+    parameters: ['cls', 'threshold', 'once', 'rootMargin'],
+    eventHandlers: [],
+    imperativeInstaller: installScrollReveal,
+  };
+  const ctx = hf.createContext ? hf.createContext() : { locals: new Map(), globals: new Map() };
+  await hf.execute(syntheticNode, ctx);
+}
+
+// Auto-register when loaded as a script tag
+if (resolveRuntime()) {
+  registerScrollReveal().catch(console.error);
+}
+
+export default {
+  source: scrollRevealSchema.source,
+  metadata: scrollRevealSchema,
+  register: registerScrollReveal,
+};

package/src/behaviors/sortable.ts

@@ -1,9 +1,13 @@
 /**
- * Sortable Behavior
+ * Sortable Behavior — Imperative Implementation
  *
- * A behavior for drag-and-drop reordering of list items.
+ * Drag-and-drop reordering of list items.
  * Apply to a container element; children become sortable.
  *
+ * Note: This behavior fires lifecycle events but does NOT automatically
+ * reorder DOM elements. Users must handle actual reordering in their
+ * `sortable:move` event handlers.
+ *
  * @example
  * ```html
  * <ul _="install Sortable">
@@ -14,19 +18,61 @@
  */
 
 import { sortableSchema } from '../schemas/sortable.schema';
-import type { LokaScriptInstance, LokaScriptWindow } from '../schemas/types';
+import type { LokaScriptInstance } from '../schemas/types';
+import { resolveRuntime } from '../schemas/types';
 
 // Re-export schema-derived values for backwards compatibility
 export const sortableSource = sortableSchema.source;
 export const sortableMetadata = sortableSchema;
 
+/**
+ * Imperative installer for Sortable behavior.
+ */
+function installSortable(element: HTMLElement, params: Record<string, any>): void {
+  const dragClass = params.dragClass || 'sorting';
+  const handleSelector = params.handle || null;
+
+  element.addEventListener('pointerdown', (e: PointerEvent) => {
+    const target = e.target as HTMLElement;
+    const item = target.closest('li');
+    if (!item || !element.contains(item)) return;
+
+    // If a handle selector is specified, only start drag from the handle
+    if (handleSelector) {
+      const handleEl = target.closest(handleSelector);
+      if (!handleEl) return;
+    }
+
+    e.preventDefault();
+    item.classList.add(dragClass);
+    element.dispatchEvent(new CustomEvent('sortable:start', { bubbles: true, detail: { item } }));
+
+    function onMove(ev: PointerEvent) {
+      element.dispatchEvent(
+        new CustomEvent('sortable:move', {
+          bubbles: true,
+          detail: { clientY: ev.clientY, item },
+        })
+      );
+    }
+
+    function onUp() {
+      document.removeEventListener('pointermove', onMove);
+      document.removeEventListener('pointerup', onUp);
+      item!.classList.remove(dragClass);
+      element.dispatchEvent(new CustomEvent('sortable:end', { bubbles: true, detail: { item } }));
+    }
+
+    document.addEventListener('pointermove', onMove);
+    document.addEventListener('pointerup', onUp);
+  });
+}
+
 /**
  * Register the Sortable behavior with LokaScript.
  */
 export async function registerSortable(hyperfixi?: LokaScriptInstance): Promise<void> {
-  const hf =
-    hyperfixi ||
-    (typeof window !== 'undefined' ? (window as unknown as LokaScriptWindow).lokascript : null);
+  const hf = hyperfixi || resolveRuntime();
 
   if (!hf) {
     throw new Error(
@@ -34,18 +80,19 @@ export async function registerSortable(hyperfixi?: LokaScriptInstance): Promise<
     );
   }
 
-  const result = hf.compileSync(sortableSchema.source, { traditional: true });
-
-  if (!result.ok) {
-    throw new Error(`Failed to compile Sortable behavior: ${JSON.stringify(result.errors)}`);
-  }
-
+  const syntheticNode = {
+    type: 'behavior',
+    name: 'Sortable',
+    parameters: ['handle', 'dragClass'],
+    eventHandlers: [],
+    imperativeInstaller: installSortable,
+  };
   const ctx = hf.createContext ? hf.createContext() : { locals: new Map(), globals: new Map() };
-  await hf.execute(result.ast, ctx);
+  await hf.execute(syntheticNode, ctx);
 }
 
 // Auto-register when loaded as a script tag
-if (typeof window !== 'undefined' && (window as unknown as LokaScriptWindow).lokascript) {
+if (resolveRuntime()) {
   registerSortable().catch(console.error);
 }
 

package/src/behaviors/tabs.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi } from 'vitest';
+
+describe('Tabs behavior', () => {
+  describe('registerTabs', () => {
+    it('should register with synthetic node via execute', async () => {
+      const { registerTabs } = await import('./tabs');
+      const mock = {
+        compileSync: vi.fn(),
+        execute: vi.fn().mockResolvedValue(undefined),
+        createContext: vi.fn().mockReturnValue({ locals: new Map(), globals: new Map() }),
+      };
+
+      await registerTabs(mock);
+
+      expect(mock.compileSync).not.toHaveBeenCalled();
+      expect(mock.execute).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'behavior',
+          name: 'Tabs',
+          imperativeInstaller: expect.any(Function),
+        }),
+        expect.objectContaining({ locals: expect.any(Map), globals: expect.any(Map) })
+      );
+    });
+
+    it('should throw when no runtime available', async () => {
+      const { registerTabs } = await import('./tabs');
+      await expect(registerTabs(undefined)).rejects.toThrowError(/LokaScript not found/);
+    });
+
+    it('should fall back to manual context when createContext is missing', async () => {
+      const { registerTabs } = await import('./tabs');
+      const mock = {
+        compileSync: vi.fn(),
+        execute: vi.fn().mockResolvedValue(undefined),
+      };
+
+      await registerTabs(mock as any);
+      expect(mock.execute).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ locals: expect.any(Map), globals: expect.any(Map) })
+      );
+    });
+  });
+
+  describe('schema', () => {
+    it('should export valid metadata', async () => {
+      const { tabsMetadata } = await import('./tabs');
+      expect(tabsMetadata.name).toBe('Tabs');
+      expect(tabsMetadata.category).toBe('ui');
+      expect(tabsMetadata.tier).toBe('core');
+    });
+
+    it('should have source containing behavior declaration', async () => {
+      const { tabsSource } = await import('./tabs');
+      expect(tabsSource).toContain('behavior Tabs');
+      expect(tabsSource).toContain('orientation');
+    });
+
+    it('should document tabs:change and tabs:changed events', async () => {
+      const { tabsMetadata } = await import('./tabs');
+      const eventNames = tabsMetadata.events.map(e => e.name);
+      expect(eventNames).toContain('tabs:change');
+      expect(eventNames).toContain('tabs:changed');
+    });
+
+    it('should document ARIA requirements', async () => {
+      const { tabsMetadata } = await import('./tabs');
+      expect(tabsMetadata.requirements).toBeDefined();
+      const reqs = tabsMetadata.requirements!.join(' ');
+      expect(reqs).toContain('aria-selected');
+      expect(reqs).toContain('tabindex');
+    });
+
+    it('should have orientation enum parameter', async () => {
+      const { tabsMetadata } = await import('./tabs');
+      const orientationParam = tabsMetadata.parameters.find(p => p.name === 'orientation');
+      expect(orientationParam?.enum).toEqual(['horizontal', 'vertical']);
+    });
+  });
+});