@hyperfixi/behaviors 2.0.0

package/src/schemas/resizable.schema.ts

@@ -0,0 +1,91 @@
+import type { BehaviorSchema } from './types';
+
+/**
+ * Resizable Behavior Schema
+ *
+ * Makes elements resizable by dragging edges or corners.
+ * Supports minimum/maximum dimensions and resize handles.
+ */
+export const resizableSchema: BehaviorSchema = {
+  name: 'Resizable',
+  category: 'ui',
+  tier: 'optional',
+  version: '1.0.0',
+  description: 'Makes elements resizable by dragging',
+  parameters: [
+    {
+      name: 'handle',
+      type: 'selector',
+      optional: true,
+      default: 'me',
+      description: 'CSS selector for the resize handle (defaults to the element itself)',
+    },
+    {
+      name: 'minWidth',
+      type: 'number',
+      optional: true,
+      default: 50,
+      description: 'Minimum width in pixels',
+    },
+    {
+      name: 'minHeight',
+      type: 'number',
+      optional: true,
+      default: 50,
+      description: 'Minimum height in pixels',
+    },
+    {
+      name: 'maxWidth',
+      type: 'number',
+      optional: true,
+      default: 9999,
+      description: 'Maximum width in pixels',
+    },
+    {
+      name: 'maxHeight',
+      type: 'number',
+      optional: true,
+      default: 9999,
+      description: 'Maximum height in pixels',
+    },
+  ],
+  events: [
+    { name: 'resizable:start', description: 'Fired when resize begins' },
+    { name: 'resizable:resize', description: 'Fired during resize' },
+    { name: 'resizable:end', description: 'Fired when resize completes' },
+  ],
+  source: `
+behavior Resizable(handle, minWidth, minHeight, maxWidth, maxHeight)
+  init
+    if no handle set handle to me
+    if no minWidth set minWidth to 50
+    if no minHeight set minHeight to 50
+    if no maxWidth set maxWidth to 9999
+    if no maxHeight set maxHeight to 9999
+  end
+  on pointerdown(clientX, clientY) from handle
+    halt the event
+    trigger resizable:start
+    measure width
+    set startWidth to it
+    measure height
+    set startHeight to it
+    set startX to clientX
+    set startY to clientY
+    repeat until event pointerup from document
+      wait for pointermove(clientX, clientY) or
+               pointerup from document
+      set newWidth to startWidth + (clientX - startX)
+      set newHeight to startHeight + (clientY - startY)
+      if newWidth < minWidth set newWidth to minWidth
+      if newWidth > maxWidth set newWidth to maxWidth
+      if newHeight < minHeight set newHeight to minHeight
+      if newHeight > maxHeight set newHeight to maxHeight
+      add { width: \${newWidth}px; height: \${newHeight}px; }
+      trigger resizable:resize
+    end
+    trigger resizable:end
+  end
+end
+`.trim(),
+};

package/src/schemas/sortable.schema.ts

@@ -0,0 +1,68 @@
+import type { BehaviorSchema } from './types';
+
+/**
+ * Sortable Behavior Schema
+ *
+ * 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.
+ */
+export const sortableSchema: BehaviorSchema = {
+  name: 'Sortable',
+  category: 'ui',
+  tier: 'common',
+  version: '1.0.0',
+  description: 'Makes child elements reorderable via drag-and-drop',
+  parameters: [
+    {
+      name: 'handle',
+      type: 'selector',
+      optional: true,
+      default: 'none',
+      description: 'CSS selector for drag handles within items',
+    },
+    {
+      name: 'dragClass',
+      type: 'string',
+      optional: true,
+      default: 'sorting',
+      description: 'CSS class added to item during drag',
+    },
+  ],
+  events: [
+    { name: 'sortable:start', description: 'Fired when drag begins' },
+    {
+      name: 'sortable:move',
+      description: 'Fired during drag — handle this event to reorder DOM elements',
+    },
+    { name: 'sortable:end', description: 'Fired when drag completes' },
+  ],
+  requirements: ['Users must handle DOM reordering in sortable:move event handlers'],
+  source: `
+behavior Sortable(handle, dragClass)
+  init
+    if no dragClass set dragClass to "sorting"
+  end
+  on pointerdown(target, clientY) from me
+    set item to closest <li/> in target
+    if no item exit
+    if handle
+      set handleEl to target.closest(handle)
+      if no handleEl exit
+    end
+    halt the event
+    add dragClass to item
+    trigger sortable:start on me
+    repeat until event pointerup from document
+      wait for pointermove(clientY) from document
+      trigger sortable:move on me
+    end
+    remove dragClass from item
+    trigger sortable:end on me
+  end
+end
+`.trim(),
+};

package/src/schemas/toggleable.schema.ts

@@ -0,0 +1,50 @@
+import type { BehaviorSchema } from './types';
+
+/**
+ * Toggleable Behavior Schema
+ *
+ * Toggles a CSS class on click.
+ * Useful for accordions, dropdowns, and toggle buttons.
+ */
+export const toggleableSchema: BehaviorSchema = {
+  name: 'Toggleable',
+  category: 'form',
+  tier: 'core',
+  version: '1.0.0',
+  description: 'Toggles a CSS class on click',
+  parameters: [
+    {
+      name: 'cls',
+      type: 'string',
+      optional: true,
+      default: 'active',
+      description: 'CSS class to toggle',
+    },
+    {
+      name: 'target',
+      type: 'selector',
+      optional: true,
+      default: 'me',
+      description: 'Element to toggle the class on',
+    },
+  ],
+  events: [
+    { name: 'toggleable:on', description: 'Fired when class is added' },
+    { name: 'toggleable:off', description: 'Fired when class is removed' },
+  ],
+  source: `
+behavior Toggleable(cls, target)
+  init
+    if cls is undefined
+      set cls to "active"
+    end
+    if target is undefined
+      set target to me
+    end
+  end
+  on click
+    toggle .{cls} on target
+  end
+end
+`.trim(),
+};

package/src/schemas/types.ts

@@ -0,0 +1,107 @@
+/**
+ * Behavior Schema Types
+ *
+ * Defines the structure for behavior metadata used for:
+ * - Code generation (TypeScript types, documentation)
+ * - Runtime categorization and lazy loading
+ * - Tooling and IDE integration
+ */
+
+/**
+ * Behavior categories for organization.
+ * - ui: Visual interaction behaviors (drag, resize, sort)
+ * - data: Data manipulation behaviors (remove, transform)
+ * - animation: Animation and transition behaviors
+ * - form: Form-related behaviors (validation, toggle states)
+ * - layout: Layout behaviors (sticky, scrollspy)
+ */
+export type BehaviorCategory = 'ui' | 'data' | 'animation' | 'form' | 'layout';
+
+/**
+ * Loading tiers for lazy loading optimization.
+ * - core: Always loaded (essential behaviors)
+ * - common: High usage (loaded for typical apps)
+ * - optional: Low usage (loaded on demand)
+ */
+export type BehaviorTier = 'core' | 'common' | 'optional';
+
+/**
+ * Schema for a behavior parameter.
+ */
+export interface ParameterSchema {
+  name: string;
+  type: 'string' | 'number' | 'boolean' | 'selector' | 'element';
+  optional?: boolean;
+  default?: string | number | boolean;
+  /** Allowed values for constrained parameters */
+  enum?: string[];
+  description: string;
+}
+
+/**
+ * Schema for a behavior event.
+ */
+export interface EventSchema {
+  name: string;
+  description: string;
+}
+
+/**
+ * Complete schema for a behavior.
+ * This is the source of truth for all behavior metadata.
+ */
+export interface BehaviorSchema {
+  /** Behavior name (PascalCase) */
+  name: string;
+  /** Category for organization */
+  category: BehaviorCategory;
+  /** Loading tier for lazy loading */
+  tier: BehaviorTier;
+  /** Semantic version */
+  version: string;
+  /** Human-readable description */
+  description: string;
+  /** Parameter definitions */
+  parameters: ParameterSchema[];
+  /** Event definitions */
+  events: EventSchema[];
+  /** The hyperscript behavior source code */
+  source: string;
+  /** Optional requirements or notes */
+  requirements?: string[];
+}
+
+/**
+ * Runtime behavior module interface.
+ * This is what gets registered with the hyperfixi runtime.
+ */
+export interface BehaviorModule {
+  source: string;
+  metadata: BehaviorSchema;
+  register: (hyperfixi?: LokaScriptInstance) => Promise<void>;
+}
+
+/**
+ * Minimal LokaScript instance interface for behavior registration.
+ */
+export interface LokaScriptInstance {
+  compileSync: (
+    code: string,
+    options?: { traditional?: boolean; language?: string }
+  ) => {
+    ok: boolean;
+    ast?: unknown;
+    errors?: Array<{ message: string; line?: number; column?: number }>;
+  };
+  execute: (ast: unknown, ctx: unknown) => Promise<unknown>;
+  createContext?: () => { locals: Map<string, unknown>; globals: Map<string, unknown> };
+}
+
+/**
+ * Typed window interface for behavior auto-registration.
+ * Avoids `(window as any)` casts throughout the codebase.
+ */
+export interface LokaScriptWindow {
+  lokascript?: LokaScriptInstance;
+  __lokascript_behaviors_ready?: Promise<void> | undefined;
+}