@hyperfixi/behaviors 2.0.0 → 2.1.0

package/src/behaviors/clickoutside.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect, vi } from 'vitest';
+
+describe('ClickOutside behavior', () => {
+  describe('registerClickOutside', () => {
+    it('should register with synthetic node via execute', async () => {
+      const { registerClickOutside } = await import('./clickoutside');
+      const mock = {
+        compileSync: vi.fn(),
+        execute: vi.fn().mockResolvedValue(undefined),
+        createContext: vi.fn().mockReturnValue({ locals: new Map(), globals: new Map() }),
+      };
+
+      await registerClickOutside(mock);
+
+      expect(mock.compileSync).not.toHaveBeenCalled();
+      expect(mock.execute).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'behavior',
+          name: 'ClickOutside',
+          imperativeInstaller: expect.any(Function),
+        }),
+        expect.objectContaining({ locals: expect.any(Map), globals: expect.any(Map) })
+      );
+    });
+
+    it('should throw when no runtime available', async () => {
+      const { registerClickOutside } = await import('./clickoutside');
+      await expect(registerClickOutside(undefined)).rejects.toThrowError(/LokaScript not found/);
+    });
+  });
+
+  describe('schema', () => {
+    it('should export valid metadata', async () => {
+      const { clickOutsideMetadata } = await import('./clickoutside');
+      expect(clickOutsideMetadata.name).toBe('ClickOutside');
+      expect(clickOutsideMetadata.category).toBe('ui');
+      expect(clickOutsideMetadata.tier).toBe('core');
+    });
+
+    it('should have source containing behavior declaration', async () => {
+      const { clickOutsideSource } = await import('./clickoutside');
+      expect(clickOutsideSource).toContain('behavior ClickOutside');
+      expect(clickOutsideSource).toContain('pointerdown');
+    });
+
+    it('should document clickoutside event', async () => {
+      const { clickOutsideMetadata } = await import('./clickoutside');
+      const eventNames = clickOutsideMetadata.events.map(e => e.name);
+      expect(eventNames).toContain('clickoutside');
+    });
+  });
+});

package/src/behaviors/clickoutside.ts

@@ -0,0 +1,77 @@
+/**
+ * ClickOutside Behavior — Imperative Implementation
+ *
+ * Fires a clickoutside event when the user clicks outside the element.
+ * Uses pointerdown instead of click to avoid timing issues.
+ */
+
+import { clickOutsideSchema } from '../schemas/clickoutside.schema';
+import type { LokaScriptInstance } from '../schemas/types';
+import { resolveRuntime } from '../schemas/types';
+
+// Re-export schema-derived values
+export const clickOutsideSource = clickOutsideSchema.source;
+export const clickOutsideMetadata = clickOutsideSchema;
+
+/**
+ * Imperative installer for ClickOutside behavior.
+ */
+function installClickOutside(element: HTMLElement, params: Record<string, any>): void {
+  let active = params.active !== false;
+
+  function onPointerDown(e: Event) {
+    // Auto-cleanup if element has been removed from DOM
+    if (!element.isConnected) {
+      document.removeEventListener('pointerdown', onPointerDown);
+      return;
+    }
+
+    if (active && !element.contains(e.target as Node)) {
+      element.dispatchEvent(new CustomEvent('clickoutside', { bubbles: true }));
+    }
+  }
+
+  document.addEventListener('pointerdown', onPointerDown);
+
+  // Programmatic activation/deactivation via custom events
+  element.addEventListener('clickoutside:activate', () => {
+    active = true;
+  });
+  element.addEventListener('clickoutside:deactivate', () => {
+    active = false;
+  });
+}
+
+/**
+ * Register the ClickOutside behavior with LokaScript.
+ */
+export async function registerClickOutside(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: 'ClickOutside',
+    parameters: ['active'],
+    eventHandlers: [],
+    imperativeInstaller: installClickOutside,
+  };
+  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()) {
+  registerClickOutside().catch(console.error);
+}
+
+export default {
+  source: clickOutsideSchema.source,
+  metadata: clickOutsideSchema,
+  register: registerClickOutside,
+};

package/src/behaviors/clipboard.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect, vi } from 'vitest';
+
+describe('Clipboard behavior', () => {
+  describe('registerClipboard', () => {
+    it('should register with synthetic node via execute', async () => {
+      const { registerClipboard } = await import('./clipboard');
+      const mock = {
+        compileSync: vi.fn(),
+        execute: vi.fn().mockResolvedValue(undefined),
+        createContext: vi.fn().mockReturnValue({ locals: new Map(), globals: new Map() }),
+      };
+
+      await registerClipboard(mock);
+
+      expect(mock.compileSync).not.toHaveBeenCalled();
+      expect(mock.execute).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'behavior',
+          name: 'Clipboard',
+          imperativeInstaller: expect.any(Function),
+        }),
+        expect.objectContaining({ locals: expect.any(Map), globals: expect.any(Map) })
+      );
+    });
+
+    it('should throw when no runtime available', async () => {
+      const { registerClipboard } = await import('./clipboard');
+      await expect(registerClipboard(undefined)).rejects.toThrowError(/LokaScript not found/);
+    });
+
+    it('should fall back to manual context when createContext is missing', async () => {
+      const { registerClipboard } = await import('./clipboard');
+      const mock = {
+        compileSync: vi.fn(),
+        execute: vi.fn().mockResolvedValue(undefined),
+      };
+
+      await registerClipboard(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 { clipboardMetadata } = await import('./clipboard');
+      expect(clipboardMetadata.name).toBe('Clipboard');
+      expect(clipboardMetadata.category).toBe('ui');
+      expect(clipboardMetadata.tier).toBe('core');
+    });
+
+    it('should have source containing behavior declaration', async () => {
+      const { clipboardSource } = await import('./clipboard');
+      expect(clipboardSource).toContain('behavior Clipboard');
+      expect(clipboardSource).toContain('clipboard:copied');
+    });
+
+    it('should document clipboard:copied and clipboard:error events', async () => {
+      const { clipboardMetadata } = await import('./clipboard');
+      const eventNames = clipboardMetadata.events.map(e => e.name);
+      expect(eventNames).toContain('clipboard:copied');
+      expect(eventNames).toContain('clipboard:error');
+    });
+  });
+});

package/src/behaviors/clipboard.ts

@@ -0,0 +1,130 @@
+/**
+ * Clipboard Behavior — Imperative Implementation
+ *
+ * Copies text to clipboard on click with visual feedback.
+ * Uses navigator.clipboard.writeText() with execCommand fallback.
+ */
+
+import { clipboardSchema } from '../schemas/clipboard.schema';
+import type { LokaScriptInstance } from '../schemas/types';
+import { resolveRuntime } from '../schemas/types';
+
+// Re-export schema-derived values
+export const clipboardSource = clipboardSchema.source;
+export const clipboardMetadata = clipboardSchema;
+
+/**
+ * Copy text to clipboard using the modern Clipboard API,
+ * falling back to execCommand for older browsers.
+ */
+async function copyToClipboard(text: string): Promise<void> {
+  if (navigator.clipboard?.writeText) {
+    await navigator.clipboard.writeText(text);
+    return;
+  }
+
+  // Fallback: temporary textarea + execCommand
+  const textarea = document.createElement('textarea');
+  textarea.value = text;
+  textarea.style.position = 'fixed';
+  textarea.style.opacity = '0';
+  document.body.appendChild(textarea);
+  textarea.select();
+  try {
+    document.execCommand('copy');
+  } finally {
+    document.body.removeChild(textarea);
+  }
+}
+
+/**
+ * Resolve a selector parameter to an HTMLElement.
+ */
+function resolveElement(element: HTMLElement, param: unknown): HTMLElement | null {
+  if (!param || param === 'me') return element;
+  if (param instanceof HTMLElement) return param;
+  if (typeof param === 'string') {
+    return (
+      (element.querySelector(param) as HTMLElement) ||
+      (document.querySelector(param) as HTMLElement) ||
+      null
+    );
+  }
+  return null;
+}
+
+/**
+ * Imperative installer for Clipboard behavior.
+ */
+function installClipboard(element: HTMLElement, params: Record<string, any>): void {
+  const feedbackDuration =
+    typeof params.feedbackDuration === 'number' ? params.feedbackDuration : 2000;
+
+  element.addEventListener('click', async () => {
+    // Determine text to copy
+    let copyText: string;
+    if (params.text != null) {
+      copyText = String(params.text);
+    } else {
+      const sourceEl = resolveElement(element, params.source) || element;
+      copyText = (sourceEl as HTMLInputElement).value ?? sourceEl.textContent ?? '';
+    }
+
+    try {
+      await copyToClipboard(copyText);
+
+      // Show feedback
+      const feedbackEl = resolveElement(element, params.feedback) || element;
+      feedbackEl.classList.add('copied');
+      setTimeout(() => feedbackEl.classList.remove('copied'), feedbackDuration);
+
+      element.dispatchEvent(
+        new CustomEvent('clipboard:copied', {
+          bubbles: true,
+          detail: { text: copyText },
+        })
+      );
+    } catch (error) {
+      element.dispatchEvent(
+        new CustomEvent('clipboard:error', {
+          bubbles: true,
+          detail: { error },
+        })
+      );
+    }
+  });
+}
+
+/**
+ * Register the Clipboard behavior with LokaScript.
+ */
+export async function registerClipboard(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: 'Clipboard',
+    parameters: ['text', 'source', 'feedback', 'feedbackDuration'],
+    eventHandlers: [],
+    imperativeInstaller: installClipboard,
+  };
+  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()) {
+  registerClipboard().catch(console.error);
+}
+
+export default {
+  source: clipboardSchema.source,
+  metadata: clipboardSchema,
+  register: registerClipboard,
+};

package/src/behaviors/draggable.ts

@@ -1,8 +1,9 @@
 /**
- * Draggable Behavior
+ * Draggable Behavior — Imperative Implementation
  *
- * A reusable behavior that makes elements draggable with pointer events.
- * Supports custom drag handles, lifecycle events, and smooth positioning.
+ * Makes elements draggable with pointer events.
+ * Uses direct DOM APIs instead of compiling hyperscript source,
+ * bypassing the complex repeat-until-event + wait-for async pattern.
  *
  * @example
  * ```html
@@ -18,19 +19,62 @@
  */
 
 import { draggableSchema } from '../schemas/draggable.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 draggableSource = draggableSchema.source;
 export const draggableMetadata = draggableSchema;
 
+/**
+ * Imperative installer for Draggable behavior.
+ * Called directly by the runtime when `install Draggable` is executed.
+ */
+function installDraggable(element: HTMLElement, params: Record<string, any>): void {
+  // Resolve drag handle: parameter value, CSS selector, or the element itself
+  let dragHandle: HTMLElement = element;
+  if (params.dragHandle && params.dragHandle !== 'me') {
+    if (typeof params.dragHandle === 'string') {
+      const found = element.querySelector(params.dragHandle);
+      if (found instanceof HTMLElement) dragHandle = found;
+    } else if (params.dragHandle instanceof HTMLElement) {
+      dragHandle = params.dragHandle;
+    }
+  }
+
+  dragHandle.addEventListener('pointerdown', (e: PointerEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    element.dispatchEvent(new CustomEvent('draggable:start', { bubbles: true }));
+
+    const startX = element.offsetLeft;
+    const startY = element.offsetTop;
+    const xoff = e.clientX - startX;
+    const yoff = e.clientY - startY;
+
+    function onMove(ev: PointerEvent) {
+      element.style.left = `${ev.clientX - xoff}px`;
+      element.style.top = `${ev.clientY - yoff}px`;
+      element.dispatchEvent(new CustomEvent('draggable:move', { bubbles: true }));
+    }
+
+    function onUp() {
+      document.removeEventListener('pointermove', onMove);
+      document.removeEventListener('pointerup', onUp);
+      element.dispatchEvent(new CustomEvent('draggable:end', { bubbles: true }));
+    }
+
+    document.addEventListener('pointermove', onMove);
+    document.addEventListener('pointerup', onUp);
+  });
+}
+
 /**
  * Register the Draggable behavior with LokaScript.
+ * Uses imperative installer via synthetic behavior node.
  */
 export async function registerDraggable(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(
@@ -38,18 +82,21 @@ export async function registerDraggable(hyperfixi?: LokaScriptInstance): Promise
     );
   }
 
-  const result = hf.compileSync(draggableSchema.source, { traditional: true });
-
-  if (!result.ok) {
-    throw new Error(`Failed to compile Draggable behavior: ${JSON.stringify(result.errors)}`);
-  }
-
+  // Register via execute() with a synthetic behavior node containing the imperative installer.
+  // The runtime detects imperativeInstaller and stores it directly in the behaviorRegistry.
+  const syntheticNode = {
+    type: 'behavior',
+    name: 'Draggable',
+    parameters: ['dragHandle'],
+    eventHandlers: [],
+    imperativeInstaller: installDraggable,
+  };
   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()) {
   registerDraggable().catch(console.error);
 }
 

package/src/behaviors/focustrap.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect, vi } from 'vitest';
+
+describe('FocusTrap behavior', () => {
+  describe('registerFocusTrap', () => {
+    it('should register with synthetic node via execute', async () => {
+      const { registerFocusTrap } = await import('./focustrap');
+      const mock = {
+        compileSync: vi.fn(),
+        execute: vi.fn().mockResolvedValue(undefined),
+        createContext: vi.fn().mockReturnValue({ locals: new Map(), globals: new Map() }),
+      };
+
+      await registerFocusTrap(mock);
+
+      expect(mock.compileSync).not.toHaveBeenCalled();
+      expect(mock.execute).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'behavior',
+          name: 'FocusTrap',
+          imperativeInstaller: expect.any(Function),
+        }),
+        expect.objectContaining({ locals: expect.any(Map), globals: expect.any(Map) })
+      );
+    });
+
+    it('should throw when no runtime available', async () => {
+      const { registerFocusTrap } = await import('./focustrap');
+      await expect(registerFocusTrap(undefined)).rejects.toThrowError(/LokaScript not found/);
+    });
+  });
+
+  describe('schema', () => {
+    it('should export valid metadata', async () => {
+      const { focusTrapMetadata } = await import('./focustrap');
+      expect(focusTrapMetadata.name).toBe('FocusTrap');
+      expect(focusTrapMetadata.category).toBe('ui');
+      expect(focusTrapMetadata.tier).toBe('core');
+    });
+
+    it('should have source containing behavior declaration', async () => {
+      const { focusTrapSource } = await import('./focustrap');
+      expect(focusTrapSource).toContain('behavior FocusTrap');
+    });
+
+    it('should document activation events', async () => {
+      const { focusTrapMetadata } = await import('./focustrap');
+      const eventNames = focusTrapMetadata.events.map(e => e.name);
+      expect(eventNames).toContain('focustrap:activated');
+      expect(eventNames).toContain('focustrap:deactivated');
+    });
+
+    it('should document aria-modal requirement', async () => {
+      const { focusTrapMetadata } = await import('./focustrap');
+      expect(focusTrapMetadata.requirements).toBeDefined();
+      const reqs = focusTrapMetadata.requirements!.join(' ');
+      expect(reqs).toContain('aria-modal');
+    });
+  });
+});

package/src/behaviors/focustrap.ts

@@ -0,0 +1,158 @@
+/**
+ * FocusTrap Behavior — Imperative Implementation
+ *
+ * Confines Tab navigation inside an element, manages aria-modal,
+ * and restores focus on deactivation.
+ */
+
+import { focusTrapSchema } from '../schemas/focustrap.schema';
+import type { LokaScriptInstance } from '../schemas/types';
+import { resolveRuntime } from '../schemas/types';
+
+// Re-export schema-derived values
+export const focusTrapSource = focusTrapSchema.source;
+export const focusTrapMetadata = focusTrapSchema;
+
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not(:disabled)',
+  'input:not(:disabled)',
+  'select:not(:disabled)',
+  'textarea:not(:disabled)',
+  '[tabindex]:not([tabindex="-1"])',
+].join(', ');
+
+/**
+ * Resolve a selector parameter to an HTMLElement within the container.
+ */
+function resolveElement(container: HTMLElement, param: unknown): HTMLElement | null {
+  if (!param) return null;
+  if (param instanceof HTMLElement) return param;
+  if (typeof param === 'string') {
+    return (
+      (container.querySelector(param) as HTMLElement) ||
+      (document.querySelector(param) as HTMLElement) ||
+      null
+    );
+  }
+  return null;
+}
+
+/**
+ * Imperative installer for FocusTrap behavior.
+ */
+function installFocusTrap(element: HTMLElement, params: Record<string, any>): void {
+  const returnFocus = params.returnFocus !== false;
+  let isActive = false;
+  let previouslyFocused: Element | null = null;
+
+  function getFocusableElements(): HTMLElement[] {
+    return Array.from(element.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR));
+  }
+
+  function onKeyDown(e: KeyboardEvent) {
+    if (!isActive || e.key !== 'Tab') return;
+
+    const focusable = getFocusableElements();
+    if (focusable.length === 0) {
+      e.preventDefault();
+      return;
+    }
+
+    // Always prevent default Tab and manually manage focus.
+    // This ensures focus never escapes to elements outside the trap,
+    // even when the modal is embedded in a page with other focusable elements.
+    e.preventDefault();
+
+    const currentIndex = focusable.indexOf(document.activeElement as HTMLElement);
+
+    if (e.shiftKey) {
+      const prevIndex = currentIndex <= 0 ? focusable.length - 1 : currentIndex - 1;
+      focusable[prevIndex].focus();
+    } else {
+      const nextIndex = currentIndex >= focusable.length - 1 ? 0 : currentIndex + 1;
+      focusable[nextIndex].focus();
+    }
+  }
+
+  function activate() {
+    if (isActive) return;
+    isActive = true;
+    previouslyFocused = document.activeElement;
+
+    element.setAttribute('aria-modal', 'true');
+
+    // Focus initialFocus element or first focusable
+    const initialEl = resolveElement(element, params.initialFocus);
+    if (initialEl) {
+      initialEl.focus();
+    } else {
+      const focusable = getFocusableElements();
+      if (focusable.length > 0) {
+        focusable[0].focus();
+      }
+    }
+
+    element.dispatchEvent(new CustomEvent('focustrap:activated', { bubbles: true }));
+  }
+
+  function deactivate() {
+    if (!isActive) return;
+    isActive = false;
+
+    element.removeAttribute('aria-modal');
+
+    if (returnFocus && previouslyFocused instanceof HTMLElement) {
+      previouslyFocused.focus();
+    }
+    previouslyFocused = null;
+
+    element.dispatchEvent(new CustomEvent('focustrap:deactivated', { bubbles: true }));
+  }
+
+  // Keydown handler for Tab trapping
+  element.addEventListener('keydown', onKeyDown);
+
+  // Programmatic activation/deactivation via custom events
+  element.addEventListener('focustrap:activate', () => activate());
+  element.addEventListener('focustrap:deactivate', () => deactivate());
+
+  // Activate immediately if requested
+  if (params.active !== false) {
+    activate();
+  }
+}
+
+/**
+ * Register the FocusTrap behavior with LokaScript.
+ */
+export async function registerFocusTrap(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: 'FocusTrap',
+    parameters: ['active', 'initialFocus', 'returnFocus'],
+    eventHandlers: [],
+    imperativeInstaller: installFocusTrap,
+  };
+  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()) {
+  registerFocusTrap().catch(console.error);
+}
+
+export default {
+  source: focusTrapSchema.source,
+  metadata: focusTrapSchema,
+  register: registerFocusTrap,
+};

package/src/behaviors/index.ts

@@ -38,3 +38,40 @@ export {
   registerToggleable,
   default as Toggleable,
 } from './toggleable';
+
+export {
+  clipboardSource,
+  clipboardMetadata,
+  registerClipboard,
+  default as Clipboard,
+} from './clipboard';
+
+export {
+  autoDismissSource,
+  autoDismissMetadata,
+  registerAutoDismiss,
+  default as AutoDismiss,
+} from './autodismiss';
+
+export {
+  clickOutsideSource,
+  clickOutsideMetadata,
+  registerClickOutside,
+  default as ClickOutside,
+} from './clickoutside';
+
+export {
+  focusTrapSource,
+  focusTrapMetadata,
+  registerFocusTrap,
+  default as FocusTrap,
+} from './focustrap';
+
+export {
+  scrollRevealSource,
+  scrollRevealMetadata,
+  registerScrollReveal,
+  default as ScrollReveal,
+} from './scrollreveal';
+
+export { tabsSource, tabsMetadata, registerTabs, default as Tabs } from './tabs';