@moloodev/editor-sdk 0.0.0-stage → 0.1.0

package/src/commands/icons/catalog.ts

@@ -0,0 +1,172 @@
+import type { ComponentType } from "react";
+import { parseTablerIconUri } from "../manifest/editor-document";
+import {
+  IconArrowBackUp,
+  IconArrowForwardUp,
+  IconBold,
+  IconClick,
+  IconClipboard,
+  IconCode,
+  IconColumnInsertLeft,
+  IconColumnInsertRight,
+  IconCopy,
+  IconDownload,
+  IconEraser,
+  IconFileImport,
+  IconFilePlus,
+  IconFileText,
+  IconFolderOpen,
+  IconH1,
+  IconH2,
+  IconH3,
+  IconHighlight,
+  IconHandMove,
+  IconHierarchy,
+  IconLayout,
+  IconHistory,
+  IconItalic,
+  IconLayersSubtract,
+  IconLayoutDashboard,
+  IconLayoutGrid,
+  IconLink,
+  IconList,
+  IconListCheck,
+  IconListNumbers,
+  IconLock,
+  IconLockOpen,
+  IconMarkdown,
+  IconMaximize,
+  IconMenu2,
+  IconMessageCircle,
+  IconMessages,
+  IconMinus,
+  IconMusic,
+  IconPackage,
+  IconPencil,
+  IconPhoto,
+  IconPlus,
+  IconPointer,
+  IconQuote,
+  IconRestore,
+  IconRowInsertBottom,
+  IconRowInsertTop,
+  IconScissors,
+  IconShape,
+  IconSparkles,
+  IconStrikethrough,
+  IconTable,
+  IconTimelineEvent,
+  IconTrash,
+  IconWorld,
+  IconWorldOff,
+  IconX,
+  IconZoomIn,
+  IconZoomOut,
+  type IconProps,
+} from "@tabler/icons-react";
+
+export type EditorIconComponent = ComponentType<IconProps>;
+
+/** Host-resolved Tabler icon names. */
+export const EDITOR_ICON_CATALOG = {
+  menu: IconMenu2,
+  "arrow-back-up": IconArrowBackUp,
+  restore: IconRestore,
+  "arrow-forward-up": IconArrowForwardUp,
+  scissors: IconScissors,
+  copy: IconCopy,
+  clipboard: IconClipboard,
+  "file-plus": IconFilePlus,
+  "file-text": IconFileText,
+  plus: IconPlus,
+  "folder-open": IconFolderOpen,
+  "file-import": IconFileImport,
+  download: IconDownload,
+  trash: IconTrash,
+  x: IconX,
+  history: IconHistory,
+  lock: IconLock,
+  "lock-open": IconLockOpen,
+  pointer: IconPointer,
+  "hand-move": IconHandMove,
+  click: IconClick,
+  "layers-subtract": IconLayersSubtract,
+  maximize: IconMaximize,
+  "zoom-in": IconZoomIn,
+  "zoom-out": IconZoomOut,
+  hierarchy: IconHierarchy,
+  layout: IconLayout,
+  table: IconTable,
+  "row-insert-top": IconRowInsertTop,
+  "row-insert-bottom": IconRowInsertBottom,
+  "column-insert-left": IconColumnInsertLeft,
+  "column-insert-right": IconColumnInsertRight,
+  eraser: IconEraser,
+  markdown: IconMarkdown,
+  bold: IconBold,
+  italic: IconItalic,
+  strikethrough: IconStrikethrough,
+  highlight: IconHighlight,
+  heading: IconH1,
+  heading2: IconH2,
+  heading3: IconH3,
+  list: IconList,
+  "list-numbers": IconListNumbers,
+  "list-check": IconListCheck,
+  quote: IconQuote,
+  code: IconCode,
+  link: IconLink,
+  photo: IconPhoto,
+  minus: IconMinus,
+  shape: IconShape,
+  "layout-grid": IconLayoutGrid,
+  "timeline-event": IconTimelineEvent,
+  music: IconMusic,
+  pencil: IconPencil,
+  messages: IconMessages,
+  sparkles: IconSparkles,
+  "message-circle": IconMessageCircle,
+  "layout-dashboard": IconLayoutDashboard,
+  package: IconPackage,
+  world: IconWorld,
+  "world-off": IconWorldOff,
+} as const satisfies Record<string, EditorIconComponent>;
+
+export type EditorIconName = keyof typeof EDITOR_ICON_CATALOG;
+
+const COMMAND_ICON_FALLBACK: Partial<Record<string, EditorIconName>> = {
+  "editor.undo": "arrow-back-up",
+  "editor.redo": "arrow-forward-up",
+  "editor.cut": "scissors",
+  "editor.copy": "copy",
+  "editor.paste": "clipboard",
+  "editor.delete": "trash",
+  "editor.new": "file-plus",
+  "editor.open": "folder-open",
+  "editor.import": "file-import",
+  "editor.download": "download",
+  "bundle.add": "plus",
+  "bundle.restore": "restore",
+  "bundle.delete": "x",
+  "bundle.access": "world",
+  "bundle.confirm": "package",
+};
+
+function isEditorIconName(name: string): name is EditorIconName {
+  return Object.hasOwn(EDITOR_ICON_CATALOG, name);
+}
+
+export function resolveEditorIcon(
+  name?: string,
+  commandId?: string,
+): EditorIconComponent | null {
+  const parsed = name ? parseTablerIconUri(name) : null;
+  if (parsed && isEditorIconName(parsed)) {
+    return EDITOR_ICON_CATALOG[parsed];
+  }
+  if (commandId) {
+    const fallback = COMMAND_ICON_FALLBACK[commandId];
+    if (fallback) return EDITOR_ICON_CATALOG[fallback];
+  }
+  return null;
+}

package/src/commands/index.ts

@@ -0,0 +1,100 @@
+export type {
+  CommandDefinition,
+  CommandHandler,
+  CommandId,
+} from "./registry/types";
+export {
+  createCommandRegistry,
+  type CommandRegistry,
+} from "./registry/create";
+
+export type {
+  ConfigurationGroup,
+  ConfigurationProperty,
+  ContributionManifest,
+  KeybindingContribution,
+  ManifestActivation,
+  MenuContribution,
+  MenuNode,
+  MergedConfiguration,
+  MergedContributions,
+} from "./manifest/types";
+export { contributionManifestSchema } from "./manifest/contribution-manifest-schema";
+export { validateManifest } from "./manifest/validate-manifest";
+export {
+  DEFAULT_MENU_GROUP,
+  mergeActiveContributions,
+  mergeManifests,
+  selectManifests,
+} from "./manifest/merge";
+export {
+  mergeActiveConfiguration,
+  mergeConfiguration,
+} from "./manifest/configuration";
+export { SHELL_SERVICE_MANIFEST_ID } from "./manifest/ids";
+
+export {
+  normalizeKey,
+  keyToKbdTokens,
+} from "./keys/normalize";
+export { displayShortcutsByCommand } from "./keys/display";
+export {
+  BROWSER_RESERVED_KEYS,
+  CLIPBOARD_FORBIDDEN_KEYS,
+  isBrowserReservedKey,
+  isClipboardForbiddenKey,
+} from "./keys/reserved";
+export {
+  validateKeybindings,
+  claimKeybindings,
+  type KeybindingConflict,
+} from "./keys/validate";
+
+export {
+  createUndoStack,
+  type UndoCommand,
+  type UndoStack,
+} from "./history/stack";
+
+export {
+  createClipboardRouter,
+  type ClipboardRouter,
+} from "./clipboard/router";
+export type {
+  ClipboardAdapter,
+  ClipboardPayload,
+  ClipboardSelection,
+} from "./clipboard/types";
+
+export {
+  CommandsProvider,
+  useCommands,
+  useMergedConfiguration,
+  useMergedContributions,
+  type CommandsProviderProps,
+} from "./react/context";
+export {
+  ScopeProvider,
+  useOptionalScope,
+  useScope,
+  type ScopeContextValue,
+  type ScopeProviderProps,
+} from "./react/scope-provider";
+export { commandsHotkeyDefaults } from "./react/hotkey-defaults";
+
+export {
+  parseWhen,
+  evaluateWhen,
+  validateWhenClause,
+  isWhenEnabled,
+  WhenParseError,
+  type ContextKeys,
+  type ContextValue,
+  type WhenExpr,
+  type WhenValidationIssue,
+} from "./when";
+
+export { HotkeysProvider, useHotkeyRegistrations } from "@tanstack/react-hotkeys";
+
+export { defineEditorManifest, parseTablerIconUri, type EditorManifest, type EditorManifestInput, type EditorTemplate } from "./manifest/editor-document";
+export { EDITOR_ICON_CATALOG, resolveEditorIcon, type EditorIconComponent, type EditorIconName } from "./icons/catalog";

package/src/commands/keys/display.ts

@@ -0,0 +1,16 @@
+import type { CommandId } from "../registry/types";
+
+/** Display chord per command: registered keybindings win over menu-only hints. */
+export function displayShortcutsByCommand(
+  keybindings: readonly { commandId: CommandId; key: string }[],
+  menus: readonly { commandId: CommandId; shortcut?: string }[],
+): Map<CommandId, string> {
+  const map = new Map<CommandId, string>();
+  for (const menu of menus) {
+    if (menu.shortcut) map.set(menu.commandId, menu.shortcut);
+  }
+  for (const binding of keybindings) {
+    map.set(binding.commandId, binding.key);
+  }
+  return map;
+}

package/src/commands/keys/normalize.ts

@@ -0,0 +1,55 @@
+/** Normalize Mod-style chords for comparison (case-insensitive, sorted mods). */
+export function normalizeKey(key: string): string {
+  const parts = key
+    .split("+")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (parts.length === 0) {
+    return "";
+  }
+  const mods = new Set<string>();
+  let main = "";
+  for (const part of parts) {
+    const lower = part.toLowerCase();
+    if (
+      lower === "mod" ||
+      lower === "meta" ||
+      lower === "cmd" ||
+      lower === "command" ||
+      lower === "ctrl" ||
+      lower === "control" ||
+      lower === "alt" ||
+      lower === "option" ||
+      lower === "shift"
+    ) {
+      if (lower === "meta" || lower === "cmd" || lower === "command") {
+        mods.add("mod");
+      } else if (lower === "control") {
+        mods.add("ctrl");
+      } else if (lower === "option") {
+        mods.add("alt");
+      } else {
+        mods.add(lower === "mod" ? "mod" : lower);
+      }
+    } else {
+      main = lower.length === 1 ? lower.toUpperCase() : lower;
+    }
+  }
+  const orderedMods = ["mod", "ctrl", "alt", "shift"].filter((m) =>
+    mods.has(m),
+  );
+  return [...orderedMods, main].filter(Boolean).join("+");
+}
+
+/** Convert `Mod+K` to UI kbd tokens like `["cmd","K"]`. */
+export function keyToKbdTokens(key: string): string[] {
+  const normalized = normalizeKey(key);
+  if (!normalized) return [];
+  return normalized.split("+").map((part) => {
+    if (part === "mod") return "cmd";
+    if (part === "ctrl") return "ctrl";
+    if (part === "alt") return "alt";
+    if (part === "shift") return "shift";
+    return part;
+  });
+}

package/src/commands/keys/reserved.ts

@@ -0,0 +1,62 @@
+import { normalizeKey } from "./normalize";
+
+/**
+ * Browser / OS escape-hatch chords. Nothing in moloo may register these
+ * as command keybindings.
+ */
+const BROWSER_RESERVED_RAW = [
+  // Zoom (a11y)
+  "Mod+=",
+  "Mod+-",
+  "Mod+0",
+  "Mod+Plus",
+  "Mod+Minus",
+  // Address bar / chrome focus
+  "Mod+L",
+  "F6",
+  "Alt+D",
+  // Tabs / windows
+  "Mod+W",
+  "Mod+Shift+W",
+  "Mod+T",
+  "Mod+N",
+  "Mod+Shift+T",
+  "Mod+1",
+  "Mod+2",
+  "Mod+3",
+  "Mod+4",
+  "Mod+5",
+  "Mod+6",
+  "Mod+7",
+  "Mod+8",
+  "Mod+9",
+  // Reload
+  "Mod+R",
+  "Mod+Shift+R",
+  "F5",
+  // Quit
+  "Mod+Q",
+  // Open local file (browser)
+  "Mod+O",
+  // Save page / some browser sidebar toggles — auto-save policy; leave alone
+  "Mod+S",
+] as const;
+
+/** Clipboard chords — not keybindings; handled via native clipboard events. */
+const CLIPBOARD_FORBIDDEN_RAW = ["Mod+C", "Mod+X", "Mod+V"] as const;
+
+export const BROWSER_RESERVED_KEYS = new Set(
+  BROWSER_RESERVED_RAW.map(normalizeKey),
+);
+
+export const CLIPBOARD_FORBIDDEN_KEYS = new Set(
+  CLIPBOARD_FORBIDDEN_RAW.map(normalizeKey),
+);
+
+export function isBrowserReservedKey(key: string): boolean {
+  return BROWSER_RESERVED_KEYS.has(normalizeKey(key));
+}
+
+export function isClipboardForbiddenKey(key: string): boolean {
+  return CLIPBOARD_FORBIDDEN_KEYS.has(normalizeKey(key));
+}

package/src/commands/keys/validate.ts

@@ -0,0 +1,77 @@
+import type { KeybindingContribution } from "../manifest/types";
+import { normalizeKey } from "./normalize";
+import {
+  isBrowserReservedKey,
+  isClipboardForbiddenKey,
+} from "./reserved";
+
+export type KeybindingConflict = {
+  key: string;
+  commandId: string;
+  reason: string;
+};
+
+/**
+ * Validate keybindings against browser reserved, clipboard-forbidden,
+ * and duplicate chords. Higher-layer bindings (already claimed) cannot
+ * be overridden by later manifests.
+ */
+export function validateKeybindings(
+  keybindings: KeybindingContribution[],
+  claimed: ReadonlyMap<string, string> = new Map(),
+): { ok: true } | { ok: false; conflicts: KeybindingConflict[] } {
+  const conflicts: KeybindingConflict[] = [];
+  const local = new Map<string, string>();
+
+  for (const binding of keybindings) {
+    const key = normalizeKey(binding.key);
+    if (!key) {
+      conflicts.push({
+        key: binding.key,
+        commandId: binding.commandId,
+        reason: "Empty keybinding",
+      });
+      continue;
+    }
+    if (isBrowserReservedKey(key)) {
+      conflicts.push({
+        key: binding.key,
+        commandId: binding.commandId,
+        reason: "Browser-reserved key",
+      });
+      continue;
+    }
+    if (isClipboardForbiddenKey(key)) {
+      conflicts.push({
+        key: binding.key,
+        commandId: binding.commandId,
+        reason: "Clipboard keys use native events, not keybindings",
+      });
+      continue;
+    }
+    const prior = claimed.get(key) ?? local.get(key);
+    if (prior && prior !== binding.commandId) {
+      conflicts.push({
+        key: binding.key,
+        commandId: binding.commandId,
+        reason: `Key already bound to "${prior}"`,
+      });
+      continue;
+    }
+    local.set(key, binding.commandId);
+  }
+
+  if (conflicts.length > 0) {
+    return { ok: false, conflicts };
+  }
+  return { ok: true };
+}
+
+export function claimKeybindings(
+  keybindings: KeybindingContribution[],
+  claimed: Map<string, string>,
+): void {
+  for (const binding of keybindings) {
+    claimed.set(normalizeKey(binding.key), binding.commandId);
+  }
+}

package/src/commands/manifest/configuration.ts

@@ -0,0 +1,59 @@
+import type {
+  ConfigurationGroup,
+  ConfigurationProperty,
+  ContributionManifest,
+  MergedConfiguration,
+} from "./types";
+import { selectManifests } from "./merge";
+
+/**
+ * Merge configuration groups from selected manifests.
+ * Property keys must be globally unique across all groups.
+ */
+export function mergeConfiguration(
+  manifests: readonly ContributionManifest[],
+): MergedConfiguration {
+  const groups: ConfigurationGroup[] = [];
+  const properties = new Map<string, ConfigurationProperty>();
+  const defaults: Record<string, boolean | number | string> = {};
+  const seenKeys = new Map<string, string>();
+
+  for (const manifest of manifests) {
+    for (const group of manifest.configuration?.groups ?? []) {
+      const nextProperties: Record<string, ConfigurationProperty> = {};
+      for (const [key, property] of Object.entries(group.properties)) {
+        const prior = seenKeys.get(key);
+        if (prior) {
+          throw new Error(
+            `Configuration property "${key}" redeclared by "${manifest.id}" (already from "${prior}")`,
+          );
+        }
+        seenKeys.set(key, manifest.id);
+        nextProperties[key] = property;
+        properties.set(key, property);
+        defaults[key] = property.default;
+      }
+      groups.push({
+        id: group.id,
+        title: group.title,
+        order: group.order,
+        properties: nextProperties,
+      });
+    }
+  }
+
+  groups.sort(
+    (a, b) =>
+      (a.order ?? 0) - (b.order ?? 0) || a.title.localeCompare(b.title),
+  );
+
+  return { groups, defaults, properties };
+}
+
+/** Configuration for the active scope (any + exact matches). */
+export function mergeActiveConfiguration(
+  manifests: readonly ContributionManifest[],
+  activeScopeId: string | null,
+): MergedConfiguration {
+  return mergeConfiguration(selectManifests(manifests, activeScopeId));
+}

package/src/commands/manifest/contribution-manifest-schema.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+
+const menuContributionSchema = z.object({
+  path: z.array(z.string()).min(1),
+  commandId: z.string().min(1),
+  order: z.number().optional(),
+  group: z.string().optional(),
+  label: z.string().optional(),
+  shortcut: z.string().optional(),
+  when: z.string().min(1).optional(),
+});
+
+const keybindingContributionSchema = z.object({
+  commandId: z.string().min(1),
+  key: z.string().min(1),
+});
+
+const configurationPropertySchema = z.object({
+  type: z.enum(["boolean", "number", "string"]),
+  default: z.union([z.boolean(), z.number(), z.string()]),
+  title: z.string(),
+  description: z.string().optional(),
+  enum: z.array(z.string()).optional(),
+  minimum: z.number().optional(),
+  maximum: z.number().optional(),
+  order: z.number().optional(),
+});
+
+const configurationGroupSchema = z.object({
+  id: z.string().min(1),
+  title: z.string(),
+  order: z.number().optional(),
+  properties: z.record(z.string(), configurationPropertySchema),
+});
+
+export const contributionManifestSchema = z.object({
+  id: z.string().min(1),
+  activation: z.enum(["always", "any", "exact"]).optional(),
+  commands: z
+    .array(
+      z.object({
+        id: z.string().min(1),
+        title: z.string(),
+        group: z.string().optional(),
+        when: z.string().min(1).optional(),
+      }),
+    )
+    .optional(),
+  menus: z.array(menuContributionSchema).optional(),
+  keybindings: z.array(keybindingContributionSchema).optional(),
+  configuration: z
+    .object({
+      groups: z.array(configurationGroupSchema),
+    })
+    .optional(),
+});