@hyperfixi/behaviors 2.0.0

package/src/registry.test.ts

@@ -0,0 +1,207 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { BehaviorModule, BehaviorSchema } from './schemas/types';
+
+// Initialize the registry with schemas and loaders (same side-effect as index.ts)
+import './loaders';
+
+import {
+  registerBehavior,
+  registerSchema,
+  registerLoader,
+  getBehavior,
+  tryGetBehavior,
+  getSchema,
+  tryGetSchema,
+  isRegistered,
+  hasLoader,
+  getRegisteredBehaviors,
+  getAvailableBehaviors,
+  getBehaviorsByCategory,
+  getBehaviorsByTier,
+  getAllSchemas,
+  getAllSchemasRecord,
+  loadBehavior,
+  preloadTier,
+  preloadCategory,
+  loadAll,
+  registerWithRuntime,
+  registerAllWithRuntime,
+} from './registry';
+
+// Create test fixtures
+function createMockSchema(overrides: Partial<BehaviorSchema> = {}): BehaviorSchema {
+  return {
+    name: 'TestBehavior',
+    category: 'ui',
+    tier: 'core',
+    version: '1.0.0',
+    description: 'Test behavior',
+    parameters: [],
+    events: [],
+    source: 'behavior TestBehavior\nend',
+    ...overrides,
+  };
+}
+
+function createMockModule(overrides: Partial<BehaviorModule> = {}): BehaviorModule {
+  const schema = createMockSchema(overrides.metadata ? { ...overrides.metadata } : undefined);
+  return {
+    source: schema.source,
+    metadata: schema,
+    register: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  };
+}
+
+describe('registry', () => {
+  // Note: The registry is a module-level singleton, so loaders.ts has already
+  // populated it with the 5 real behavior schemas. Tests build on this state.
+
+  describe('registerBehavior', () => {
+    it('should register a behavior and its schema', () => {
+      const module = createMockModule({
+        metadata: createMockSchema({ name: 'RegTest' }),
+      });
+      registerBehavior('RegTest', module);
+      expect(getBehavior('RegTest')).toBe(module);
+      expect(getSchema('RegTest').name).toBe('RegTest');
+    });
+  });
+
+  describe('getBehavior / tryGetBehavior', () => {
+    it('should throw for unregistered behavior', () => {
+      expect(() => getBehavior('NonExistent')).toThrowError(/not registered/);
+    });
+
+    it('should suggest lazy loading in error message', () => {
+      expect(() => getBehavior('NonExistent')).toThrowError(/loadBehavior/);
+    });
+
+    it('tryGetBehavior should return undefined for unregistered', () => {
+      expect(tryGetBehavior('NonExistent')).toBeUndefined();
+    });
+  });
+
+  describe('getSchema / tryGetSchema', () => {
+    it('should throw for unregistered schema', () => {
+      expect(() => getSchema('NonExistent')).toThrowError(/not registered/);
+    });
+
+    it('should suggest tryGetSchema in error message', () => {
+      expect(() => getSchema('NonExistent')).toThrowError(/tryGetSchema/);
+    });
+
+    it('tryGetSchema should return undefined for unregistered', () => {
+      expect(tryGetSchema('NonExistent')).toBeUndefined();
+    });
+
+    it('should return schema for registered behavior', () => {
+      const schema = getSchema('Draggable');
+      expect(schema.name).toBe('Draggable');
+      expect(schema.category).toBe('ui');
+    });
+  });
+
+  describe('isRegistered / hasLoader', () => {
+    it('hasLoader should return true for registered loaders', () => {
+      expect(hasLoader('Draggable')).toBe(true);
+      expect(hasLoader('NonExistent')).toBe(false);
+    });
+  });
+
+  describe('metadata queries', () => {
+    it('getAllSchemasRecord should return record keyed by name', () => {
+      const record = getAllSchemasRecord();
+      expect(record.Draggable).toBeDefined();
+      expect(record.Draggable.category).toBe('ui');
+    });
+  });
+
+  describe('loadBehavior', () => {
+    it('should load via registered loader', async () => {
+      const module = await loadBehavior('Toggleable');
+      expect(module).toBeDefined();
+      expect(module.metadata.name).toBe('Toggleable');
+    });
+
+    it('should return cached module on second load', async () => {
+      const first = await loadBehavior('Toggleable');
+      const second = await loadBehavior('Toggleable');
+      expect(first).toBe(second);
+    });
+
+    it('should throw for behavior with no loader', async () => {
+      await expect(loadBehavior('NonExistent')).rejects.toThrowError(/No loader/);
+    });
+  });
+
+  describe('preloadTier / preloadCategory', () => {
+    it('preloadTier should load all behaviors in a tier', async () => {
+      await preloadTier('core');
+      expect(isRegistered('Draggable')).toBe(true);
+      expect(isRegistered('Toggleable')).toBe(true);
+    });
+
+    it('preloadCategory should load all behaviors in a category', async () => {
+      await preloadCategory('ui');
+      expect(isRegistered('Draggable')).toBe(true);
+    });
+
+    it('preloadTier should warn on load failure', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      // Register a loader that fails
+      registerLoader('FailBehavior', () => Promise.reject(new Error('test fail')));
+      registerSchema(createMockSchema({ name: 'FailBehavior', tier: 'optional' }));
+
+      await preloadTier('optional');
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('FailBehavior'),
+        expect.any(Error)
+      );
+      warnSpy.mockRestore();
+    });
+  });
+
+  describe('loadAll', () => {
+    it('should load all available behaviors', async () => {
+      await loadAll();
+      const registered = getRegisteredBehaviors();
+      expect(registered).toContain('Draggable');
+      expect(registered).toContain('Toggleable');
+      expect(registered).toContain('Removable');
+      expect(registered).toContain('Sortable');
+      expect(registered).toContain('Resizable');
+    });
+  });
+
+  describe('registerWithRuntime', () => {
+    it('should load and call module.register', async () => {
+      const mockInstance = {
+        compileSync: vi.fn().mockReturnValue({ ok: true, ast: {} }),
+        execute: vi.fn().mockResolvedValue(undefined),
+        createContext: vi.fn().mockReturnValue({ locals: new Map(), globals: new Map() }),
+      };
+
+      // Load first so module is available
+      await loadBehavior('Draggable');
+
+      await registerWithRuntime('Draggable', mockInstance);
+      expect(mockInstance.compileSync).toHaveBeenCalled();
+    });
+  });
+
+  describe('registerAllWithRuntime', () => {
+    it('should register all loaded behaviors', async () => {
+      const mockInstance = {
+        compileSync: vi.fn().mockReturnValue({ ok: true, ast: {} }),
+        execute: vi.fn().mockResolvedValue(undefined),
+        createContext: vi.fn().mockReturnValue({ locals: new Map(), globals: new Map() }),
+      };
+
+      await loadAll();
+      await registerAllWithRuntime(mockInstance);
+      // Each behavior calls compileSync once
+      expect(mockInstance.compileSync.mock.calls.length).toBeGreaterThanOrEqual(5);
+    });
+  });
+});

package/src/registry.ts

@@ -0,0 +1,304 @@
+/**
+ * Behavior Registry
+ *
+ * Central registration point for behaviors. Modeled on semantic/registry.ts.
+ * Supports lazy loading, category/tier queries, and tree-shaking.
+ *
+ * @example
+ * ```typescript
+ * // Register a behavior
+ * registerBehavior('Draggable', DraggableModule);
+ *
+ * // Query behaviors
+ * const uiBehaviors = getBehaviorsByCategory('ui');
+ * const coreBehaviors = getBehaviorsByTier('core');
+ *
+ * // Lazy load on demand
+ * const module = await loadBehavior('Resizable');
+ * ```
+ */
+
+import type {
+  BehaviorModule,
+  BehaviorSchema,
+  BehaviorCategory,
+  BehaviorTier,
+  LokaScriptInstance,
+} from './schemas/types';
+
+// =============================================================================
+// Registry State
+// =============================================================================
+
+const behaviors = new Map<string, BehaviorModule>();
+const schemas = new Map<string, BehaviorSchema>();
+const loaders = new Map<string, () => Promise<{ default: BehaviorModule }>>();
+const loadingPromises = new Map<string, Promise<BehaviorModule>>();
+
+// =============================================================================
+// Registration Functions
+// =============================================================================
+
+/**
+ * Register a behavior module.
+ */
+export function registerBehavior(name: string, module: BehaviorModule): void {
+  behaviors.set(name, module);
+  if (module.metadata) {
+    schemas.set(name, module.metadata);
+  }
+}
+
+/**
+ * Register a behavior schema (without the module).
+ */
+export function registerSchema(schema: BehaviorSchema): void {
+  schemas.set(schema.name, schema);
+}
+
+/**
+ * Register a lazy loader for a behavior.
+ * The loader should return a module with a default export.
+ */
+export function registerLoader(
+  name: string,
+  loader: () => Promise<{ default: BehaviorModule }>
+): void {
+  loaders.set(name, loader);
+}
+
+// =============================================================================
+// Query Functions (Sync)
+// =============================================================================
+
+/**
+ * Get a behavior module by name.
+ * @throws Error if behavior is not registered
+ */
+export function getBehavior(name: string): BehaviorModule {
+  const behavior = behaviors.get(name);
+  if (!behavior) {
+    const registered = Array.from(behaviors.keys()).join(', ');
+    throw new Error(
+      `Behavior '${name}' is not registered. ` +
+        `Registered behaviors: ${registered || 'none'}. ` +
+        `Use loadBehavior('${name}') to lazy load it.`
+    );
+  }
+  return behavior;
+}
+
+/**
+ * Try to get a behavior, returning undefined if not registered.
+ */
+export function tryGetBehavior(name: string): BehaviorModule | undefined {
+  return behaviors.get(name);
+}
+
+/**
+ * Get a behavior schema by name.
+ * @throws Error if schema is not registered
+ */
+export function getSchema(name: string): BehaviorSchema {
+  const schema = schemas.get(name);
+  if (!schema) {
+    throw new Error(
+      `Schema for behavior '${name}' is not registered. ` +
+        `Use tryGetSchema('${name}') for a non-throwing alternative.`
+    );
+  }
+  return schema;
+}
+
+/**
+ * Try to get a schema, returning undefined if not registered.
+ */
+export function tryGetSchema(name: string): BehaviorSchema | undefined {
+  return schemas.get(name);
+}
+
+/**
+ * Check if a behavior is registered.
+ */
+export function isRegistered(name: string): boolean {
+  return behaviors.has(name);
+}
+
+/**
+ * Check if a loader is registered for a behavior.
+ */
+export function hasLoader(name: string): boolean {
+  return loaders.has(name);
+}
+
+/**
+ * Get all registered behavior names.
+ */
+export function getRegisteredBehaviors(): string[] {
+  return Array.from(behaviors.keys());
+}
+
+/**
+ * Get all behavior names that have loaders (including unloaded).
+ */
+export function getAvailableBehaviors(): string[] {
+  const names = new Set([...behaviors.keys(), ...loaders.keys()]);
+  return Array.from(names);
+}
+
+// =============================================================================
+// Query by Metadata
+// =============================================================================
+
+/**
+ * Get behavior names by category.
+ */
+export function getBehaviorsByCategory(category: BehaviorCategory): string[] {
+  const result: string[] = [];
+  for (const [name, schema] of schemas) {
+    if (schema.category === category) {
+      result.push(name);
+    }
+  }
+  return result;
+}
+
+/**
+ * Get behavior names by tier.
+ */
+export function getBehaviorsByTier(tier: BehaviorTier): string[] {
+  const result: string[] = [];
+  for (const [name, schema] of schemas) {
+    if (schema.tier === tier) {
+      result.push(name);
+    }
+  }
+  return result;
+}
+
+/**
+ * Get all schemas.
+ */
+export function getAllSchemas(): BehaviorSchema[] {
+  return Array.from(schemas.values());
+}
+
+/**
+ * Get all schemas as a record.
+ */
+export function getAllSchemasRecord(): Record<string, BehaviorSchema> {
+  const result: Record<string, BehaviorSchema> = {};
+  for (const [name, schema] of schemas) {
+    result[name] = schema;
+  }
+  return result;
+}
+
+// =============================================================================
+// Lazy Loading (Async)
+// =============================================================================
+
+/**
+ * Load a behavior by name.
+ * If already loaded, returns the cached module.
+ * If a loader is registered, loads and caches the module.
+ */
+export async function loadBehavior(name: string): Promise<BehaviorModule> {
+  // Return cached if available
+  const cached = behaviors.get(name);
+  if (cached) {
+    return cached;
+  }
+
+  // Check for in-flight load
+  const inFlight = loadingPromises.get(name);
+  if (inFlight) {
+    return inFlight;
+  }
+
+  // Check for loader
+  const loader = loaders.get(name);
+  if (!loader) {
+    throw new Error(
+      `No loader registered for behavior '${name}'. ` +
+        `Available loaders: ${Array.from(loaders.keys()).join(', ') || 'none'}`
+    );
+  }
+
+  // Load and cache
+  const promise = loader().then(mod => {
+    const module = mod.default;
+    registerBehavior(name, module);
+    loadingPromises.delete(name);
+    return module;
+  });
+
+  loadingPromises.set(name, promise);
+  return promise;
+}
+
+/**
+ * Preload all behaviors in a tier.
+ */
+export async function preloadTier(tier: BehaviorTier): Promise<void> {
+  const names = getBehaviorsByTier(tier);
+  await Promise.all(
+    names.map(name =>
+      loadBehavior(name).catch(err => {
+        console.warn(`[behaviors] Failed to preload '${name}' (tier: ${tier}):`, err);
+      })
+    )
+  );
+}
+
+/**
+ * Preload all behaviors in a category.
+ */
+export async function preloadCategory(category: BehaviorCategory): Promise<void> {
+  const names = getBehaviorsByCategory(category);
+  await Promise.all(
+    names.map(name =>
+      loadBehavior(name).catch(err => {
+        console.warn(`[behaviors] Failed to preload '${name}' (category: ${category}):`, err);
+      })
+    )
+  );
+}
+
+/**
+ * Load and register all available behaviors.
+ */
+export async function loadAll(): Promise<void> {
+  const names = getAvailableBehaviors();
+  await Promise.all(
+    names.map(name =>
+      loadBehavior(name).catch(err => {
+        console.warn(`[behaviors] Failed to load '${name}':`, err);
+      })
+    )
+  );
+}
+
+// =============================================================================
+// Runtime Registration
+// =============================================================================
+
+/**
+ * Register a behavior with HyperFixi runtime.
+ * Compiles and executes the behavior source.
+ */
+export async function registerWithRuntime(
+  name: string,
+  hyperfixi?: LokaScriptInstance
+): Promise<void> {
+  const module = await loadBehavior(name);
+  await module.register(hyperfixi);
+}
+
+/**
+ * Register all loaded behaviors with HyperFixi runtime.
+ */
+export async function registerAllWithRuntime(hyperfixi?: LokaScriptInstance): Promise<void> {
+  const registrations = Array.from(behaviors.values()).map(module => module.register(hyperfixi));
+  await Promise.all(registrations);
+}

package/src/schemas/draggable.schema.ts

@@ -0,0 +1,54 @@
+import type { BehaviorSchema } from './types';
+
+/**
+ * Draggable Behavior Schema
+ *
+ * Makes elements draggable with pointer events.
+ * Supports custom drag handles and lifecycle events.
+ */
+export const draggableSchema: BehaviorSchema = {
+  name: 'Draggable',
+  category: 'ui',
+  tier: 'core',
+  version: '1.0.0',
+  description: 'Makes elements draggable with pointer events',
+  parameters: [
+    {
+      name: 'dragHandle',
+      type: 'selector',
+      optional: true,
+      default: 'me',
+      description: 'CSS selector for the drag handle element',
+    },
+  ],
+  events: [
+    { name: 'draggable:start', description: 'Fired when drag begins' },
+    { name: 'draggable:move', description: 'Fired during each movement' },
+    { name: 'draggable:end', description: 'Fired when drag completes' },
+  ],
+  requirements: ['position: absolute or position: fixed on the element'],
+  source: `
+behavior Draggable(dragHandle)
+  init
+    if no dragHandle set dragHandle to me
+  end
+  on pointerdown(clientX, clientY) from dragHandle
+    halt the event
+    trigger draggable:start
+    measure x
+    set startX to it
+    measure y
+    set startY to it
+    set xoff to clientX - startX
+    set yoff to clientY - startY
+    repeat until event pointerup from document
+      wait for pointermove(clientX, clientY) or
+               pointerup(clientX, clientY) from document
+      add { left: \${clientX - xoff}px; top: \${clientY - yoff}px; }
+      trigger draggable:move
+    end
+    trigger draggable:end
+  end
+end
+`.trim(),
+};

package/src/schemas/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Behavior Schemas
+ *
+ * Central export point for all behavior schemas.
+ * Used by the registry and code generation.
+ */
+
+// Types
+export type {
+  BehaviorSchema,
+  BehaviorCategory,
+  BehaviorTier,
+  ParameterSchema,
+  EventSchema,
+  BehaviorModule,
+  LokaScriptInstance,
+} from './types';
+
+// Individual schemas
+export { draggableSchema } from './draggable.schema';
+export { sortableSchema } from './sortable.schema';
+export { resizableSchema } from './resizable.schema';
+export { removableSchema } from './removable.schema';
+export { toggleableSchema } from './toggleable.schema';
+
+// All schemas as a collection
+import { draggableSchema } from './draggable.schema';
+import { sortableSchema } from './sortable.schema';
+import { resizableSchema } from './resizable.schema';
+import { removableSchema } from './removable.schema';
+import { toggleableSchema } from './toggleable.schema';
+import type { BehaviorSchema } from './types';
+
+/**
+ * All behavior schemas indexed by name.
+ */
+export const ALL_SCHEMAS: Record<string, BehaviorSchema> = {
+  Draggable: draggableSchema,
+  Sortable: sortableSchema,
+  Resizable: resizableSchema,
+  Removable: removableSchema,
+  Toggleable: toggleableSchema,
+};
+
+/**
+ * Get all schema names.
+ */
+export function getSchemaNames(): string[] {
+  return Object.keys(ALL_SCHEMAS);
+}
+
+/**
+ * Find a schema by name. Returns undefined if not found.
+ *
+ * Note: For the throwing version, use `getSchema()` from the registry
+ * (exported from '@hyperfixi/behaviors').
+ */
+export function findSchema(name: string): BehaviorSchema | undefined {
+  return ALL_SCHEMAS[name];
+}

package/src/schemas/removable.schema.ts

@@ -0,0 +1,69 @@
+import type { BehaviorSchema } from './types';
+
+/**
+ * Removable Behavior Schema
+ *
+ * Removes an element when a trigger is clicked.
+ * Supports optional confirmation and transition effects.
+ *
+ * @since 1.2.0 — `trigger` parameter renamed to `triggerEl` to avoid
+ * shadowing the hyperscript `trigger` command keyword. Users migrating
+ * from v1.x should update: `install Removable(triggerEl: .close-btn)`.
+ */
+export const removableSchema: BehaviorSchema = {
+  name: 'Removable',
+  category: 'data',
+  tier: 'common',
+  version: '1.2.0',
+  description: 'Makes elements removable on click',
+  parameters: [
+    {
+      name: 'triggerEl',
+      type: 'selector',
+      optional: true,
+      default: 'me',
+      description: 'Element that triggers removal (e.g., a close button)',
+    },
+    {
+      name: 'confirm',
+      type: 'boolean',
+      optional: true,
+      default: false,
+      description: 'Show confirmation dialog before removal',
+    },
+    {
+      name: 'effect',
+      type: 'string',
+      optional: true,
+      default: 'none',
+      enum: ['fade', 'none'],
+      description: 'Transition effect: "fade" or "none"',
+    },
+  ],
+  events: [
+    { name: 'removable:before', description: 'Fired before removal (cancelable)' },
+    { name: 'removable:removed', description: 'Fired after removal' },
+  ],
+  source: `
+behavior Removable(triggerEl, confirm, effect)
+  init
+    if triggerEl is undefined
+      set triggerEl to me
+    end
+  end
+  on click from triggerEl
+    if confirm
+      if not window.confirm("Are you sure?")
+        halt
+      end
+    end
+    trigger removable:before
+    if effect is "fade"
+      transition opacity to 0 over 300ms
+    end
+    trigger removable:removed
+    remove me
+  end
+end
+`.trim(),
+};