@moloodev/editor-sdk 0.0.0-stage → 0.1.0

package/src/commands/manifest/merge.ts

@@ -0,0 +1,215 @@
+import { claimKeybindings, validateKeybindings } from "../keys/validate";
+import type {
+  ContributionManifest,
+  ManifestActivation,
+  MenuContribution,
+  MenuNode,
+  MergedContributions,
+} from "./types";
+
+function resolveActivation(
+  manifest: ContributionManifest,
+): ManifestActivation {
+  return manifest.activation ?? "always";
+}
+
+/**
+ * Resolve which manifests apply given the active scope.
+ * - `"always"` (default): always
+ * - `"any"`: when some scope is active
+ * - `"exact"`: when activeScopeId === manifest.id
+ */
+export function selectManifests(
+  manifests: readonly ContributionManifest[],
+  activeScopeId: string | null,
+): ContributionManifest[] {
+  return manifests.filter((manifest) => {
+    const activation = resolveActivation(manifest);
+    if (activation === "always") return true;
+    if (activation === "any") return activeScopeId != null;
+    return activeScopeId != null && manifest.id === activeScopeId;
+  });
+}
+
+/** Default leaf group — scope-specific appends land after common blocks. */
+export const DEFAULT_MENU_GROUP = "9_default";
+
+function compareMenuSiblings(a: MenuNode, b: MenuNode): number {
+  const groupCmp = (a.group ?? DEFAULT_MENU_GROUP).localeCompare(
+    b.group ?? DEFAULT_MENU_GROUP,
+  );
+  if (groupCmp !== 0) return groupCmp;
+  return a.order - b.order || a.label.localeCompare(b.label);
+}
+
+function buildMenuTree(
+  menus: MenuContribution[],
+  titleByCommand: Map<string, string>,
+): MenuNode[] {
+  type Mutable = {
+    id: string;
+    segment: string;
+    label: string;
+    order: number;
+    group?: string;
+    shortcut?: string;
+    commandId?: string;
+    when?: string;
+    children: Map<string, Mutable>;
+  };
+
+  const roots = new Map<string, Mutable>();
+
+  const sorted = [...menus].sort((a, b) => {
+    const pathCmp = a.path.join("\0").localeCompare(b.path.join("\0"));
+    if (pathCmp !== 0) return pathCmp;
+    const groupCmp = (a.group ?? DEFAULT_MENU_GROUP).localeCompare(
+      b.group ?? DEFAULT_MENU_GROUP,
+    );
+    if (groupCmp !== 0) return groupCmp;
+    return (a.order ?? 0) - (b.order ?? 0);
+  });
+
+  for (const item of sorted) {
+    if (item.path.length === 0) {
+      throw new Error(`Menu for "${item.commandId}" has empty path`);
+    }
+    let level = roots;
+    for (let i = 0; i < item.path.length; i++) {
+      const segment = item.path[i]!;
+      const id = item.path.slice(0, i + 1).join("/");
+      let current = level.get(segment);
+      if (!current) {
+        current = {
+          id,
+          segment,
+          label: segment,
+          order: item.order ?? 0,
+          children: new Map(),
+        };
+        level.set(segment, current);
+      }
+      const isLeaf = i === item.path.length - 1;
+      if (isLeaf) {
+        if (current.commandId && current.commandId !== item.commandId) {
+          throw new Error(
+            `Menu path "${id}" already bound to "${current.commandId}"`,
+          );
+        }
+        current.commandId = item.commandId;
+        current.group = item.group ?? DEFAULT_MENU_GROUP;
+        current.shortcut = item.shortcut;
+        current.when = item.when;
+        current.label =
+          item.label ?? titleByCommand.get(item.commandId) ?? segment;
+        if (item.order != null) current.order = item.order;
+      } else if (item.order != null && current.children.size === 0) {
+        current.order = Math.min(current.order, item.order);
+      }
+      level = current.children;
+    }
+  }
+
+  const SEGMENT_META: Record<string, { label: string; order: number }> = {
+    file: { label: "파일", order: 10 },
+    edit: { label: "편집", order: 30 },
+    insert: { label: "삽입", order: 35 },
+    format: { label: "포맷", order: 35 },
+    asset: { label: "애셋", order: 36 },
+    view: { label: "보기", order: 40 },
+    canvas: { label: "캔버스", order: 50 },
+  };
+
+  function toNodes(map: Map<string, Mutable>): MenuNode[] {
+    return [...map.values()]
+      .map((n) => {
+        const meta = SEGMENT_META[n.segment];
+        const children = toNodes(n.children);
+        const label =
+          children.length > 0
+            ? (meta?.label ?? n.label)
+            : n.label;
+        const order = meta?.order ?? n.order;
+        return {
+          id: n.id,
+          segment: n.segment,
+          label,
+          order,
+          group: children.length > 0 ? undefined : n.group,
+          shortcut: children.length > 0 ? undefined : n.shortcut,
+          when: children.length > 0 ? undefined : n.when,
+          commandId: children.length > 0 ? undefined : n.commandId,
+          children,
+        };
+      })
+      .sort(compareMenuSiblings);
+  }
+
+  return toNodes(roots);
+}
+
+/**
+ * Merge selected manifests. Duplicate command ids or key overrides throw.
+ */
+export function mergeManifests(
+  manifests: readonly ContributionManifest[],
+): MergedContributions {
+  const commands: MergedContributions["commands"] = [];
+  const menus: MenuContribution[] = [];
+  const keybindings: MergedContributions["keybindings"] = [];
+  const seenCommands = new Map<string, string>();
+  const claimedKeys = new Map<string, string>();
+
+  for (const manifest of manifests) {
+    for (const command of manifest.commands ?? []) {
+      const prior = seenCommands.get(command.id);
+      if (prior) {
+        throw new Error(
+          `Command "${command.id}" redeclared by "${manifest.id}" (already from "${prior}")`,
+        );
+      }
+      seenCommands.set(command.id, manifest.id);
+      commands.push({
+        id: command.id,
+        title: command.title,
+        group: command.group,
+        when: command.when,
+        sourceId: manifest.id,
+        activation: resolveActivation(manifest),
+      });
+    }
+
+    for (const menu of manifest.menus ?? []) {
+      menus.push(menu);
+    }
+
+    const bindings = manifest.keybindings ?? [];
+    const result = validateKeybindings(bindings, claimedKeys);
+    if (!result.ok) {
+      const first = result.conflicts[0]!;
+      throw new Error(
+        `Keybinding conflict in "${manifest.id}": ${first.key} → ${first.commandId} (${first.reason})`,
+      );
+    }
+    claimKeybindings(bindings, claimedKeys);
+    keybindings.push(...bindings);
+  }
+
+  const titleByCommand = new Map(
+    commands.map((command) => [command.id, command.title]),
+  );
+
+  return {
+    commands,
+    menus,
+    keybindings,
+    menuTree: buildMenuTree(menus, titleByCommand),
+  };
+}
+
+export function mergeActiveContributions(
+  manifests: readonly ContributionManifest[],
+  activeScopeId: string | null,
+): MergedContributions {
+  return mergeManifests(selectManifests(manifests, activeScopeId));
+}

package/src/commands/manifest/types.ts

@@ -0,0 +1,113 @@
+import type { CommandId } from "../registry/types";
+
+export type MenuContribution = {
+  /**
+   * Full menu path. Intermediate segments are submenus; the last segment is
+   * the item. Hosts append under existing paths (e.g. `["edit","group"]`)
+   * or add top-level menus (e.g. `["canvas","frame"]`).
+   */
+  path: string[];
+  commandId: CommandId;
+  order?: number;
+  /**
+   * Sibling group id (VS Code-style). Sorted lexicographically; hosts insert
+   * a separator when the group changes. Prefer prefixes like `1_history`,
+   * `2_clipboard`, `9_default`.
+   */
+  group?: string;
+  /** Optional display label; defaults to command title when rendering. */
+  label?: string;
+  /**
+   * Display-only chord (e.g. `Mod+C`). Shown in menus/palette hints but not
+   * registered as a keybinding — use for native clipboard keys etc.
+   */
+  shortcut?: string;
+  /**
+   * Visibility when-clause. Hosts hide the leaf when false.
+   * Command `when` still gates enablement (disabled).
+   */
+  when?: string;
+};
+
+export type KeybindingContribution = {
+  commandId: CommandId;
+  /** TanStack / Mod-style chord, e.g. `Mod+Z`. */
+  key: string;
+};
+
+export type ConfigurationProperty = {
+  type: "boolean" | "number" | "string";
+  default: boolean | number | string;
+  title: string;
+  description?: string;
+  enum?: string[];
+  minimum?: number;
+  maximum?: number;
+  order?: number;
+};
+
+export type ConfigurationGroup = {
+  id: string;
+  title: string;
+  order?: number;
+  properties: Record<string, ConfigurationProperty>;
+};
+
+/** Omitted → `"always"`. */
+export type ManifestActivation =
+  | "always" // include regardless of scope
+  | "any" // include when some scope is active
+  | "exact"; // include when activeScopeId === manifest.id
+
+export type ContributionManifest = {
+  id: string;
+  activation?: ManifestActivation;
+  commands?: {
+    id: CommandId;
+    title: string;
+    group?: string;
+    /** When-clause; omitted = always available. */
+    when?: string;
+  }[];
+  menus?: MenuContribution[];
+  keybindings?: KeybindingContribution[];
+  /** VS Code–style settings schema contributions. */
+  configuration?: { groups: ConfigurationGroup[] };
+};
+
+export type MergedConfiguration = {
+  groups: ConfigurationGroup[];
+  defaults: Record<string, boolean | number | string>;
+  properties: Map<string, ConfigurationProperty>;
+};
+
+export type MenuNode = {
+  id: string;
+  /** Segment key (last path part). */
+  segment: string;
+  label: string;
+  order: number;
+  /** Present on leaves; used for separator breaks among siblings. */
+  group?: string;
+  commandId?: CommandId;
+  /** Display-only shortcut; see MenuContribution.shortcut. */
+  shortcut?: string;
+  /** Visibility when-clause; see MenuContribution.when. */
+  when?: string;
+  children: MenuNode[];
+};
+
+export type MergedContributions = {
+  commands: {
+    id: CommandId;
+    title: string;
+    group?: string;
+    when?: string;
+    sourceId: string;
+    /** Activation of the contributing manifest (for palette / scope ordering). */
+    activation: ManifestActivation;
+  }[];
+  menus: MenuContribution[];
+  keybindings: KeybindingContribution[];
+  menuTree: MenuNode[];
+};

package/src/commands/manifest/validate-manifest.ts

@@ -0,0 +1,45 @@
+import type { ContributionManifest } from "./types";
+import { contributionManifestSchema } from "./contribution-manifest-schema";
+import { validateWhenClause } from "../when/validate";
+
+function formatZodIssues(error: {
+  issues: { path: PropertyKey[]; message: string }[];
+}): string {
+  return error.issues
+    .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+    .join("; ");
+}
+
+/** Shape validation for contribution manifests. Throws on failure. */
+export function validateManifest(input: unknown): ContributionManifest {
+  const result = contributionManifestSchema.safeParse(input);
+  if (!result.success) {
+    throw new Error(`Invalid contribution manifest: ${formatZodIssues(result.error)}`);
+  }
+
+  const data = result.data;
+  const whenErrors: string[] = [];
+  for (const [index, command] of (data.commands ?? []).entries()) {
+    if (command.when == null) continue;
+    const issues = validateWhenClause(command.when);
+    for (const issue of issues) {
+      whenErrors.push(
+        `commands.${index}.when: ${issue.message} (offset ${issue.offset})`,
+      );
+    }
+  }
+  for (const [index, menu] of (data.menus ?? []).entries()) {
+    if (menu.when == null) continue;
+    const issues = validateWhenClause(menu.when);
+    for (const issue of issues) {
+      whenErrors.push(
+        `menus.${index}.when: ${issue.message} (offset ${issue.offset})`,
+      );
+    }
+  }
+  if (whenErrors.length > 0) {
+    throw new Error(`Invalid contribution manifest: ${whenErrors.join("; ")}`);
+  }
+
+  return data;
+}

package/src/commands/react/context.tsx

@@ -0,0 +1,249 @@
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+import { HotkeysProvider, useHotkey } from "@tanstack/react-hotkeys";
+import { createClipboardRouter } from "../clipboard/router";
+import { mergeActiveConfiguration } from "../manifest/configuration";
+import { mergeActiveContributions } from "../manifest/merge";
+import type {
+  ContributionManifest,
+  MergedConfiguration,
+  MergedContributions,
+} from "../manifest/types";
+import type { CommandHandler, CommandId } from "../registry/types";
+import { normalizeKey } from "../keys/normalize";
+import { isWhenEnabled } from "../when";
+import type { ContextKeys } from "../when/types";
+import { commandsHotkeyDefaults } from "./hotkey-defaults";
+import {
+  CommandsStoreContext,
+  createCommandsStore,
+  useCommandsStore,
+  type CommandsStore,
+} from "./store";
+
+function useStoreVersion(store: CommandsStore): number {
+  return useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot,
+  );
+}
+
+export type CommandsProviderProps = {
+  manifests?: ContributionManifest[];
+  onKeybinding?: (binding: { key: string; commandId: CommandId }) => void;
+  children: ReactNode;
+};
+
+export function CommandsProvider({
+  manifests: initialManifests = [],
+  onKeybinding,
+  children,
+}: CommandsProviderProps) {
+  const storeRef = useRef<CommandsStore | null>(null);
+  if (!storeRef.current) {
+    storeRef.current = createCommandsStore(initialManifests);
+  }
+  const store = storeRef.current;
+
+  useEffect(() => {
+    store.setManifests(initialManifests);
+  }, [store, initialManifests]);
+
+  useEffect(() => {
+    const router = createClipboardRouter(() => store.getClipboardAdapter());
+    return router.attach(document);
+  }, [store]);
+
+  return (
+    <CommandsStoreContext.Provider value={store}>
+      <HotkeysProvider defaultOptions={commandsHotkeyDefaults}>
+        <CommandKeybindingsBridge onKeybinding={onKeybinding} />
+        {children}
+      </HotkeysProvider>
+    </CommandsStoreContext.Provider>
+  );
+}
+
+function CommandKeybindingsBridge({ onKeybinding }: {
+  onKeybinding: CommandsProviderProps["onKeybinding"];
+}) {
+  const merged = useMergedContributions();
+  const { execute } = useCommands();
+
+  return (
+    <>
+      {merged.keybindings.map((binding) => (
+        <Keybinding
+          key={`${binding.commandId}:${binding.key}`}
+          chord={binding.key}
+          commandId={binding.commandId}
+          execute={execute}
+          onKeybinding={onKeybinding}
+        />
+      ))}
+    </>
+  );
+}
+
+function Keybinding({
+  chord,
+  commandId,
+  execute,
+  onKeybinding,
+}: {
+  chord: string;
+  commandId: CommandId;
+  execute: (id: CommandId) => Promise<void>;
+  onKeybinding: CommandsProviderProps["onKeybinding"];
+}) {
+  const registration = keybindingRegistration({ key: chord, commandId }, execute, onKeybinding);
+
+  useHotkey(
+    // Manifest chords are validated at merge time; TanStack types a finite set.
+    chord as Parameters<typeof useHotkey>[0],
+    registration.action,
+    registration.options,
+  );
+  return null;
+}
+
+export function executeKeybinding(
+  binding: { key: string; commandId: CommandId },
+  execute: (id: CommandId) => Promise<void>,
+  onKeybinding?: CommandsProviderProps["onKeybinding"],
+): void {
+  if (onKeybinding) onKeybinding(binding);
+  else void execute(binding.commandId);
+}
+
+export function keybindingRegistration(
+  binding: { key: string; commandId: CommandId },
+  execute: (id: CommandId) => Promise<void>,
+  onKeybinding?: CommandsProviderProps["onKeybinding"],
+) {
+  const key = normalizeKey(binding.key);
+  return {
+    key: binding.key,
+    action: () => executeKeybinding(binding, execute, onKeybinding),
+    options: {
+      preventDefault: true,
+      ignoreInputs: key === "delete" || key === "backspace",
+      meta: { name: binding.commandId, description: binding.commandId },
+    },
+  };
+}
+
+function useMergedManifestList(): ContributionManifest[] {
+  const store = useCommandsStore();
+  useStoreVersion(store);
+  return useMemo(() => {
+    const scope = store.scopeManifest;
+    if (!scope) return store.manifests;
+    const rest = store.manifests.filter((item) => item.id !== scope.id);
+    return [...rest, scope];
+  }, [store, store.manifests, store.scopeManifest, store.getSnapshot()]);
+}
+
+export function useMergedContributions(): MergedContributions {
+  const store = useCommandsStore();
+  useStoreVersion(store);
+  const manifests = useMergedManifestList();
+  return useMemo(
+    () => mergeActiveContributions(manifests, store.activeScopeId),
+    [manifests, store.activeScopeId],
+  );
+}
+
+export function useMergedConfiguration(): MergedConfiguration {
+  const store = useCommandsStore();
+  useStoreVersion(store);
+  const manifests = useMergedManifestList();
+  return useMemo(
+    () => mergeActiveConfiguration(manifests, store.activeScopeId),
+    [manifests, store.activeScopeId],
+  );
+}
+
+export function useCommands() {
+  const store = useCommandsStore();
+  useStoreVersion(store);
+
+  const merged = useMergedContributions();
+
+  useEffect(() => {
+    for (const command of merged.commands) {
+      store.registry.define({
+        id: command.id,
+        title: command.title,
+        group: command.group,
+        sourceId: command.sourceId,
+      });
+    }
+  }, [merged.commands, store.registry]);
+
+  const commandsById = useMemo(() => {
+    const map = new Map(merged.commands.map((command) => [command.id, command]));
+    return map;
+  }, [merged.commands]);
+
+  const isAvailable = useCallback(
+    (id: CommandId) => {
+      const command = commandsById.get(id);
+      return isWhenEnabled(command?.when, store.getContext());
+    },
+    [commandsById, store],
+  );
+
+  const execute = useCallback(
+    async (id: CommandId, args?: unknown) => {
+      if (!isAvailable(id)) return;
+      await store.registry.execute(id, args);
+    },
+    [isAvailable, store.registry],
+  );
+
+  const registerHandler = useCallback(
+    (id: CommandId, handler: CommandHandler) => {
+      return store.registry.registerHandler(id, handler);
+    },
+    [store.registry],
+  );
+
+  const setContext = useCallback(
+    (partial: ContextKeys) => {
+      store.setContext(partial);
+    },
+    [store],
+  );
+
+  const clearContext = useCallback(
+    (keys?: readonly string[]) => {
+      store.clearContext(keys);
+    },
+    [store],
+  );
+
+  return {
+    commands: merged.commands,
+    menus: merged.menus,
+    menuTree: merged.menuTree,
+    keybindings: merged.keybindings,
+    activeScopeId: store.activeScopeId,
+    execute,
+    registerHandler,
+    getUndoStack: store.getUndoStack,
+    replaceUndoStack: store.replaceUndoStack,
+    setClipboardAdapter: store.setClipboardAdapter,
+    getContext: store.getContext,
+    setContext,
+    clearContext,
+    isAvailable,
+  };
+}

package/src/commands/react/hotkey-defaults.ts

@@ -0,0 +1,11 @@
+import type { HotkeysProviderProps } from "@tanstack/react-hotkeys";
+
+/** Shared defaults for moloo product shells. */
+export const commandsHotkeyDefaults: NonNullable<
+  HotkeysProviderProps["defaultOptions"]
+> = {
+  hotkey: {
+    preventDefault: true,
+    ignoreInputs: false,
+  },
+};

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

@@ -0,0 +1,31 @@
+import { createContext, useContext } from "react";
+import type { ClipboardAdapter } from "../clipboard/types";
+import type { UndoStack } from "../history/stack";
+import type { ContributionManifest } from "../manifest/types";
+import type { CommandHandler, CommandId } from "../registry/types";
+
+export type ScopeContextValue = {
+  scopeId: string;
+  manifest: ContributionManifest;
+  active: boolean;
+  stack: UndoStack;
+  execute: (id: CommandId, args?: unknown) => Promise<void>;
+  registerHandler: (id: CommandId, handler: CommandHandler) => () => void;
+  hasHandler: (id: CommandId) => boolean;
+  setClipboardAdapter: (adapter: ClipboardAdapter | null) => void;
+};
+
+export const ScopeContext = createContext<ScopeContextValue | null>(null);
+
+export function useScope(): ScopeContextValue {
+  const scope = useContext(ScopeContext);
+  if (!scope) {
+    throw new Error("useScope requires <ScopeProvider>");
+  }
+  return scope;
+}
+
+/** Returns null outside a scope (e.g. settings host above the page). */
+export function useOptionalScope(): ScopeContextValue | null {
+  return useContext(ScopeContext);
+}