Lit Controllers

import { DerivedController } from '@directive-run/lit';

// Single derivation
new DerivedController<T>(host: ReactiveControllerHost, system: System, key: string)

// Multiple derivations
new DerivedController<T>(host: ReactiveControllerHost, system: System, keys: string[])

// Single derivation
class MyElement extends LitElement {
  // Subscribe to the cart total – re-renders when it changes
  private total = new DerivedController<number>(this, system, "total");

  render() {
    return html`<span>Total: ${this.total.value}</span>`;
  }
}

// Multiple derivations
class DashboardElement extends LitElement {
  // Subscribe to multiple derivations at once
  private stats = new DerivedController<Record<string, unknown>>(
    this, system, ["total", "average", "count"]
  );

  render() {
    const { total, average, count } = this.stats.value;

    return html`<div>${total} / ${average} / ${count}</div>`;
  }
}

import { FactController } from '@directive-run/lit';

new FactController<T>(host: ReactiveControllerHost, system: System, key: string)

class StatusElement extends LitElement {
  // Subscribe to the current phase – re-renders when it changes
  private phase = new FactController(this, system, "phase");

  render() {
    return html`<span>Phase: ${this.phase.value}</span>`;
  }
}

import { DirectiveSelectorController } from '@directive-run/lit';

new DirectiveSelectorController<R>(
  host: ReactiveControllerHost,
  system: System,
  selector: (state: FactsProxy) => R,
  equalityFn?: (a: R, b: R) => boolean,
)

class SummaryElement extends LitElement {
  // Select across all facts to build a summary string
  private summary = new DirectiveSelectorController(
    this, system, (facts) => `${facts.user?.name}: ${facts.count}`
  );

  render() {
    return html`<p>${this.summary.value}</p>`;
  }
}

import { WatchController } from '@directive-run/lit';

// Unified API – auto-detects fact vs derivation
new WatchController(
  host: ReactiveControllerHost,
  system: System,
  key: string,
  callback: (value: unknown, prev: unknown) => void,
)

// Deprecated: "fact" discriminator overload (still works)
new WatchController(
  host: ReactiveControllerHost,
  system: System,
  { kind: "fact", factKey: string },
  callback: (value: unknown, prev: unknown) => void,
)

class LoggerElement extends LitElement {
  // Watch the phase derivation – auto-detected
  private _watcher = new WatchController(
    this, system, "phase", (value, prev) => {
      console.log(`Phase changed: ${prev} -> ${value}`);
    }
  );

  // Watch the count fact – auto-detected, no discriminator needed
  private _factWatcher = new WatchController(
    this, system, "count", (value, prev) => {
      console.log(`Count changed: ${prev} -> ${value}`);
    }
  );
}

import { InspectController } from '@directive-run/lit';

new InspectController(host: ReactiveControllerHost, system: System, opts?: { throttleMs?: number })

class DebugElement extends LitElement {
  // Get reactive system inspection data with throttled updates
  private inspect = new InspectController(this, system, { throttleMs: 200 });

  render() {
    const { unmet, isSettled } = this.inspect.value;

    return html`
      <div>Settled: ${isSettled}</div>
      <div>Unmet: ${unmet.length}</div>
    `;
  }
}

import { ExplainController } from '@directive-run/lit';

new ExplainController(host: ReactiveControllerHost, system: System, requirementType: string)

class ExplainElement extends LitElement {
  // Get a detailed explanation of why the TRANSITION requirement exists
  private explanation = new ExplainController(this, system, "TRANSITION");

  render() {
    const exp = this.explanation.value;
    if (!exp) {
      return html`<p>No active requirement</p>`;
    }

    return html`<pre>${JSON.stringify(exp, null, 2)}</pre>`;
  }
}

import { ConstraintStatusController } from '@directive-run/lit';

new ConstraintStatusController(host: ReactiveControllerHost, system: System, constraintId?: string)

class ConstraintElement extends LitElement {
  // Check if the transition constraint is currently active
  private status = new ConstraintStatusController(this, system, "transition");

  render() {
    return html`<span>Active: ${this.status.value?.active}</span>`;
  }
}

import { RequirementStatusController } from '@directive-run/lit';

new RequirementStatusController(
  host: ReactiveControllerHost,
  statusPlugin: StatusPlugin,
  type: string,
)

class LoadingElement extends LitElement {
  // Track the loading state of the FETCH_USER requirement
  private status = new RequirementStatusController(this, statusPlugin, "FETCH_USER");

  render() {
    if (this.status.value.inflight > 0) {
      return html`<spinner-el></spinner-el>`;
    }

    if (this.status.value.lastError) {
      return html`<p>Error!</p>`;
    }

    return html`<p>Ready</p>`;
  }
}

import { OptimisticUpdateController } from '@directive-run/lit';

new OptimisticUpdateController(
  host: ReactiveControllerHost,
  system: System,
  statusPlugin: StatusPlugin,
  requirementType: string,
)

class LikeButton extends LitElement {
  // Set up optimistic mutations with automatic rollback
  private optimistic = new OptimisticUpdateController(
    this, system, statusPlugin, "TOGGLE_LIKE"
  );

  private handleClick() {
    // Optimistically update the UI before the server responds
    this.optimistic.mutate({ liked: true, count: currentCount + 1 });
  }
}

import { ModuleController } from '@directive-run/lit';

new ModuleController(host: ReactiveControllerHost, module: Module, opts?: ModuleOpts)

class CounterElement extends LitElement {
  // Create a scoped system tied to this element's lifecycle
  private mod = new ModuleController(this, counterModule, { status: true });

  render() {
    const count = this.mod.system.read("count");

    return html`<button @click=${() => this.mod.system.dispatch({ type: "INCREMENT" })}>
      ${count}
    </button>`;
  }
}

import { SystemController } from '@directive-run/lit';

// Simple
new SystemController(host: ReactiveControllerHost, module: Module)

// With options
new SystemController(host: ReactiveControllerHost, config: {
  module: Module,
  plugins?: Plugin[],
  debug?: DebugOpts,
})

class AppElement extends LitElement {
  // Create a full system scoped to this element's lifecycle
  private ctrl = new SystemController(this, {
    module: appModule,
    plugins: [loggingPlugin()],
    debug: { timeTravel: true },
  });

  render() {
    // Pass the system down to child elements
    return html`<child-el .system=${this.ctrl.system}></child-el>`;
  }
}

import { TimeTravelController } from '@directive-run/lit';

new TimeTravelController(host: ReactiveControllerHost, system: System)

class TimeTravelElement extends LitElement {
  // Get reactive time-travel controls (null when not enabled)
  private tt = new TimeTravelController(this, system);

  render() {
    const state = this.tt.value;
    if (!state) {
      return html`<p>Time-travel not enabled</p>`;
    }

    return html`
      <button ?disabled=${!state.canUndo} @click=${state.undo}>Undo</button>
      <button ?disabled=${!state.canRedo} @click=${state.redo}>Redo</button>
    `;
  }
}

import {
  createDerived,
  createFact,
  createWatch,
  createInspect,
  createExplain,
  createConstraintStatus,
  createRequirementStatus,
  createOptimisticUpdate,
  createModule,
  createDirectiveSelector,
} from '@directive-run/lit';

class MyElement extends LitElement {
  // These are equivalent:
  private total = new DerivedController(this, system, "total");
  private total = createDerived(this, system, "total");

  // Subscribe to a single fact
  private phase = createFact(this, system, "phase");

  // Subscribe to multiple derivations at once
  private stats = createDerived(this, system, ["total", "average"]);

  // Get system inspection data with throttled updates
  private inspect = createInspect(this, system, { throttleMs: 200 });

  // Get a requirement explanation
  private explanation = createExplain(this, system, "TRANSITION");

  // Check a specific constraint
  private constraint = createConstraintStatus(this, system, "transition");

  // Track requirement loading state
  private reqStatus = createRequirementStatus(this, statusPlugin, "FETCH_USER");

  // Set up optimistic mutations
  private optimistic = createOptimisticUpdate(this, system, statusPlugin, "TOGGLE_LIKE");

  // Create a scoped system tied to this element
  private mod = createModule(this, counterModule, { status: true });

  // Selector factory – derive values from facts
  private summary = createDirectiveSelector(this, system, (facts) => `${facts.count}`);
}

import {
  useDispatch,
  useEvents,
  useTimeTravel,
  getDerived,
  getFact,
  createTypedHooks,
  shallowEqual,
  directiveContext,
} from '@directive-run/lit';

useDispatch(system: System): (event: SystemEvent) => void

// Get a typed dispatch function for sending events
const dispatch = useDispatch(system);

// Dispatch an event directly
dispatch({ type: "INCREMENT", payload: 1 });

useEvents(system: System): TypedEventDispatchers

// Get typed event dispatchers – each event type becomes a callable function
const events = useEvents(system);

// Dispatch events with full type safety
events.increment(1);
events.reset();

useTimeTravel(system: System): TimeTravelState | null

// Get the current time-travel state (non-reactive)
const tt = useTimeTravel(system);

// Undo the last action if possible
if (tt?.canUndo) tt.undo();

getDerived<T>(system: System, key: string): () => T

// Create a non-reactive getter for a derivation
const getTotal = getDerived(system, "total");

// Read the current value on demand
console.log(getTotal());

getFact<T>(system: System, key: string): () => T

// Create a non-reactive getter for a fact
const getCount = getFact(system, "count");

// Read the current value on demand
console.log(getCount());

createTypedHooks<M extends ModuleSchema>(): {
  createDerived: <K>(host, system, derivationId: K) => DerivedController<InferDerivations<M>[K]>;
  createFact: <K>(host, system, factKey: K) => FactController<InferFacts<M>[K]>;
  useDispatch: (system) => (event: InferEvents<M>) => void;
  useEvents: (system) => System<M>["events"];
}

// Create typed controller factories for your schema
const hooks = createTypedHooks<typeof appModule>();

class MyElement extends LitElement {
  // Fully typed – fact key autocompletes, return type inferred
  private count = hooks.createFact(this, "count");

  // Derivation types are also fully inferred
  private total = hooks.createDerived(this, "total");
}

shallowEqual(a: unknown, b: unknown): boolean

// Use shallowEqual to prevent re-renders when name/age haven't changed
const selected = new DirectiveSelectorController(
  this, system, (facts) => ({ name: facts.user?.name, age: facts.user?.age }), shallowEqual
);

import { directiveContext } from '@directive-run/lit';
import { provide, consume } from '@lit/context';

// Provider – share the system with descendant elements
@provide({ context: directiveContext })
system = mySystem;

// Consumer – receive the system from an ancestor
@consume({ context: directiveContext })
system!: System;