@hyperfixi/behaviors 2.0.0

package/src/behaviors/toggleable.ts

@@ -0,0 +1,55 @@
+/**
+ * Toggleable Behavior
+ *
+ * A behavior that toggles a CSS class on click.
+ * Useful for accordions, dropdowns, and toggle buttons.
+ *
+ * @example
+ * ```html
+ * <button _="install Toggleable">Toggle</button>
+ *
+ * <button _="install Toggleable(cls: expanded, target: #menu)">Menu</button>
+ * ```
+ */
+
+import { toggleableSchema } from '../schemas/toggleable.schema';
+import type { LokaScriptInstance, LokaScriptWindow } from '../schemas/types';
+
+// Re-export schema-derived values for backwards compatibility
+export const toggleableSource = toggleableSchema.source;
+export const toggleableMetadata = toggleableSchema;
+
+/**
+ * Register the Toggleable behavior with LokaScript.
+ */
+export async function registerToggleable(hyperfixi?: LokaScriptInstance): Promise<void> {
+  const hf =
+    hyperfixi ||
+    (typeof window !== 'undefined' ? (window as unknown as LokaScriptWindow).lokascript : null);
+
+  if (!hf) {
+    throw new Error(
+      'LokaScript not found. Make sure @hyperfixi/core is loaded before registering behaviors.'
+    );
+  }
+
+  const result = hf.compileSync(toggleableSchema.source, { traditional: true });
+
+  if (!result.ok) {
+    throw new Error(`Failed to compile Toggleable behavior: ${JSON.stringify(result.errors)}`);
+  }
+
+  const ctx = hf.createContext ? hf.createContext() : { locals: new Map(), globals: new Map() };
+  await hf.execute(result.ast, ctx);
+}
+
+// Auto-register when loaded as a script tag
+if (typeof window !== 'undefined' && (window as unknown as LokaScriptWindow).lokascript) {
+  registerToggleable().catch(console.error);
+}
+
+export default {
+  source: toggleableSchema.source,
+  metadata: toggleableSchema,
+  register: registerToggleable,
+};

package/src/core-bundle.ts

@@ -0,0 +1,35 @@
+/**
+ * Core Tier Bundle
+ *
+ * Includes only core tier behaviors (Draggable, Toggleable).
+ * Use this for minimal bundle size when you only need essential behaviors.
+ */
+
+export { registerDraggable, draggableSource, draggableMetadata } from './behaviors/draggable';
+
+export { registerToggleable, toggleableSource, toggleableMetadata } from './behaviors/toggleable';
+
+import { registerDraggable } from './behaviors/draggable';
+import { registerToggleable } from './behaviors/toggleable';
+import type { LokaScriptInstance, LokaScriptWindow } from './schemas/types';
+
+/**
+ * Register all core tier behaviors.
+ */
+export async function registerCore(hyperfixi?: LokaScriptInstance): Promise<void> {
+  await Promise.all([registerDraggable(hyperfixi), registerToggleable(hyperfixi)]);
+}
+
+/**
+ * Promise that resolves when core behaviors are registered.
+ * Set when the package auto-registers in browser environments.
+ */
+export let ready: Promise<void> | null = null;
+
+// Auto-register when loaded in browser
+if (typeof window !== 'undefined' && (window as unknown as LokaScriptWindow).lokascript) {
+  ready = registerCore();
+  ready.catch(err => {
+    console.error('[behaviors] Core auto-registration failed:', err);
+  });
+}

package/src/generated/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Generated Exports
+ *
+ * DO NOT EDIT - Generated by scripts/generate.ts
+ * Run `npm run generate` to regenerate.
+ */
+
+export * from './types';
+export * from './metadata';

package/src/generated/metadata.ts

@@ -0,0 +1,78 @@
+/**
+ * Generated Metadata
+ *
+ * DO NOT EDIT - Generated by scripts/generate.ts
+ * Run `npm run generate` to regenerate.
+ */
+
+import type { BehaviorCategory, BehaviorTier } from '../schemas/types';
+import type { BehaviorName } from './types';
+
+/**
+ * All behavior names.
+ */
+export const ALL_BEHAVIOR_NAMES: BehaviorName[] = [
+  "Draggable",
+  "Sortable",
+  "Resizable",
+  "Removable",
+  "Toggleable"
+];
+
+/**
+ * Behaviors grouped by category.
+ */
+export const BEHAVIORS_BY_CATEGORY: Record<BehaviorCategory, BehaviorName[]> = {
+  "ui": [
+    "Draggable",
+    "Sortable",
+    "Resizable"
+  ],
+  "data": [
+    "Removable"
+  ],
+  "animation": [],
+  "form": [
+    "Toggleable"
+  ],
+  "layout": []
+};
+
+/**
+ * Behaviors grouped by tier.
+ */
+export const BEHAVIORS_BY_TIER: Record<BehaviorTier, BehaviorName[]> = {
+  "core": [
+    "Draggable",
+    "Toggleable"
+  ],
+  "common": [
+    "Sortable",
+    "Removable"
+  ],
+  "optional": [
+    "Resizable"
+  ]
+};
+
+/**
+ * Category for each behavior.
+ */
+export const BEHAVIOR_CATEGORIES: Record<BehaviorName, BehaviorCategory> = {
+  "Draggable": "ui",
+  "Sortable": "ui",
+  "Resizable": "ui",
+  "Removable": "data",
+  "Toggleable": "form"
+};
+
+/**
+ * Tier for each behavior.
+ */
+export const BEHAVIOR_TIERS: Record<BehaviorName, BehaviorTier> = {
+  "Draggable": "core",
+  "Sortable": "common",
+  "Resizable": "optional",
+  "Removable": "common",
+  "Toggleable": "core"
+};

package/src/generated/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Generated Types
+ *
+ * DO NOT EDIT - Generated by scripts/generate.ts
+ * Run `npm run generate` to regenerate.
+ */
+
+/**
+ * Union of all behavior names.
+ */
+export type BehaviorName = 'Draggable' | 'Sortable' | 'Resizable' | 'Removable' | 'Toggleable';
+
+/**
+ * UI category behaviors.
+ */
+export type UIBehavior = 'Draggable' | 'Sortable' | 'Resizable';
+
+/**
+ * Data category behaviors.
+ */
+export type DataBehavior = 'Removable';
+
+/**
+ * Animation category behaviors.
+ */
+export type AnimationBehavior = never;
+
+/**
+ * Form category behaviors.
+ */
+export type FormBehavior = 'Toggleable';
+
+/**
+ * Layout category behaviors.
+ */
+export type LayoutBehavior = never;
+
+/**
+ * Core tier behaviors (always loaded).
+ */
+export type CoreBehavior = 'Draggable' | 'Toggleable';
+
+/**
+ * Common tier behaviors (high usage).
+ */
+export type CommonBehavior = 'Sortable' | 'Removable';
+
+/**
+ * Optional tier behaviors (load on demand).
+ */
+export type OptionalBehavior = 'Resizable';

package/src/index.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect } from 'vitest';
+import {
+  // Individual behavior exports
+  draggableSource,
+  draggableMetadata,
+  removableSource,
+  removableMetadata,
+  toggleableSource,
+  toggleableMetadata,
+  sortableSource,
+  sortableMetadata,
+  resizableSource,
+  resizableMetadata,
+  // Registry functions
+  getAvailableBehaviors,
+  getBehaviorsByCategory,
+  getBehaviorsByTier,
+  getAllSchemas,
+  // Registration functions
+  registerDraggable,
+  registerRemovable,
+  registerToggleable,
+  registerSortable,
+  registerResizable,
+  registerAll,
+} from './index';
+
+describe('@hyperfixi/behaviors', () => {
+  describe('exports', () => {
+    it('should export all behavior sources', () => {
+      expect(draggableSource).toBeDefined();
+      expect(removableSource).toBeDefined();
+      expect(toggleableSource).toBeDefined();
+      expect(sortableSource).toBeDefined();
+      expect(resizableSource).toBeDefined();
+    });
+
+    it('should export all behavior metadata', () => {
+      expect(draggableMetadata.name).toBe('Draggable');
+      expect(removableMetadata.name).toBe('Removable');
+      expect(toggleableMetadata.name).toBe('Toggleable');
+      expect(sortableMetadata.name).toBe('Sortable');
+      expect(resizableMetadata.name).toBe('Resizable');
+    });
+
+    it('should export register functions', () => {
+      expect(registerDraggable).toBeDefined();
+      expect(registerRemovable).toBeDefined();
+      expect(registerToggleable).toBeDefined();
+      expect(registerSortable).toBeDefined();
+      expect(registerResizable).toBeDefined();
+      expect(registerAll).toBeDefined();
+    });
+  });
+
+  describe('registry', () => {
+    it('getAvailableBehaviors should return all behavior names', () => {
+      const names = getAvailableBehaviors();
+      expect(names).toContain('Draggable');
+      expect(names).toContain('Removable');
+      expect(names).toContain('Toggleable');
+      expect(names).toContain('Sortable');
+      expect(names).toContain('Resizable');
+      expect(names.length).toBe(5);
+    });
+
+    it('getBehaviorsByCategory should group by category', () => {
+      expect(getBehaviorsByCategory('ui')).toEqual(['Draggable', 'Sortable', 'Resizable']);
+      expect(getBehaviorsByCategory('data')).toEqual(['Removable']);
+      expect(getBehaviorsByCategory('form')).toEqual(['Toggleable']);
+    });
+
+    it('getBehaviorsByTier should group by tier', () => {
+      expect(getBehaviorsByTier('core')).toEqual(['Draggable', 'Toggleable']);
+      expect(getBehaviorsByTier('common')).toEqual(['Sortable', 'Removable']);
+      expect(getBehaviorsByTier('optional')).toEqual(['Resizable']);
+    });
+
+    it('getAllSchemas should return all schemas', () => {
+      const schemas = getAllSchemas();
+      expect(schemas.length).toBe(5);
+      expect(schemas.map(s => s.name).sort()).toEqual([
+        'Draggable',
+        'Removable',
+        'Resizable',
+        'Sortable',
+        'Toggleable',
+      ]);
+    });
+  });
+
+  describe('Draggable behavior', () => {
+    it('should have valid hyperscript source', () => {
+      expect(draggableSource).toContain('behavior Draggable');
+      expect(draggableSource).toContain('on pointerdown');
+      expect(draggableSource).toContain('trigger draggable:start');
+    });
+
+    it('should have correct schema metadata', () => {
+      expect(draggableMetadata.category).toBe('ui');
+      expect(draggableMetadata.tier).toBe('core');
+      expect(draggableMetadata.parameters).toBeDefined();
+      expect(draggableMetadata.parameters?.length).toBeGreaterThan(0);
+    });
+
+    it('should document events', () => {
+      expect(draggableMetadata.events).toBeDefined();
+      expect(draggableMetadata.events?.map(e => e.name)).toContain('draggable:start');
+      expect(draggableMetadata.events?.map(e => e.name)).toContain('draggable:end');
+    });
+  });
+
+  describe('Removable behavior', () => {
+    it('should have valid hyperscript source', () => {
+      expect(removableSource).toContain('behavior Removable');
+      expect(removableSource).toContain('on click');
+      expect(removableSource).toContain('remove me');
+    });
+
+    it('should have correct schema metadata', () => {
+      expect(removableMetadata.category).toBe('data');
+      expect(removableMetadata.tier).toBe('common');
+    });
+
+    it('should support confirmation parameter', () => {
+      expect(removableSource).toContain('if confirm');
+    });
+
+    it('should use triggerEl parameter (not trigger)', () => {
+      expect(removableSource).toContain('behavior Removable(triggerEl');
+      expect(removableSource).toContain('on click from triggerEl');
+    });
+  });
+
+  describe('Toggleable behavior', () => {
+    it('should have valid hyperscript source', () => {
+      expect(toggleableSource).toContain('behavior Toggleable');
+      expect(toggleableSource).toContain('on click');
+    });
+
+    it('should have correct schema metadata', () => {
+      expect(toggleableMetadata.category).toBe('form');
+      expect(toggleableMetadata.tier).toBe('core');
+    });
+
+    it('should default to "active" class', () => {
+      expect(toggleableSource).toContain('set cls to "active"');
+    });
+  });
+
+  describe('Sortable behavior', () => {
+    it('should have valid hyperscript source', () => {
+      expect(sortableSource).toContain('behavior Sortable');
+      expect(sortableSource).toContain('on pointerdown');
+      expect(sortableSource).toContain('trigger sortable:');
+    });
+
+    it('should have correct schema metadata', () => {
+      expect(sortableMetadata.category).toBe('ui');
+      expect(sortableMetadata.tier).toBe('common');
+    });
+  });
+
+  describe('Resizable behavior', () => {
+    it('should have valid hyperscript source', () => {
+      expect(resizableSource).toContain('behavior Resizable');
+      expect(resizableSource).toContain('on pointerdown');
+    });
+
+    it('should have correct schema metadata', () => {
+      expect(resizableMetadata.category).toBe('ui');
+      expect(resizableMetadata.tier).toBe('optional');
+    });
+
+    it('should support min/max constraints', () => {
+      expect(resizableSource).toContain('minWidth');
+      expect(resizableSource).toContain('maxWidth');
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,222 @@
+/**
+ * @hyperfixi/behaviors
+ *
+ * Reusable hyperscript behaviors for LokaScript.
+ * Each behavior can be imported individually for tree-shaking,
+ * or all behaviors can be registered at once.
+ *
+ * @example Individual import (tree-shakeable)
+ * ```javascript
+ * import { registerDraggable } from '@hyperfixi/behaviors/draggable';
+ * await registerDraggable();
+ * ```
+ *
+ * @example Import all
+ * ```javascript
+ * import { registerAll } from '@hyperfixi/behaviors';
+ * await registerAll();
+ * ```
+ *
+ * @example Registry-based lazy loading
+ * ```javascript
+ * import { loadBehavior, getBehaviorsByCategory } from '@hyperfixi/behaviors';
+ * await loadBehavior('Draggable');
+ * const uiBehaviors = getBehaviorsByCategory('ui');
+ * ```
+ *
+ * @example CDN usage
+ * ```html
+ * <script src="lokascript-browser.js"></script>
+ * <script src="@hyperfixi/behaviors/draggable.browser.js"></script>
+ * <!-- Draggable is auto-registered -->
+ * ```
+ */
+
+// =============================================================================
+// Re-export individual behaviors
+// =============================================================================
+
+export {
+  draggableSource,
+  draggableMetadata,
+  registerDraggable,
+  default as Draggable,
+} from './behaviors/draggable';
+
+export {
+  removableSource,
+  removableMetadata,
+  registerRemovable,
+  default as Removable,
+} from './behaviors/removable';
+
+export {
+  toggleableSource,
+  toggleableMetadata,
+  registerToggleable,
+  default as Toggleable,
+} from './behaviors/toggleable';
+
+export {
+  sortableSource,
+  sortableMetadata,
+  registerSortable,
+  default as Sortable,
+} from './behaviors/sortable';
+
+export {
+  resizableSource,
+  resizableMetadata,
+  registerResizable,
+  default as Resizable,
+} from './behaviors/resizable';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type {
+  BehaviorSchema,
+  BehaviorCategory,
+  BehaviorTier,
+  ParameterSchema,
+  EventSchema,
+  BehaviorModule,
+  LokaScriptInstance,
+} from './schemas/types';
+
+// =============================================================================
+// Initialize registry with loaders (populates schemas and loaders)
+// =============================================================================
+
+import './loaders';
+
+// =============================================================================
+// Registry exports
+// =============================================================================
+
+export {
+  // Registration
+  registerBehavior,
+  registerSchema,
+  registerLoader,
+  // Query (sync)
+  getBehavior,
+  tryGetBehavior,
+  getSchema,
+  tryGetSchema,
+  isRegistered,
+  hasLoader,
+  getRegisteredBehaviors,
+  getAvailableBehaviors,
+  // Query by metadata
+  getBehaviorsByCategory,
+  getBehaviorsByTier,
+  getAllSchemas,
+  getAllSchemasRecord,
+  // Lazy loading (async)
+  loadBehavior,
+  preloadTier,
+  preloadCategory,
+  loadAll,
+  // Runtime registration
+  registerWithRuntime,
+  registerAllWithRuntime,
+} from './registry';
+
+// =============================================================================
+// Generated types and metadata
+// =============================================================================
+
+export type {
+  BehaviorName,
+  UIBehavior,
+  DataBehavior,
+  AnimationBehavior,
+  FormBehavior,
+  LayoutBehavior,
+  CoreBehavior,
+  CommonBehavior,
+  OptionalBehavior,
+} from './generated/types';
+
+export {
+  ALL_BEHAVIOR_NAMES,
+  BEHAVIORS_BY_CATEGORY,
+  BEHAVIORS_BY_TIER,
+  BEHAVIOR_CATEGORIES,
+  BEHAVIOR_TIERS,
+} from './generated/metadata';
+
+// =============================================================================
+// Convenience functions
+// =============================================================================
+
+import { registerDraggable } from './behaviors/draggable';
+import { registerRemovable } from './behaviors/removable';
+import { registerToggleable } from './behaviors/toggleable';
+import { registerSortable } from './behaviors/sortable';
+import { registerResizable } from './behaviors/resizable';
+import type { LokaScriptInstance, LokaScriptWindow } from './schemas/types';
+
+/**
+ * Register all behaviors with HyperFixi.
+ *
+ * @param hyperfixi - The hyperfixi instance (defaults to window.hyperfixi)
+ * @returns Promise that resolves when all behaviors are registered
+ *
+ * @example
+ * ```javascript
+ * import { registerAll } from '@hyperfixi/behaviors';
+ * await registerAll();
+ * ```
+ */
+export async function registerAll(hyperfixi?: LokaScriptInstance): Promise<void> {
+  await Promise.all([
+    registerDraggable(hyperfixi),
+    registerRemovable(hyperfixi),
+    registerToggleable(hyperfixi),
+    registerSortable(hyperfixi),
+    registerResizable(hyperfixi),
+  ]);
+}
+
+// =============================================================================
+// Auto-registration for browser
+// =============================================================================
+
+/**
+ * Promise that resolves when all behaviors are registered.
+ * This is set when the package auto-registers in browser environments.
+ */
+export let ready: Promise<void> | null = null;
+
+// Auto-register all behaviors when loaded in browser with hyperfixi available
+if (typeof window !== 'undefined' && (window as unknown as LokaScriptWindow).lokascript) {
+  const lsWin = window as unknown as LokaScriptWindow;
+  ready = registerAll();
+
+  lsWin.__lokascript_behaviors_ready = ready;
+
+  ready
+    .then(() => {
+      const hyperfixi = lsWin.lokascript as LokaScriptInstance & {
+        attributeProcessor?: { scanAndProcessAll: () => Promise<void> };
+        processNode?: (node: Document) => void;
+      };
+      const savedPromise = lsWin.__lokascript_behaviors_ready;
+      delete lsWin.__lokascript_behaviors_ready;
+
+      if (hyperfixi.attributeProcessor?.scanAndProcessAll) {
+        hyperfixi.attributeProcessor.scanAndProcessAll().finally(() => {
+          lsWin.__lokascript_behaviors_ready = savedPromise;
+        });
+      } else if (hyperfixi.processNode) {
+        hyperfixi.processNode(document);
+        lsWin.__lokascript_behaviors_ready = savedPromise;
+      }
+    })
+    .catch(err => {
+      console.error('[behaviors] Auto-registration failed:', err);
+    });
+}

package/src/loaders.ts

@@ -0,0 +1,39 @@
+/**
+ * Behavior Loaders
+ *
+ * Registers lazy loaders for all behaviors.
+ * Import this module to enable on-demand loading without bundling all behaviors.
+ *
+ * @example
+ * ```typescript
+ * // Enable lazy loading
+ * import '@hyperfixi/behaviors/loaders';
+ *
+ * // Now load behaviors on demand
+ * import { loadBehavior } from '@hyperfixi/behaviors/registry';
+ * await loadBehavior('Draggable');
+ * ```
+ */
+
+import { registerLoader, registerSchema } from './registry';
+
+// Register schemas for metadata queries before loading
+import { draggableSchema } from './schemas/draggable.schema';
+import { sortableSchema } from './schemas/sortable.schema';
+import { resizableSchema } from './schemas/resizable.schema';
+import { removableSchema } from './schemas/removable.schema';
+import { toggleableSchema } from './schemas/toggleable.schema';
+
+// Register all schemas
+registerSchema(draggableSchema);
+registerSchema(sortableSchema);
+registerSchema(resizableSchema);
+registerSchema(removableSchema);
+registerSchema(toggleableSchema);
+
+// Register lazy loaders - behaviors are only loaded when requested
+registerLoader('Draggable', () => import('./behaviors/draggable'));
+registerLoader('Sortable', () => import('./behaviors/sortable'));
+registerLoader('Resizable', () => import('./behaviors/resizable'));
+registerLoader('Removable', () => import('./behaviors/removable'));
+registerLoader('Toggleable', () => import('./behaviors/toggleable'));