@moloodev/editor-sdk 0.0.0-stage → 0.2.0

package/src/commands/react/scope-provider.tsx

@@ -0,0 +1,123 @@
+import { useCallback, useEffect, useMemo, type ReactNode } from "react";
+import type { ClipboardAdapter } from "../clipboard/types";
+import type { ContributionManifest } from "../manifest/types";
+import type { CommandHandler, CommandId } from "../registry/types";
+import { ScopeContext, type ScopeContextValue } from "./scope-context";
+import { useCommandsStore } from "./store";
+
+export type ScopeProviderProps = {
+  manifest: ContributionManifest;
+  /** When false, does not claim active scope. Default true. */
+  active?: boolean;
+  children: ReactNode;
+};
+
+/**
+ * Declares an active contribution scope for the subtree.
+ * Publishes the scope onto the commands store so host-level consumers
+ * (keybindings bridge, etc.) can merge against it.
+ */
+export function ScopeProvider({
+  manifest,
+  active = true,
+  children,
+}: ScopeProviderProps) {
+  const store = useCommandsStore();
+
+  if (manifest.activation != null && manifest.activation !== "exact") {
+    throw new Error(
+      `ScopeProvider manifest "${manifest.id}" must use activation "exact"; got "${manifest.activation}"`,
+    );
+  }
+
+  const resolvedManifest = useMemo(
+    () =>
+      manifest.activation === "exact"
+        ? manifest
+        : { ...manifest, activation: "exact" as const },
+    [manifest],
+  );
+
+  const scopeId = resolvedManifest.id;
+  const stack = store.getUndoStack(scopeId);
+
+  useEffect(() => {
+    store.setScope(resolvedManifest, active);
+    return () => {
+      store.setScope(null, false);
+    };
+  }, [store, resolvedManifest, active]);
+
+  const execute = useCallback(
+    async (id: CommandId, args?: unknown) => {
+      await store.registry.execute(id, args);
+    },
+    [store.registry],
+  );
+
+  const registerHandler = useCallback(
+    (id: CommandId, handler: CommandHandler) => {
+      return store.registry.registerHandler(id, handler);
+    },
+    [store.registry],
+  );
+
+  const hasHandler = useCallback(
+    (id: CommandId) => store.registry.hasHandler(id),
+    [store.registry],
+  );
+
+  const setClipboardAdapter = useCallback(
+    (adapter: ClipboardAdapter | null) => {
+      store.setClipboardAdapter(adapter);
+    },
+    [store],
+  );
+
+  useEffect(() => {
+    const unsubs = [
+      registerHandler("editor.undo", async () => {
+        await store.getUndoStack(scopeId).undo();
+      }),
+      registerHandler("editor.redo", async () => {
+        await store.getUndoStack(scopeId).redo();
+      }),
+    ];
+    return () => {
+      for (const unsub of unsubs) unsub();
+    };
+  }, [registerHandler, store, scopeId]);
+
+  const value = useMemo<ScopeContextValue>(
+    () => ({
+      scopeId,
+      manifest: resolvedManifest,
+      active,
+      stack,
+      execute,
+      registerHandler,
+      hasHandler,
+      setClipboardAdapter,
+    }),
+    [
+      scopeId,
+      resolvedManifest,
+      active,
+      stack,
+      execute,
+      registerHandler,
+      hasHandler,
+      setClipboardAdapter,
+    ],
+  );
+
+  return (
+    <ScopeContext.Provider value={value}>{children}</ScopeContext.Provider>
+  );
+}
+
+export {
+  useOptionalScope,
+  useScope,
+  type ScopeContextValue,
+} from "./scope-context";

package/src/commands/react/store.ts

@@ -0,0 +1,182 @@
+import { createContext, useContext } from "react";
+import type { ClipboardAdapter } from "../clipboard/types";
+import { createUndoStack, type UndoStack } from "../history/stack";
+import type { ContributionManifest } from "../manifest/types";
+import { createCommandRegistry } from "../registry/create";
+import type { ContextKeys, ContextValue } from "../when/types";
+
+export type CommandsStore = {
+  manifests: ContributionManifest[];
+  /** Scope overlay published by ScopeProvider for host-level consumers. */
+  scopeManifest: ContributionManifest | null;
+  activeScopeId: string | null;
+  subscribe: (listener: () => void) => () => void;
+  getSnapshot: () => number;
+  setManifests: (manifests: ContributionManifest[]) => void;
+  setScope: (
+    manifest: ContributionManifest | null,
+    active: boolean,
+  ) => void;
+  registry: ReturnType<typeof createCommandRegistry>;
+  getUndoStack: (scopeId: string) => UndoStack;
+  replaceUndoStack: (scopeId: string, stack: UndoStack | null) => void;
+  setClipboardAdapter: (adapter: ClipboardAdapter | null) => void;
+  getClipboardAdapter: () => ClipboardAdapter | null;
+  getContext: () => ContextKeys;
+  setContext: (partial: ContextKeys) => void;
+  clearContext: (keys?: readonly string[]) => void;
+};
+
+function wrapUndoStack(inner: UndoStack, emit: () => void): UndoStack {
+  return {
+    push(command) {
+      inner.push(command);
+      emit();
+    },
+    async undo() {
+      const ok = await inner.undo();
+      emit();
+      return ok;
+    },
+    async redo() {
+      const ok = await inner.redo();
+      emit();
+      return ok;
+    },
+    canUndo() {
+      return inner.canUndo();
+    },
+    canRedo() {
+      return inner.canRedo();
+    },
+    clear() {
+      inner.clear();
+      emit();
+    },
+  };
+}
+
+export function createCommandsStore(
+  initialManifests: ContributionManifest[],
+): CommandsStore {
+  let manifests = initialManifests;
+  let scopeManifest: ContributionManifest | null = null;
+  let activeScopeId: string | null = null;
+  let version = 0;
+  const listeners = new Set<() => void>();
+  const registry = createCommandRegistry();
+  const undoStacks = new Map<string, UndoStack>();
+  let clipboardAdapter: ClipboardAdapter | null = null;
+  let context: Record<string, ContextValue> = {};
+
+  const emit = () => {
+    version += 1;
+    for (const listener of listeners) listener();
+  };
+
+  return {
+    get manifests() {
+      return manifests;
+    },
+    get scopeManifest() {
+      return scopeManifest;
+    },
+    get activeScopeId() {
+      return activeScopeId;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot() {
+      return version;
+    },
+    setManifests(next) {
+      manifests = next;
+      emit();
+    },
+    setScope(manifest, active) {
+      scopeManifest = manifest;
+      activeScopeId = active && manifest ? manifest.id : null;
+      emit();
+    },
+    registry,
+    getUndoStack(scopeId) {
+      let stack = undoStacks.get(scopeId);
+      if (!stack) {
+        stack = wrapUndoStack(createUndoStack(), emit);
+        undoStacks.set(scopeId, stack);
+      }
+      return stack;
+    },
+    replaceUndoStack(scopeId, stack) {
+      if (!stack) {
+        undoStacks.delete(scopeId);
+        emit();
+        return;
+      }
+      undoStacks.set(scopeId, wrapUndoStack(stack, emit));
+      emit();
+    },
+    setClipboardAdapter(adapter) {
+      clipboardAdapter = adapter;
+    },
+    getClipboardAdapter() {
+      return clipboardAdapter;
+    },
+    getContext() {
+      return context;
+    },
+    setContext(partial) {
+      let changed = false;
+      const next = { ...context };
+      for (const [key, value] of Object.entries(partial)) {
+        if (value === undefined) {
+          if (key in next) {
+            delete next[key];
+            changed = true;
+          }
+          continue;
+        }
+        if (next[key] !== value) {
+          next[key] = value;
+          changed = true;
+        }
+      }
+      if (!changed) return;
+      context = next;
+      emit();
+    },
+    clearContext(keys) {
+      if (keys == null) {
+        if (Object.keys(context).length === 0) return;
+        context = {};
+        emit();
+        return;
+      }
+      let changed = false;
+      const next = { ...context };
+      for (const key of keys) {
+        if (key in next) {
+          delete next[key];
+          changed = true;
+        }
+      }
+      if (!changed) return;
+      context = next;
+      emit();
+    },
+  };
+}
+
+export const CommandsStoreContext = createContext<CommandsStore | null>(null);
+
+export function useCommandsStore(): CommandsStore {
+  const store = useContext(CommandsStoreContext);
+  if (!store) {
+    throw new Error("Commands hooks require <CommandsProvider>");
+  }
+  return store;
+}

package/src/commands/registry/create.ts

@@ -0,0 +1,55 @@
+import type {
+  CommandDefinition,
+  CommandHandler,
+  CommandId,
+} from "./types";
+
+export type CommandRegistry = {
+  get(id: CommandId): CommandDefinition | undefined;
+  list(): CommandDefinition[];
+  define(command: CommandDefinition): void;
+  registerHandler(id: CommandId, handler: CommandHandler): () => void;
+  execute(id: CommandId, args?: unknown): Promise<void>;
+  hasHandler(id: CommandId): boolean;
+};
+
+export function createCommandRegistry(): CommandRegistry {
+  const definitions = new Map<CommandId, CommandDefinition>();
+  const handlers = new Map<CommandId, CommandHandler>();
+
+  return {
+    get(id) {
+      return definitions.get(id);
+    },
+    list() {
+      return [...definitions.values()];
+    },
+    define(command) {
+      const existing = definitions.get(command.id);
+      if (existing && existing.sourceId !== command.sourceId) {
+        throw new Error(
+          `Command "${command.id}" already defined by "${existing.sourceId}"`,
+        );
+      }
+      definitions.set(command.id, command);
+    },
+    registerHandler(id, handler) {
+      handlers.set(id, handler);
+      return () => {
+        if (handlers.get(id) === handler) {
+          handlers.delete(id);
+        }
+      };
+    },
+    async execute(id, args) {
+      const handler = handlers.get(id);
+      if (!handler) {
+        throw new Error(`No handler registered for command "${id}"`);
+      }
+      await handler(args);
+    },
+    hasHandler(id) {
+      return handlers.has(id);
+    },
+  };
+}

package/src/commands/registry/types.ts

@@ -0,0 +1,12 @@
+export type CommandId = string;
+
+export type CommandHandler = (args?: unknown) => void | Promise<void>;
+
+export type CommandDefinition = {
+  id: CommandId;
+  title: string;
+  /** Palette / menu grouping label. */
+  group?: string;
+  /** Manifest that contributed this command. */
+  sourceId: string;
+};

package/src/commands/when/evaluate.ts

@@ -0,0 +1,80 @@
+import type { ContextKeys, ContextValue, WhenExpr } from "./types";
+
+function readKey(ctx: ContextKeys, name: string): ContextValue {
+  return ctx[name];
+}
+
+function isTruthy(value: ContextValue): boolean {
+  if (value === undefined) return false;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value !== 0;
+  return value.length > 0;
+}
+
+function asNumber(value: ContextValue): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+  }
+  if (typeof value === "boolean") return value ? 1 : 0;
+  return null;
+}
+
+function valuesEqual(left: ContextValue, right: ContextValue): boolean {
+  if (left === undefined || right === undefined) {
+    return left === right;
+  }
+  if (typeof left === typeof right) {
+    return left === right;
+  }
+  // Loose compare across string/number/boolean for manifest ergonomics.
+  return String(left) === String(right);
+}
+
+function evalValue(expr: WhenExpr, ctx: ContextKeys): ContextValue {
+  switch (expr.kind) {
+    case "literal":
+      return expr.value;
+    case "key":
+      return readKey(ctx, expr.name);
+    case "unary":
+      return !isTruthy(evalValue(expr.arg, ctx));
+    case "binary": {
+      if (expr.op === "&&") {
+        const left = evalValue(expr.left, ctx);
+        if (!isTruthy(left)) return false;
+        return isTruthy(evalValue(expr.right, ctx));
+      }
+      if (expr.op === "||") {
+        const left = evalValue(expr.left, ctx);
+        if (isTruthy(left)) return true;
+        return isTruthy(evalValue(expr.right, ctx));
+      }
+      if (expr.op === "==") {
+        return valuesEqual(evalValue(expr.left, ctx), evalValue(expr.right, ctx));
+      }
+      if (expr.op === "!=") {
+        return !valuesEqual(evalValue(expr.left, ctx), evalValue(expr.right, ctx));
+      }
+      const ln = asNumber(evalValue(expr.left, ctx));
+      const rn = asNumber(evalValue(expr.right, ctx));
+      if (ln == null || rn == null) return false;
+      switch (expr.op) {
+        case "<":
+          return ln < rn;
+        case "<=":
+          return ln <= rn;
+        case ">":
+          return ln > rn;
+        case ">=":
+          return ln >= rn;
+      }
+    }
+  }
+}
+
+/** Evaluate a parsed when expression against a context key bag. */
+export function evaluateWhen(expr: WhenExpr, ctx: ContextKeys): boolean {
+  return isTruthy(evalValue(expr, ctx));
+}

package/src/commands/when/index.ts

@@ -0,0 +1,19 @@
+export { parseWhen } from "./parse";
+export { evaluateWhen } from "./evaluate";
+export { validateWhenClause, type WhenValidationIssue } from "./validate";
+export {
+  WhenParseError,
+  type ContextKeys,
+  type ContextValue,
+  type WhenExpr,
+} from "./types";
+
+import { parseWhen } from "./parse";
+import { evaluateWhen } from "./evaluate";
+import type { ContextKeys } from "./types";
+
+/** Parse + evaluate in one step. Throws WhenParseError if the clause is invalid. */
+export function isWhenEnabled(source: string | undefined, ctx: ContextKeys): boolean {
+  if (source == null || source.trim() === "") return true;
+  return evaluateWhen(parseWhen(source), ctx);
+}