@yuzhouu/canvas-kit 0.1.2

package/README.md

@@ -0,0 +1,145 @@
+# @land/canvas-kit
+
+`@land/canvas-kit` 把 Land 画布打包成一个开箱即用的 React 画布套件，包含标准产品预设、插件集成和类型化 API。
+
+发布包包含：
+
+- `CanvasKit`，用于直接嵌入标准画布套件
+- `createCanvasKitApi` 和 `CanvasKitApi`，用于编辑器自动化
+- `createCanvasKitProduct`，用于较底层的 `CanvasProductRoot` 产品组合
+- `@land/canvas-kit/product`，用于自定义产品 chrome
+- `@land/canvas-kit/standard`，用于标准内置插件扩展与类型化 API
+- 打包进发布产物的 Land 内部依赖
+- 作为 peer dependency 的 `react` 和 `react-dom`
+
+## 文档
+
+- [使用文档](./docs/使用文档.md) - 基于 `apps/professional` 和 `apps/zen` 示例的使用指南。
+- [API 文档](./docs/API文档.md) - `.`、`./product` 和 `./standard` 三个入口的完整 API 参考。
+
+## 安装
+
+```bash
+pnpm add @land/canvas-kit react react-dom
+```
+
+## 使用
+
+```tsx
+import { useRef } from "react";
+import {
+  CanvasKit,
+  type CanvasKitHandle,
+} from "@land/canvas-kit";
+import "@land/canvas-kit/style.css";
+
+export function App() {
+  const apiRef = useRef<CanvasKitHandle>(null);
+
+  return (
+    <div style={{ width: "100%", height: "100vh" }}>
+      <CanvasKit
+        ref={apiRef}
+        onReady={(api) => {
+          console.log(api.snapshot());
+        }}
+      />
+    </div>
+  );
+}
+```
+
+宿主容器需要提供明确尺寸。`CanvasKit` 会以 `width: 100%` 和 `height: 100%` 填满父容器。
+
+## 注意事项
+
+- 默认的 `canvas-kit` 产品包含画布表面、标准插件、产品运行时，以及插件自带的编辑 UI，例如文本行内格式工具条。
+- 它不会注册产品级 chrome 面板、工具栏或上下文菜单。
+
+## 使用 `createCanvasKitProduct` 自定义 chrome
+
+`createCanvasKitProduct` 是围绕标准 Land 画布构建自定义产品壳的较底层组合入口。它负责编辑器运行时、标准插件、图片导入、剪贴板集成、持久化和 API 生命周期；你的应用只需要通过一个 `chrome(context)` 函数提供产品 UI。
+
+```tsx
+import { useMemo } from "react";
+import { CanvasProductRoot } from "@land/canvas-product-react";
+import {
+  createCanvasKitProduct,
+  type CanvasKitChromeContext,
+} from "@land/canvas-kit/product";
+import { type CanvasKitApi } from "@land/canvas-kit";
+import "@land/canvas-kit/style.css";
+
+function MyChrome({ context }: { context: CanvasKitChromeContext<CanvasKitApi> }) {
+  const { api, history, selectedShapeIds, selection, toolbarSurfaces, zoom } =
+    context;
+
+  return (
+    <>
+      <div className="my-topbar">
+        <button type="button" disabled={!history.canUndo} onClick={history.undo}>
+          撤销
+        </button>
+        <button type="button" onClick={zoom.zoomIn}>
+          放大
+        </button>
+        <button
+          type="button"
+          disabled={selection.count === 0}
+          onClick={() => api.deleteShapes([...selectedShapeIds])}
+        >
+          删除
+        </button>
+      </div>
+
+      {toolbarSurfaces.contextToolbarGroups.length > 0 ? (
+        <aside className="my-context-panel">
+          {toolbarSurfaces.contextToolbarTitle}
+        </aside>
+      ) : null}
+    </>
+  );
+}
+
+export function App() {
+  const product = useMemo(
+    () =>
+      createCanvasKitProduct({
+        chrome: (context) => <MyChrome context={context} />,
+        exposeApiOnWindow: true,
+      }),
+    [],
+  );
+
+  return (
+    <div style={{ width: "100%", height: "100vh" }}>
+      <CanvasProductRoot product={product} />
+    </div>
+  );
+}
+```
+
+如果要做 professional 风格的产品，可以围绕 `CanvasKitChromeContext` 添加自己的面板，并把文档改动保持在 `context.api` 上。chrome 不需要直接访问 `Editor`、`@land/canvas-core` 或 `@land/canvas-react/host`。
+
+## 高级入口
+
+包根入口会刻意保持精简。较底层的产品套件辅助方法请从显式子路径导入：
+
+```tsx
+import { createCanvasKitProduct } from "@land/canvas-kit/product";
+import { standardCanvasExtensions } from "@land/canvas-kit/standard";
+```
+
+## 本仓库本地构建
+
+从 workspace 根目录执行：
+
+```bash
+pnpm build:canvas-kit:bundle
+```
+
+可发布产物会写入：
+
+```text
+packages/canvas-kit/dist-component/
+```

package/_vendor/canvas-core/bindings/BindingUtil.ts

@@ -0,0 +1,92 @@
+import type { Editor } from "../editor/Editor";
+import type { SelectionOverlayFrameGeometryState } from "../editor/selection";
+import type {
+  BindingId,
+  BindingRecord,
+  BindingRecordBase,
+  ShapeRecord,
+} from "../schema/records";
+
+export interface BindingUtilEffect {
+  shapes?: ShapeRecord[];
+  bindings?: BindingRecord[];
+  deleteShapeIds?: ShapeRecord["id"][];
+  deleteBindingIds?: BindingId[];
+}
+
+export interface BindingShapeChangeContext {
+  before: ShapeRecord;
+  after: ShapeRecord;
+  role: "from" | "to";
+}
+
+export interface BindingShapeDeleteContext {
+  shape: ShapeRecord;
+  role: "from" | "to";
+}
+
+export interface BindingEndpointContext {
+  fromShape: ShapeRecord;
+  toShape: ShapeRecord;
+}
+
+export interface BindingSelectionCompanionFrameContext {
+  selectedShape: ShapeRecord;
+}
+
+export interface BindingShapeGeometryDependencyContext {
+  shape: ShapeRecord;
+  role: "from" | "to";
+}
+
+export abstract class BindingUtil<
+  B extends BindingRecordBase = BindingRecordBase,
+> {
+  abstract readonly type: B["type"];
+
+  abstract getDefaultProps(): B["props"];
+
+  abstract validateProps(props: unknown): B["props"];
+
+  canBind?(editor: Editor, binding: B, context: BindingEndpointContext): boolean;
+
+  getExclusiveBindingKey?(binding: B): string | null;
+
+  onBindingCreate?(editor: Editor, binding: B): BindingUtilEffect | void;
+
+  onBindingUpdate?(
+    editor: Editor,
+    before: B,
+    after: B,
+  ): BindingUtilEffect | void;
+
+  onBindingLoad?(editor: Editor, binding: B): BindingUtilEffect | void;
+
+  onAfterShapeChange?(
+    editor: Editor,
+    binding: B,
+    context: BindingShapeChangeContext,
+  ): BindingUtilEffect | void;
+
+  onBeforeDeleteShape?(
+    editor: Editor,
+    binding: B,
+    context: BindingShapeDeleteContext,
+  ): BindingUtilEffect | void;
+
+  onBeforeDeleteBinding?(editor: Editor, binding: B): BindingUtilEffect | void;
+
+  getExportShapeIds?(editor: Editor, binding: B): ShapeRecord["id"][];
+
+  getGeometryDependentShapeIds?(
+    editor: Editor,
+    binding: B,
+    context: BindingShapeGeometryDependencyContext,
+  ): ShapeRecord["id"][];
+
+  getSelectionCompanionFrameGeometries?(
+    editor: Editor,
+    binding: B,
+    context: BindingSelectionCompanionFrameContext,
+  ): SelectionOverlayFrameGeometryState[];
+}

package/_vendor/canvas-core/bindings/BindingUtilRegistry.ts

@@ -0,0 +1,22 @@
+import type { BindingRecordBase } from "../schema/records";
+import { BindingUtil } from "./BindingUtil";
+
+export class BindingUtilRegistry {
+  private readonly registry = new Map<string, BindingUtil>();
+
+  register<B extends BindingRecordBase>(util: BindingUtil<B>): void {
+    this.registry.set(util.type, util as BindingUtil);
+  }
+
+  values(): IterableIterator<BindingUtil> {
+    return this.registry.values();
+  }
+
+  get<B extends BindingRecordBase>(type: B["type"]): BindingUtil<B> {
+    const util = this.registry.get(type);
+    if (!util) {
+      throw new Error(`Missing binding util for type \"${type}\"`);
+    }
+    return util as BindingUtil<B>;
+  }
+}

package/_vendor/canvas-core/bindings/arrow/arrowBindingHelpers.ts

@@ -0,0 +1,52 @@
+import { Vec } from "../../geometry/Vec";
+import type { Editor } from "../../editor/Editor";
+import type { ArrowBindingPreviewState } from "../../editor/selection";
+import type { ShapeId } from "../../schema/records";
+
+export interface ConnectionPoint {
+  x: number;
+  y: number;
+}
+
+export type ConnectionTerminal = "start" | "end";
+
+export interface ArrowBindingTargetInput {
+  targetShapeId: ShapeId;
+  normalizedAnchor: ConnectionPoint;
+}
+
+export interface ResolvedArrowTerminalBinding {
+  pagePoint: Vec;
+  binding: ArrowBindingTargetInput | null;
+  preview: ArrowBindingPreviewState | null;
+}
+
+export interface ArrowTerminalBindingResolverInput {
+  terminal: ConnectionTerminal;
+  rawPagePoint: Vec;
+  oppositePagePoint: Vec;
+  excludeShapeId?: ShapeId;
+  ignoreTargets?: boolean;
+}
+
+export type ArrowTerminalBindingResolver = (
+  editor: Editor,
+  input: ArrowTerminalBindingResolverInput,
+) => ResolvedArrowTerminalBinding;
+
+export function getFreeArrowTerminalBinding({
+  rawPagePoint,
+}: ArrowTerminalBindingResolverInput): ResolvedArrowTerminalBinding {
+  return {
+    pagePoint: rawPagePoint.clone(),
+    binding: null,
+    preview: null,
+  };
+}
+
+export function resolveArrowTerminalBindingAtPoint(
+  editor: Editor,
+  input: ArrowTerminalBindingResolverInput,
+): ResolvedArrowTerminalBinding {
+  return editor.resolveArrowTerminalBinding(input);
+}

package/_vendor/canvas-core/contextMenu.ts

@@ -0,0 +1,85 @@
+import type { ShapeId, ShapeRecordBase } from "./schema/records";
+import type { ToolbarActionValue, ToolbarContext } from "./toolbar";
+import type { Vec } from "./geometry";
+
+export interface ContextMenuCanvasTarget {
+  type: "canvas";
+}
+
+export interface ContextMenuShapeTarget {
+  type: "shape";
+  shapeId: ShapeId;
+  shapeType: ShapeRecordBase["type"];
+  selected: boolean;
+}
+
+export interface ContextMenuSelectionTarget {
+  type: "selection";
+  selectedShapeIds: readonly ShapeId[];
+}
+
+export type ContextMenuTarget =
+  | ContextMenuCanvasTarget
+  | ContextMenuShapeTarget
+  | ContextMenuSelectionTarget;
+
+export interface ContextMenuOpenSnapshot {
+  screenPoint: Vec;
+  pagePoint: Vec;
+  target: ContextMenuTarget;
+}
+
+export interface ContextMenuContext extends ToolbarContext {
+  menu: ContextMenuOpenSnapshot;
+}
+
+export type ContextMenuContributionTarget =
+  | "canvas"
+  | "selection"
+  | "shape"
+  | "any";
+
+export interface ContextMenuCommandItem {
+  kind: "command";
+  id: string;
+  actionId: string;
+  label: string;
+  icon?: string;
+  value?: ToolbarActionValue;
+  shortcut?: string;
+  tone?: "default" | "destructive";
+  dataUi?: string;
+}
+
+export interface ContextMenuSeparatorItem {
+  kind: "separator";
+  id: string;
+}
+
+export interface ContextMenuBadgeItem {
+  kind: "badge";
+  id: string;
+  label: string;
+  dataUi?: string;
+}
+
+export type ContextMenuItem =
+  | ContextMenuCommandItem
+  | ContextMenuSeparatorItem
+  | ContextMenuBadgeItem;
+
+export interface ContextMenuSection {
+  id: string;
+  order?: number;
+  title?: string;
+  items: readonly ContextMenuItem[];
+}
+
+export interface ContextMenuContribution {
+  id: string;
+  target: ContextMenuContributionTarget;
+  order?: number;
+  actionIds: readonly string[];
+  when?(context: ContextMenuContext): boolean;
+  getSections(context: ContextMenuContext): readonly ContextMenuSection[];
+}