@directive-run/knowledge 0.2.0

package/examples/feature-flags.ts

@@ -0,0 +1,220 @@
+// Example: feature-flags
+// Source: examples/feature-flags/src/module.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Feature Flags Directive Module (Example)
+ *
+ * Mirrors the real feature flag system running on directive.run.
+ * 8 flags with two interaction patterns:
+ *
+ * 1. Maintenance mode – disables chat, search, playground, and vote API
+ * 2. Onboarding toast → depends on brand switcher (constraint auto-enables)
+ */
+import { createModule, t } from "@directive-run/core";
+
+export const featureFlagsModule = createModule("feature-flags", {
+  schema: {
+    facts: {
+      // Individual feature toggles
+      chatEnabled: t.boolean(),
+      searchEnabled: t.boolean(),
+      playgroundEnabled: t.boolean(),
+      brandSwitcherEnabled: t.boolean(),
+      themeSelectorEnabled: t.boolean(),
+      onboardingToastEnabled: t.boolean(),
+      versionSelectorEnabled: t.boolean(),
+      voteApiEnabled: t.boolean(),
+
+      // Context
+      maintenanceMode: t.boolean(),
+    },
+    derivations: {
+      canUseChat: t.boolean(),
+      canUseSearch: t.boolean(),
+      canUsePlayground: t.boolean(),
+      canUseBrandSwitcher: t.boolean(),
+      canUseThemeSelector: t.boolean(),
+      canShowOnboardingToast: t.boolean(),
+      canUseVersionSelector: t.boolean(),
+      canUseVoteApi: t.boolean(),
+      enabledCount: t.number(),
+      allFeaturesEnabled: t.boolean(),
+    },
+    events: {
+      configure: {
+        chatEnabled: t.boolean(),
+        searchEnabled: t.boolean(),
+        playgroundEnabled: t.boolean(),
+        brandSwitcherEnabled: t.boolean(),
+        themeSelectorEnabled: t.boolean(),
+        onboardingToastEnabled: t.boolean(),
+        versionSelectorEnabled: t.boolean(),
+        voteApiEnabled: t.boolean(),
+      },
+      setMaintenanceMode: { enabled: t.boolean() },
+      toggleFlag: { flag: t.string(), enabled: t.boolean() },
+      resetAll: {},
+    },
+    requirements: {
+      ENABLE_BRAND_SWITCHER: {},
+      LOG_MAINTENANCE_WARNING: {},
+    },
+  },
+
+  init: (facts) => {
+    facts.chatEnabled = true;
+    facts.searchEnabled = true;
+    facts.playgroundEnabled = true;
+    facts.brandSwitcherEnabled = true;
+    facts.themeSelectorEnabled = true;
+    facts.onboardingToastEnabled = true;
+    facts.versionSelectorEnabled = true;
+    facts.voteApiEnabled = true;
+
+    facts.maintenanceMode = false;
+  },
+
+  derive: {
+    canUseChat: (facts) => facts.chatEnabled && !facts.maintenanceMode,
+    canUseSearch: (facts) => facts.searchEnabled && !facts.maintenanceMode,
+    canUsePlayground: (facts) =>
+      facts.playgroundEnabled && !facts.maintenanceMode,
+    canUseBrandSwitcher: (facts) => facts.brandSwitcherEnabled,
+    canUseThemeSelector: (facts) => facts.themeSelectorEnabled,
+    canShowOnboardingToast: (facts) =>
+      facts.onboardingToastEnabled && facts.brandSwitcherEnabled,
+    canUseVersionSelector: (facts) => facts.versionSelectorEnabled,
+    canUseVoteApi: (facts) => facts.voteApiEnabled && !facts.maintenanceMode,
+    enabledCount: (facts) => {
+      let count = 0;
+      if (facts.chatEnabled) count++;
+      if (facts.searchEnabled) count++;
+      if (facts.playgroundEnabled) count++;
+      if (facts.brandSwitcherEnabled) count++;
+      if (facts.themeSelectorEnabled) count++;
+      if (facts.onboardingToastEnabled) count++;
+      if (facts.versionSelectorEnabled) count++;
+      if (facts.voteApiEnabled) count++;
+
+      return count;
+    },
+    allFeaturesEnabled: (facts) =>
+      facts.chatEnabled &&
+      facts.searchEnabled &&
+      facts.playgroundEnabled &&
+      facts.brandSwitcherEnabled &&
+      facts.themeSelectorEnabled &&
+      facts.onboardingToastEnabled &&
+      facts.versionSelectorEnabled &&
+      facts.voteApiEnabled,
+  },
+
+  events: {
+    configure: (facts, payload) => {
+      facts.chatEnabled = payload.chatEnabled;
+      facts.searchEnabled = payload.searchEnabled;
+      facts.playgroundEnabled = payload.playgroundEnabled;
+      facts.brandSwitcherEnabled = payload.brandSwitcherEnabled;
+      facts.themeSelectorEnabled = payload.themeSelectorEnabled;
+      facts.onboardingToastEnabled = payload.onboardingToastEnabled;
+      facts.versionSelectorEnabled = payload.versionSelectorEnabled;
+      facts.voteApiEnabled = payload.voteApiEnabled;
+    },
+
+    setMaintenanceMode: (facts, { enabled }) => {
+      facts.maintenanceMode = enabled;
+    },
+
+    toggleFlag: (facts, { flag, enabled }) => {
+      const key = flag as keyof typeof facts;
+      if (key in facts && typeof facts[key] === "boolean") {
+        (facts as Record<string, boolean>)[key] = enabled;
+      }
+    },
+
+    resetAll: (facts) => {
+      facts.chatEnabled = true;
+      facts.searchEnabled = true;
+      facts.playgroundEnabled = true;
+      facts.brandSwitcherEnabled = true;
+      facts.themeSelectorEnabled = true;
+      facts.onboardingToastEnabled = true;
+      facts.versionSelectorEnabled = true;
+      facts.voteApiEnabled = true;
+      facts.maintenanceMode = false;
+    },
+  },
+
+  constraints: {
+    onboardingRequiresBrandSwitcher: {
+      when: (facts) =>
+        facts.onboardingToastEnabled && !facts.brandSwitcherEnabled,
+      require: { type: "ENABLE_BRAND_SWITCHER" },
+    },
+
+    maintenanceWarning: {
+      when: (facts) => facts.maintenanceMode,
+      require: { type: "LOG_MAINTENANCE_WARNING" },
+    },
+  },
+
+  resolvers: {
+    enableBrandSwitcher: {
+      requirement: "ENABLE_BRAND_SWITCHER",
+      resolve: async (req, context) => {
+        context.facts.brandSwitcherEnabled = true;
+      },
+    },
+
+    logMaintenanceWarning: {
+      requirement: "LOG_MAINTENANCE_WARNING",
+      resolve: async (req, context) => {
+        console.warn(
+          "[feature-flags] Maintenance mode is active. Chat, search, playground, and vote API are disabled.",
+        );
+      },
+    },
+  },
+
+  effects: {
+    logChanges: {
+      deps: [
+        "chatEnabled",
+        "searchEnabled",
+        "playgroundEnabled",
+        "brandSwitcherEnabled",
+        "themeSelectorEnabled",
+        "onboardingToastEnabled",
+        "versionSelectorEnabled",
+        "voteApiEnabled",
+        "maintenanceMode",
+      ],
+      run: (facts, prev) => {
+        if (!prev) {
+          return;
+        }
+
+        const flags = [
+          "chatEnabled",
+          "searchEnabled",
+          "playgroundEnabled",
+          "brandSwitcherEnabled",
+          "themeSelectorEnabled",
+          "onboardingToastEnabled",
+          "versionSelectorEnabled",
+          "voteApiEnabled",
+          "maintenanceMode",
+        ] as const;
+
+        for (const flag of flags) {
+          if (facts[flag] !== prev[flag]) {
+            console.log(
+              `[feature-flags] ${flag}: ${prev[flag]} → ${facts[flag]}`,
+            );
+          }
+        }
+      },
+    },
+  },
+});

package/examples/form-wizard.ts

@@ -0,0 +1,347 @@
+// Example: form-wizard
+// Source: examples/form-wizard/src/form-wizard.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Form Wizard — Directive Modules
+ *
+ * Two-module system demonstrating multi-step form validation,
+ * constraint-driven step advancement, cross-module async email
+ * availability checking, and persistence of draft data.
+ *
+ * - wizard module: step navigation, field data, derivations for per-step
+ *   validity, constraints to advance/submit, resolvers for step transitions.
+ * - validation module: cross-module email availability check using
+ *   crossModuleDeps on the wizard schema.
+ */
+
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
+import { devtoolsPlugin, persistencePlugin } from "@directive-run/core/plugins";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type PlanType = "free" | "pro" | "enterprise";
+
+// ============================================================================
+// Wizard Schema
+// ============================================================================
+
+export const wizardSchema = {
+  facts: {
+    currentStep: t.number(),
+    totalSteps: t.number(),
+    advanceRequested: t.boolean(),
+    email: t.string(),
+    password: t.string(),
+    name: t.string(),
+    company: t.string(),
+    plan: t.string<PlanType>(),
+    newsletter: t.boolean(),
+    submitted: t.boolean(),
+  },
+  derivations: {
+    step0Valid: t.boolean(),
+    step1Valid: t.boolean(),
+    step2Valid: t.boolean(),
+    currentStepValid: t.boolean(),
+    canAdvance: t.boolean(),
+    canGoBack: t.boolean(),
+    progress: t.number(),
+    isLastStep: t.boolean(),
+  },
+  events: {
+    requestAdvance: {},
+    goBack: {},
+    setField: { field: t.string(), value: t.object<unknown>() },
+    reset: {},
+  },
+  requirements: {
+    ADVANCE_STEP: {},
+    SUBMIT_FORM: {},
+  },
+} satisfies ModuleSchema;
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/** Inline step validity check for use in constraints (which only receive facts). */
+function isStepValid(facts: Record<string, unknown>, step: number): boolean {
+  if (step === 0) {
+    return (
+      (facts.email as string).includes("@") &&
+      (facts.password as string).length >= 8
+    );
+  }
+  if (step === 1) {
+    return (facts.name as string).trim().length > 0;
+  }
+  if (step === 2) {
+    return (facts.plan as string) !== "";
+  }
+
+  return false;
+}
+
+// ============================================================================
+// Wizard Module
+// ============================================================================
+
+export const wizardModule = createModule("wizard", {
+  schema: wizardSchema,
+
+  init: (facts) => {
+    facts.currentStep = 0;
+    facts.totalSteps = 3;
+    facts.advanceRequested = false;
+    facts.email = "";
+    facts.password = "";
+    facts.name = "";
+    facts.company = "";
+    facts.plan = "free";
+    facts.newsletter = false;
+    facts.submitted = false;
+  },
+
+  // ============================================================================
+  // Derivations
+  // ============================================================================
+
+  derive: {
+    step0Valid: (facts) => {
+      return facts.email.includes("@") && facts.password.length >= 8;
+    },
+
+    step1Valid: (facts) => {
+      return facts.name.trim().length > 0;
+    },
+
+    step2Valid: (facts) => {
+      return facts.plan !== "";
+    },
+
+    currentStepValid: (facts, derive) => {
+      if (facts.currentStep === 0) {
+        return derive.step0Valid;
+      }
+      if (facts.currentStep === 1) {
+        return derive.step1Valid;
+      }
+      if (facts.currentStep === 2) {
+        return derive.step2Valid;
+      }
+
+      return false;
+    },
+
+    canAdvance: (facts, derive) => {
+      return (
+        derive.currentStepValid && facts.currentStep < facts.totalSteps - 1
+      );
+    },
+
+    canGoBack: (facts) => {
+      return facts.currentStep > 0;
+    },
+
+    progress: (facts) => {
+      return Math.round(((facts.currentStep + 1) / facts.totalSteps) * 100);
+    },
+
+    isLastStep: (facts) => {
+      return facts.currentStep === facts.totalSteps - 1;
+    },
+  },
+
+  // ============================================================================
+  // Events
+  // ============================================================================
+
+  events: {
+    requestAdvance: (facts) => {
+      facts.advanceRequested = true;
+    },
+
+    goBack: (facts) => {
+      if (facts.currentStep > 0) {
+        facts.currentStep = facts.currentStep - 1;
+      }
+    },
+
+    setField: (facts, { field, value }) => {
+      (facts as Record<string, unknown>)[field] = value;
+    },
+
+    reset: (facts) => {
+      facts.currentStep = 0;
+      facts.advanceRequested = false;
+      facts.email = "";
+      facts.password = "";
+      facts.name = "";
+      facts.company = "";
+      facts.plan = "free";
+      facts.newsletter = false;
+      facts.submitted = false;
+    },
+  },
+
+  // ============================================================================
+  // Constraints
+  // ============================================================================
+
+  constraints: {
+    submit: {
+      priority: 60,
+      when: (facts) => {
+        const isLastStep = facts.currentStep === facts.totalSteps - 1;
+        const stepValid = isStepValid(facts, facts.currentStep);
+
+        return facts.advanceRequested && isLastStep && stepValid;
+      },
+      require: { type: "SUBMIT_FORM" },
+    },
+
+    advance: {
+      priority: 50,
+      when: (facts) => {
+        const isLastStep = facts.currentStep === facts.totalSteps - 1;
+        const stepValid = isStepValid(facts, facts.currentStep);
+
+        return facts.advanceRequested && !isLastStep && stepValid;
+      },
+      require: { type: "ADVANCE_STEP" },
+    },
+  },
+
+  // ============================================================================
+  // Resolvers
+  // ============================================================================
+
+  resolvers: {
+    advanceStep: {
+      requirement: "ADVANCE_STEP",
+      resolve: async (req, context) => {
+        context.facts.currentStep = context.facts.currentStep + 1;
+        context.facts.advanceRequested = false;
+      },
+    },
+
+    submitForm: {
+      requirement: "SUBMIT_FORM",
+      timeout: 10000,
+      resolve: async (req, context) => {
+        // Simulate API submission
+        await new Promise((resolve) => setTimeout(resolve, 800));
+        context.facts.submitted = true;
+        context.facts.advanceRequested = false;
+      },
+    },
+  },
+});
+
+// ============================================================================
+// Validation Schema
+// ============================================================================
+
+export const validationSchema = {
+  facts: {
+    emailAvailable: t.boolean(),
+    checkingEmail: t.boolean(),
+    emailChecked: t.string(),
+  },
+  derivations: {},
+  events: {},
+  requirements: {
+    CHECK_EMAIL: { email: t.string() },
+  },
+} satisfies ModuleSchema;
+
+// ============================================================================
+// Validation Module
+// ============================================================================
+
+export const validationModule = createModule("validation", {
+  schema: validationSchema,
+
+  crossModuleDeps: { wizard: wizardSchema },
+
+  init: (facts) => {
+    facts.emailAvailable = true;
+    facts.checkingEmail = false;
+    facts.emailChecked = "";
+  },
+
+  // ============================================================================
+  // Constraints
+  // ============================================================================
+
+  constraints: {
+    checkEmail: {
+      when: (facts) => {
+        const email = facts.wizard.email;
+        const checked = facts.self.emailChecked;
+
+        return email.includes("@") && email !== checked;
+      },
+      require: (facts) => ({
+        type: "CHECK_EMAIL",
+        email: facts.wizard.email,
+      }),
+    },
+  },
+
+  // ============================================================================
+  // Resolvers
+  // ============================================================================
+
+  resolvers: {
+    checkEmail: {
+      requirement: "CHECK_EMAIL",
+      resolve: async (req, context) => {
+        context.facts.checkingEmail = true;
+
+        try {
+          // Simulate API availability check
+          await new Promise((resolve) => setTimeout(resolve, 500));
+          context.facts.emailAvailable = req.email !== "taken@test.com";
+          context.facts.emailChecked = req.email;
+        } finally {
+          context.facts.checkingEmail = false;
+        }
+      },
+    },
+  },
+});
+
+// ============================================================================
+// System
+// ============================================================================
+
+export const system = createSystem({
+  modules: {
+    wizard: wizardModule,
+    validation: validationModule,
+  },
+  debug: { runHistory: true },
+  plugins: [
+    devtoolsPlugin({ name: "form-wizard" }),
+    persistencePlugin({
+      storage: localStorage,
+      key: "form-wizard-draft",
+      include: [
+        "wizard::email",
+        "wizard::name",
+        "wizard::company",
+        "wizard::plan",
+        "wizard::currentStep",
+      ],
+    }),
+  ],
+});