@x12i/editor 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x12i
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @x12i/editor
+
+Document schema for the Unified UI Kit block editor.
+
+> **Status: foundation.** This package ships the versioned document JSON and the
+> provider contracts for collaboration and AI assistance. The editor, the engine
+> spike and the converters are not built yet.
+
+The stored document is JSON that the kit owns, so the engine behind the editor
+can change without migrating saved documents. It includes the kit blocks: a
+chart block holds a [`ChartSpec`](../charts), a diagram block holds a
+[`DiagramDocument`](../diagrams) and a data view block holds a
+[`SavedView`](../data).
+
+```ts
+import { createEmptyDocument, type EditorDocument } from "@x12i/editor";
+
+const doc: EditorDocument = createEmptyDocument();
+```
+
+## Planned engine
+
+Decided by a scored spike: Tiptap core on ProseMirror (MIT) is the default if
+scores tie, with Plate and Lexical as alternatives. Collaboration will use Yjs
+behind `CollaborationProvider`, with Hocuspocus (MIT) as the reference server.
+
+Not allowed: BlockNote XL packages (GPL-3.0 or commercial) and Tiptap Pro
+extensions or cloud features that need a subscription.

package/dist/index.d.ts

@@ -0,0 +1,184 @@
+import { ChartSpec } from '@x12i/charts';
+import { SavedView } from '@x12i/data';
+import { DiagramDocument } from '@x12i/diagrams';
+
+/**
+ * The stored document (spec section 11): versioned JSON owned by the kit, with
+ * converters to and from the engine's format planned. That keeps the editor
+ * engine (Tiptap by default) replaceable.
+ */
+
+declare const DOCUMENT_VERSION = 1;
+type Mark = {
+    type: "bold";
+} | {
+    type: "italic";
+} | {
+    type: "underline";
+} | {
+    type: "strike";
+} | {
+    type: "code";
+} | {
+    type: "link";
+    href: string;
+} | {
+    type: "color";
+    token: string;
+} | {
+    type: "highlight";
+    token: string;
+};
+type InlineNode = {
+    type: "text";
+    text: string;
+    marks?: Mark[];
+} | {
+    type: "mention";
+    kind: "person" | "page" | "date";
+    id: string;
+    label: string;
+} | {
+    type: "emoji";
+    shortcode: string;
+};
+type Inline = InlineNode[];
+interface BlockBase {
+    id: string;
+}
+type CalloutVariant = "info" | "success" | "warning" | "danger" | "neutral";
+interface TaskItem {
+    id: string;
+    content: Inline;
+    checked: boolean;
+    children?: TaskItem[];
+}
+interface ListItem {
+    id: string;
+    content: Inline;
+    children?: ListItem[];
+}
+interface TableCell {
+    content: Inline;
+    colSpan?: number;
+    rowSpan?: number;
+    header?: boolean;
+}
+type Block = BlockBase & ({
+    type: "paragraph";
+    content: Inline;
+} | {
+    type: "heading";
+    level: 1 | 2 | 3 | 4;
+    content: Inline;
+} | {
+    type: "quote";
+    content: Inline;
+} | {
+    type: "callout";
+    variant: CalloutVariant;
+    content: Inline;
+} | {
+    type: "toggle";
+    summary: Inline;
+    children: Block[];
+} | {
+    type: "divider";
+} | {
+    type: "bulleted-list";
+    items: ListItem[];
+} | {
+    type: "numbered-list";
+    items: ListItem[];
+} | {
+    type: "task-list";
+    items: TaskItem[];
+} | {
+    type: "code";
+    language?: string;
+    code: string;
+} | {
+    type: "equation";
+    latex: string;
+} | {
+    type: "table";
+    headerRow?: boolean;
+    headerColumn?: boolean;
+    rows: TableCell[][];
+} | {
+    type: "image";
+    src: string;
+    alt: string;
+    caption?: Inline;
+    align?: "start" | "center" | "end";
+    width?: number;
+} | {
+    type: "video" | "audio";
+    src: string;
+    caption?: Inline;
+} | {
+    type: "file";
+    src: string;
+    name: string;
+    size?: number;
+} | {
+    type: "bookmark";
+    url: string;
+    title?: string;
+    description?: string;
+} | {
+    type: "columns";
+    columns: Block[][];
+} | {
+    type: "page-break";
+} | {
+    type: "table-of-contents";
+} | {
+    type: "chart";
+    spec: ChartSpec;
+} | {
+    type: "diagram";
+    engine: "mermaid" | "canvas" | "excalidraw";
+    diagram?: DiagramDocument;
+    source?: string;
+} | {
+    type: "data-view";
+    dataset: string;
+    view: SavedView;
+} | {
+    type: "ai";
+    prompt: string;
+    result?: Block[];
+});
+type BlockType = Block["type"];
+interface EditorDocument {
+    version: typeof DOCUMENT_VERSION;
+    title?: string;
+    blocks: Block[];
+}
+/** An empty document with one empty paragraph. */
+declare function createEmptyDocument(id?: string): EditorDocument;
+/** Shared document model behind a provider interface (Yjs and Hocuspocus planned). */
+interface CollaborationProvider {
+    connect(documentId: string): Promise<void>;
+    disconnect(): void;
+    onPresence(listener: (users: Array<{
+        id: string;
+        name: string;
+        color: string;
+    }>) => void): () => void;
+}
+type AiCommand = "continue" | "summarize" | "rewrite" | "fix-grammar";
+/** Provider-agnostic hook. The kit calls no model by itself. */
+interface AiProvider {
+    run(input: {
+        command: AiCommand;
+        selection: string;
+        /** For `rewrite`, for example "formal". */
+        tone?: string;
+        signal?: AbortSignal;
+    }): AsyncIterable<string>;
+}
+
+export { DOCUMENT_VERSION, createEmptyDocument };
+export type { AiCommand, AiProvider, Block, BlockBase, BlockType, CalloutVariant, CollaborationProvider, EditorDocument, Inline, InlineNode, ListItem, Mark, TableCell, TaskItem };

package/dist/index.js

@@ -0,0 +1,12 @@
+// src/index.ts
+var DOCUMENT_VERSION = 1;
+function createEmptyDocument(id = "root") {
+  return {
+    version: DOCUMENT_VERSION,
+    blocks: [{ id, type: "paragraph", content: [] }]
+  };
+}
+
+export { DOCUMENT_VERSION, createEmptyDocument };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AASO,IAAM,gBAAA,GAAmB;AA0FzB,SAAS,mBAAA,CAAoB,KAAK,MAAA,EAAwB;AAC/D,EAAA,OAAO;AAAA,IACL,OAAA,EAAS,gBAAA;AAAA,IACT,MAAA,EAAQ,CAAC,EAAE,EAAA,EAAI,MAAM,WAAA,EAAa,OAAA,EAAS,EAAC,EAAG;AAAA,GACjD;AACF","file":"index.js","sourcesContent":["/**\r\n * The stored document (spec section 11): versioned JSON owned by the kit, with\r\n * converters to and from the engine's format planned. That keeps the editor\r\n * engine (Tiptap by default) replaceable.\r\n */\r\nimport type { ChartSpec } from \"@x12i/charts\";\r\nimport type { SavedView } from \"@x12i/data\";\r\nimport type { DiagramDocument } from \"@x12i/diagrams\";\r\n\r\nexport const DOCUMENT_VERSION = 1;\r\n\r\n// ---------------------------------------------------------------------------\r\n// Inline content\r\n// ---------------------------------------------------------------------------\r\n\r\nexport type Mark =\r\n  | { type: \"bold\" }\r\n  | { type: \"italic\" }\r\n  | { type: \"underline\" }\r\n  | { type: \"strike\" }\r\n  | { type: \"code\" }\r\n  | { type: \"link\"; href: string }\r\n  | { type: \"color\"; token: string }\r\n  | { type: \"highlight\"; token: string };\r\n\r\nexport type InlineNode =\r\n  | { type: \"text\"; text: string; marks?: Mark[] }\r\n  | { type: \"mention\"; kind: \"person\" | \"page\" | \"date\"; id: string; label: string }\r\n  | { type: \"emoji\"; shortcode: string };\r\n\r\nexport type Inline = InlineNode[];\r\n\r\n// ---------------------------------------------------------------------------\r\n// Blocks\r\n// ---------------------------------------------------------------------------\r\n\r\nexport interface BlockBase {\r\n  id: string;\r\n}\r\n\r\nexport type CalloutVariant = \"info\" | \"success\" | \"warning\" | \"danger\" | \"neutral\";\r\n\r\nexport interface TaskItem {\r\n  id: string;\r\n  content: Inline;\r\n  checked: boolean;\r\n  children?: TaskItem[];\r\n}\r\n\r\nexport interface ListItem {\r\n  id: string;\r\n  content: Inline;\r\n  children?: ListItem[];\r\n}\r\n\r\nexport interface TableCell {\r\n  content: Inline;\r\n  colSpan?: number;\r\n  rowSpan?: number;\r\n  header?: boolean;\r\n}\r\n\r\nexport type Block = BlockBase &\r\n  (\r\n    | { type: \"paragraph\"; content: Inline }\r\n    | { type: \"heading\"; level: 1 | 2 | 3 | 4; content: Inline }\r\n    | { type: \"quote\"; content: Inline }\r\n    | { type: \"callout\"; variant: CalloutVariant; content: Inline }\r\n    | { type: \"toggle\"; summary: Inline; children: Block[] }\r\n    | { type: \"divider\" }\r\n    | { type: \"bulleted-list\"; items: ListItem[] }\r\n    | { type: \"numbered-list\"; items: ListItem[] }\r\n    | { type: \"task-list\"; items: TaskItem[] }\r\n    | { type: \"code\"; language?: string; code: string }\r\n    | { type: \"equation\"; latex: string }\r\n    | { type: \"table\"; headerRow?: boolean; headerColumn?: boolean; rows: TableCell[][] }\r\n    | { type: \"image\"; src: string; alt: string; caption?: Inline; align?: \"start\" | \"center\" | \"end\"; width?: number }\r\n    | { type: \"video\" | \"audio\"; src: string; caption?: Inline }\r\n    | { type: \"file\"; src: string; name: string; size?: number }\r\n    | { type: \"bookmark\"; url: string; title?: string; description?: string }\r\n    | { type: \"columns\"; columns: Block[][] }\r\n    | { type: \"page-break\" }\r\n    | { type: \"table-of-contents\" }\r\n    // Kit blocks\r\n    | { type: \"chart\"; spec: ChartSpec }\r\n    | { type: \"diagram\"; engine: \"mermaid\" | \"canvas\" | \"excalidraw\"; diagram?: DiagramDocument; source?: string }\r\n    | { type: \"data-view\"; dataset: string; view: SavedView }\r\n    | { type: \"ai\"; prompt: string; result?: Block[] }\r\n  );\r\n\r\nexport type BlockType = Block[\"type\"];\r\n\r\nexport interface EditorDocument {\r\n  version: typeof DOCUMENT_VERSION;\r\n  title?: string;\r\n  blocks: Block[];\r\n}\r\n\r\n/** An empty document with one empty paragraph. */\r\nexport function createEmptyDocument(id = \"root\"): EditorDocument {\r\n  return {\r\n    version: DOCUMENT_VERSION,\r\n    blocks: [{ id, type: \"paragraph\", content: [] }],\r\n  };\r\n}\r\n\r\n// ---------------------------------------------------------------------------\r\n// Optional packages: collaboration and AI assistance\r\n// ---------------------------------------------------------------------------\r\n\r\n/** Shared document model behind a provider interface (Yjs and Hocuspocus planned). */\r\nexport interface CollaborationProvider {\r\n  connect(documentId: string): Promise<void>;\r\n  disconnect(): void;\r\n  onPresence(listener: (users: Array<{ id: string; name: string; color: string }>) => void): () => void;\r\n}\r\n\r\nexport type AiCommand = \"continue\" | \"summarize\" | \"rewrite\" | \"fix-grammar\";\r\n\r\n/** Provider-agnostic hook. The kit calls no model by itself. */\r\nexport interface AiProvider {\r\n  run(input: {\r\n    command: AiCommand;\r\n    selection: string;\r\n    /** For `rewrite`, for example \"formal\". */\r\n    tone?: string;\r\n    signal?: AbortSignal;\r\n  }): AsyncIterable<string>;\r\n}\r\n"]}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@x12i/editor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Document schema for the Unified UI Kit block editor: versioned JSON owned by the kit, so the engine stays replaceable. The editor itself is planned.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/x12i/unified-ui-kit.git",
+    "directory": "packages/editor"
+  },
+  "homepage": "https://github.com/x12i/unified-ui-kit/tree/main/packages/editor#readme",
+  "bugs": {
+    "url": "https://github.com/x12i/unified-ui-kit/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@x12i/charts": "^1.0.0",
+    "@x12i/data": "^1.0.0",
+    "@x12i/diagrams": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests"
+  }
 }