@hankchen/canvas-editor 0.7.1 → 0.8.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { LayerBox, Canvas, TextLayoutPolicies, Layer, LayerType, TableLayer, RenderBackend, Padding, HorizontalAlign, VerticalAlign, Anchor, TableRowLayer, TableCellLayer, TableRowTemplateLayer } from '@hankchen/canvas';
-export { ANCHORS, Anchor, Border, BorderSide, Canvas, HORIZONTAL_ALIGNS, HorizontalAlign, LAYER_TYPES, Layer, LayerBox, LayerType, Padding, TableCellLayer, TableLayer, TableRowLayer, TextLayer, VERTICAL_ALIGNS, VerticalAlign } from '@hankchen/canvas';
+import { LayerBox, Canvas, TextLayoutPolicies, Layer, LayerType, TableLayer, RenderBackend, Padding, HorizontalAlign, VerticalAlign, CanvasBackground, Anchor, TableRowLayer, TableCellLayer, TableRowTemplateLayer } from '@hankchen/canvas';
+export { ANCHORS, Anchor, Border, BorderSide, Canvas, CanvasBackground, HORIZONTAL_ALIGNS, HorizontalAlign, LAYER_TYPES, Layer, LayerBox, LayerType, Padding, TableCellLayer, TableLayer, TableRowLayer, TextLayer, VERTICAL_ALIGNS, VerticalAlign } from '@hankchen/canvas';
 import { Draft, Patch } from 'immer';
 export { canvasFontCssFamily } from '@hankchen/canvas-browser-renderer';
 
@@ -2090,8 +2090,15 @@ declare class EditorSession {
      * commitTextEdit 先清会话再落库，天然不复入接管。
      */
     private takeoverDraftIfNeeded;
-    /** 更新画布级字段（未选中图层时面板的宽/高写入口）；键由类型收窄为 width/height */
+    /**
+     * 更新画布级字段（未选中图层时面板的写入口）：width/height 数值；background
+     * 整对象一步事务（canvas-background 工单 04）——面板各分量提交折算回整对象，
+     * 归一经 normalizeCanvasBackground（空串分量归 null、两分量皆空 = 清背景 null，
+     * 镜像解码语义；条件写键归 encode）；结构相同的整对象空转（immer 引义换新
+     * 不产生历史步，数值键的零变更语义同门）。
+     */
     updateCanvasProp(key: 'width' | 'height', value: number, options?: TransactOptions): void;
+    updateCanvasProp(key: 'background', value: CanvasBackground | null, options?: TransactOptions): void;
     /**
      * 注入数据源 schema 声明（载荷形态，D1 钉定：声明即 compile(canvas, dataset)
      * 收到的 data 载荷形状，根上下文候选 = 载荷顶层键）。声明经
@@ -3144,6 +3151,16 @@ declare function enumerateExpressionCandidates(schema: ExpressionSchemaNode | nu
  * 给根 schema 表根起点，故独立落件不改 expressionContext）；任一层解析不出
  * （rowsPath 无 items 声明/漂移/途经非表）→ null 降级无候选。
  *
+ * 点选器剪枝枚举件（rows-path-picker 工单 01，spec D5/D3）：级联点选器每层的
+ * 候选条目——在补全枚举语义上加剪枝谓词 leadsToArray，候选面收敛至「通往行数组
+ * 的路径」：标量子段不出现；对象子段仅当子树内沿 properties 链至少含一个可达
+ * 数组才出现；数组子段 = 终点条目（isArray 标记），不透传 items（数组套数组的
+ * 内层不可达）。无 partial 概念（纯点选无输入期），前缀 = 已积累点路径、逐段
+ * 全量已消费、尾段取子层；空层/漂移/畸形前缀一律返回空数组（空态呈现归 vue
+ * 面）。起点判别不在此重复造：调用方经 resolveRowsPathStartSchema 得起点后再
+ * 进本件。元信息同表达式补全先例（D8）：description/title 两字段分离透传，展示
+ * 回落 description ?? title 归呈现层。
+ *
  * 全模块纯函数、零 DOM；层内依赖仅 expressionSchema / expressionCandidates
  * （候选类型面）/ layerPath。
  */
@@ -3166,6 +3183,31 @@ interface RowsPathCandidateResult {
  * 阻）；枚举落点为对象层 → 该层全量合法子项。
  */
 declare function enumerateRowsPathCandidates(startSchema: ExpressionSchemaNode | null, input: string): RowsPathCandidateResult | null;
+/**
+ * 一条 rowsPath 点选器条目（rows-path-picker 工单 01）：级联一层的可点项。
+ * 与 RowsPathCandidate 的分叉：无 partial/徽标面，换显式数组终点标记——点选器
+ * 按 isArray 分流「点选提交 / 只可下钻」，不再经「带尾点探一层」推断。
+ */
+interface RowsPathPickerEntry {
+    /** 提交/下钻的完整点路径（起点相对；点选器 v-model 面就是它） */
+    path: string;
+    /** 本段名（无元信息时的显示回落） */
+    segment: string;
+    /** 显示名注解（D8 两字段分离透传；展示回落 description ?? title 归呈现层） */
+    title?: string;
+    /** 说明（未声明为 undefined） */
+    description?: string;
+    /** 数组终点标记：true = 行数组终点（点选即提交）；false = 对象中间站（只可下钻） */
+    isArray: boolean;
+}
+/**
+ * 枚举点选器某层的候选条目（rows-path-picker 工单 01）：prefix 为已积累点路径，
+ * 逐段全量已消费、尾段取子层（'' = 起点层）；下钻域规则走 descendToLayer，每层
+ * 条目经 leadsToArray 剪枝至「通往行数组的路径」。起点 schema null / 前缀漂移
+ * （段缺失/标量落点）/ 畸形（双点/尾点/头点）/ 数组落点（数组不展开）→ 空数组，
+ * 全程不抛错——空态呈现归 vue 面（spec D6）。
+ */
+declare function enumerateRowsPathPickerEntries(startSchema: ExpressionSchemaNode | null, prefix: string): readonly RowsPathPickerEntry[];
 /**
  * rowsPath 编辑起点的三分流判别（D3）：无 template 祖先 → 载荷根 schema（根层
  * 表；建表表单恒根起点同款）；有 template 祖先 → 沿选中路径每个 template 段行
@@ -3221,4 +3263,4 @@ declare function memoizeTextPolicies(policies?: TextLayoutPolicies, options?: Me
  */
 declare const PACKAGE_NAME: "@hankchen/canvas-editor";
 
-export { ALIGN_CORNER_MARGIN_PX, ALT_DRAG_DEAD_ZONE_SCREEN_PX, ARM_CREATE_LAYER_TYPES, type AlignBoxGeometry, type AlignToCanvasMode, type AlignToCanvasOptions, type ArmCreateShortcutAction, CREATE_DEAD_ZONE_SCREEN_PX, type CanvasEditorState, type CreateGesture, type CreateRectResult, DATE_FORMAT_SUGGESTIONS, DEFAULT_EDITOR_SHORTCUTS, DEFAULT_ZOOM_BOUNDS, type DataSourceSchemaRejection, type DeletedLayerRef, type DocRecipe, type DragGesture, EDITOR_STATE_SCHEMA_VERSION, EXPRESSION_FUNCTIONS, type EditorChange, type EditorPrefsState, EditorSession, type EditorSessionOptions, type EditorShortcutAction, type EditorShortcutBinding, type EditorShortcutGroup, type EditorShortcutInput, EditorStore, type EditorUi, type ExpressionCallArg, type ExpressionCallErrorKind, type ExpressionCallParse, type ExpressionCallSlotContext, type ExpressionCandidate, type ExpressionCandidateQuery, type ExpressionCandidateResult, type ExpressionContextKind, type ExpressionErrorRange, type ExpressionFormatSuggestion, type ExpressionFragmentDiagnostic, type ExpressionFragmentErrorKind, type ExpressionFunctionMeta, type ExpressionPathHead, type ExpressionPathParse, type ExpressionScan, type ExpressionScanFragment, type ExpressionScanLiteral, type ExpressionScanOpen, type ExpressionScanPart, type ExpressionSchemaChildEntry, type ExpressionSchemaChildView, type ExpressionSchemaDiagnostic, type ExpressionSchemaDiagnosticCode, type ExpressionSchemaNode, type ExpressionSchemaParse, type ExpressionSchemaRejectReason, type ExpressionSyntaxError, type FindSession, type FindTextHit, FontCatalog, type FontCatalogEntry, type FrameScheduler, type Guide, type GuideOrientation, type HistoryStep, type HitTestOptions, type InvalidateTarget, type LayerOutlineNode, type LayerOutlineRole, type LayerPath, MAX_HISTORY_STEPS, type MemoTextPoliciesOptions, type MovedSubtreeRef, NUMBER_FUNCTION_SUGGESTIONS, type NextTextStyle, type OverlayPaintArgs, type OverlayPainter, PACKAGE_NAME, PAN_TO_BOX_MARGIN_PX, PASTE_OFFSET_PX, PHP_TRIM_CHARS, type Point, type ProportionalDrivingAxis, RATIO_PRESETS, RESIZE_HANDLES, RESIZE_HANDLE_HIT_PX, RESIZE_MIN_SIZE_PX, type RatioPreset, type RatioPresetId, type Rect, type ResizeAxes, type ResizeBoxGeometry, type ResizeBoxResult, type ResizeHandle, type ResourceStatus, type ResourceStatusMap, type RowsPathCandidate, type RowsPathCandidateResult, SNAP_THRESHOLD_SCREEN_PX, STYLE_FIELD_KEYS_BY_TYPE, type ShortcutCombo, type Size, type SnapAxis, type SnapAxisSource, type SnapBoxGeometry, type SnapPoints, type SnapResolution, type StyleSnapshot, TEXT_PRESETS, type TextEditLayout, type TextEditingSession, type TextPreset, type TextPresetId, type TransactOptions, type UploadFile, type UploadHandler, UploadHandlerMissingError, type UploadImagePlacement, type Viewport, WHEEL_ZOOM_STEP, type WheelInput, type WheelIntent, type ZoomBounds, addRootLayerInDraft, addTableCellInDraft, addTableRowInDraft, addTemplateCellInDraft, alignToCanvasTarget, applyStyleFieldsInDraft, buildLayerOutline, canCopyLayerAt, canonicalizeTableSyncInDraft, captureStyleSnapshot, clampZoom, classifyEditorShortcut, classifyWheel, cloneLayerSubtree, convertTableToRowsInDraft, convertTableToTemplateInDraft, createDefaultLayer, createRubberBandRect, createTemplateTable, defaultNextTextStyle, defaultSizeForRatio, deleteLayerInDraft, enumerateExpressionCandidates, enumerateRowsPathCandidates, expressionCallSlotAtEnd, expressionDiagnostics, expressionFragmentAtCursor, findPresetEntry, fitRect, fitViewport, growRowToCellInDraft, handleResizesHeight, handleResizesWidth, hitTest, insertRootLayerAdjacentInDraft, insertRootLayerInDraft, isCallFragment, isImageContentUndrawn, isLayerPath, isLockedPath, isRootLayerPath, isRootPasteableType, isTemplateSubtreePath, layerBoxByPath, memoizeTextPolicies, moveGuard, moveRootLayerInDraft, moveTableCellInDraft, moveTableCellToRowInDraft, moveTableRowInDraft, moveTableRowToTableInDraft, nextZoomByWheel, normalizeExpressionSchemaSource, panBy, panToBox, parseExpressionCall, parseExpressionPath, parseExpressionSchema, pastePosition, pathStartsWith, pathsEqual, phpTrim, pickNextTextStylePatch, prepareRootPaste, proportionalDrivingAxis, ratioValue, readSpecField, remapPathAfterSplice, replaceHitsInDraft, resizableAxesAt, resizeBox, resizeBoxProportional, resizeHandleAt, resizeHandlePoint, resizeHandlesAt, resizeProportionalSnapPoints, resizeSnapPoints, resolveLayer, resolveRowSchema, resolveRowsPathStartSchema, resolveSnap, resolveSnapPoints, resourcePathDiagnostics, rootLayerOf, scanExpressionFragments, scanTextMatches, sceneToScreen, schemaChildEntries, schemaNodeAtPath, screenToScene, selectionParentPath, setCellAutoHeightInDraft, snapAxesFromBoxes, snapThresholdScene, snapViewportToPhysicalPixels, syncContentIntoCellInDraft, syncRowWidthInDraft, uploadDisplayName, visibleRootBoxes, writeSpecField, zoomAtPoint };
+export { ALIGN_CORNER_MARGIN_PX, ALT_DRAG_DEAD_ZONE_SCREEN_PX, ARM_CREATE_LAYER_TYPES, type AlignBoxGeometry, type AlignToCanvasMode, type AlignToCanvasOptions, type ArmCreateShortcutAction, CREATE_DEAD_ZONE_SCREEN_PX, type CanvasEditorState, type CreateGesture, type CreateRectResult, DATE_FORMAT_SUGGESTIONS, DEFAULT_EDITOR_SHORTCUTS, DEFAULT_ZOOM_BOUNDS, type DataSourceSchemaRejection, type DeletedLayerRef, type DocRecipe, type DragGesture, EDITOR_STATE_SCHEMA_VERSION, EXPRESSION_FUNCTIONS, type EditorChange, type EditorPrefsState, EditorSession, type EditorSessionOptions, type EditorShortcutAction, type EditorShortcutBinding, type EditorShortcutGroup, type EditorShortcutInput, EditorStore, type EditorUi, type ExpressionCallArg, type ExpressionCallErrorKind, type ExpressionCallParse, type ExpressionCallSlotContext, type ExpressionCandidate, type ExpressionCandidateQuery, type ExpressionCandidateResult, type ExpressionContextKind, type ExpressionErrorRange, type ExpressionFormatSuggestion, type ExpressionFragmentDiagnostic, type ExpressionFragmentErrorKind, type ExpressionFunctionMeta, type ExpressionPathHead, type ExpressionPathParse, type ExpressionScan, type ExpressionScanFragment, type ExpressionScanLiteral, type ExpressionScanOpen, type ExpressionScanPart, type ExpressionSchemaChildEntry, type ExpressionSchemaChildView, type ExpressionSchemaDiagnostic, type ExpressionSchemaDiagnosticCode, type ExpressionSchemaNode, type ExpressionSchemaParse, type ExpressionSchemaRejectReason, type ExpressionSyntaxError, type FindSession, type FindTextHit, FontCatalog, type FontCatalogEntry, type FrameScheduler, type Guide, type GuideOrientation, type HistoryStep, type HitTestOptions, type InvalidateTarget, type LayerOutlineNode, type LayerOutlineRole, type LayerPath, MAX_HISTORY_STEPS, type MemoTextPoliciesOptions, type MovedSubtreeRef, NUMBER_FUNCTION_SUGGESTIONS, type NextTextStyle, type OverlayPaintArgs, type OverlayPainter, PACKAGE_NAME, PAN_TO_BOX_MARGIN_PX, PASTE_OFFSET_PX, PHP_TRIM_CHARS, type Point, type ProportionalDrivingAxis, RATIO_PRESETS, RESIZE_HANDLES, RESIZE_HANDLE_HIT_PX, RESIZE_MIN_SIZE_PX, type RatioPreset, type RatioPresetId, type Rect, type ResizeAxes, type ResizeBoxGeometry, type ResizeBoxResult, type ResizeHandle, type ResourceStatus, type ResourceStatusMap, type RowsPathCandidate, type RowsPathCandidateResult, type RowsPathPickerEntry, SNAP_THRESHOLD_SCREEN_PX, STYLE_FIELD_KEYS_BY_TYPE, type ShortcutCombo, type Size, type SnapAxis, type SnapAxisSource, type SnapBoxGeometry, type SnapPoints, type SnapResolution, type StyleSnapshot, TEXT_PRESETS, type TextEditLayout, type TextEditingSession, type TextPreset, type TextPresetId, type TransactOptions, type UploadFile, type UploadHandler, UploadHandlerMissingError, type UploadImagePlacement, type Viewport, WHEEL_ZOOM_STEP, type WheelInput, type WheelIntent, type ZoomBounds, addRootLayerInDraft, addTableCellInDraft, addTableRowInDraft, addTemplateCellInDraft, alignToCanvasTarget, applyStyleFieldsInDraft, buildLayerOutline, canCopyLayerAt, canonicalizeTableSyncInDraft, captureStyleSnapshot, clampZoom, classifyEditorShortcut, classifyWheel, cloneLayerSubtree, convertTableToRowsInDraft, convertTableToTemplateInDraft, createDefaultLayer, createRubberBandRect, createTemplateTable, defaultNextTextStyle, defaultSizeForRatio, deleteLayerInDraft, enumerateExpressionCandidates, enumerateRowsPathCandidates, enumerateRowsPathPickerEntries, expressionCallSlotAtEnd, expressionDiagnostics, expressionFragmentAtCursor, findPresetEntry, fitRect, fitViewport, growRowToCellInDraft, handleResizesHeight, handleResizesWidth, hitTest, insertRootLayerAdjacentInDraft, insertRootLayerInDraft, isCallFragment, isImageContentUndrawn, isLayerPath, isLockedPath, isRootLayerPath, isRootPasteableType, isTemplateSubtreePath, layerBoxByPath, memoizeTextPolicies, moveGuard, moveRootLayerInDraft, moveTableCellInDraft, moveTableCellToRowInDraft, moveTableRowInDraft, moveTableRowToTableInDraft, nextZoomByWheel, normalizeExpressionSchemaSource, panBy, panToBox, parseExpressionCall, parseExpressionPath, parseExpressionSchema, pastePosition, pathStartsWith, pathsEqual, phpTrim, pickNextTextStylePatch, prepareRootPaste, proportionalDrivingAxis, ratioValue, readSpecField, remapPathAfterSplice, replaceHitsInDraft, resizableAxesAt, resizeBox, resizeBoxProportional, resizeHandleAt, resizeHandlePoint, resizeHandlesAt, resizeProportionalSnapPoints, resizeSnapPoints, resolveLayer, resolveRowSchema, resolveRowsPathStartSchema, resolveSnap, resolveSnapPoints, resourcePathDiagnostics, rootLayerOf, scanExpressionFragments, scanTextMatches, sceneToScreen, schemaChildEntries, schemaNodeAtPath, screenToScene, selectionParentPath, setCellAutoHeightInDraft, snapAxesFromBoxes, snapThresholdScene, snapViewportToPhysicalPixels, syncContentIntoCellInDraft, syncRowWidthInDraft, uploadDisplayName, visibleRootBoxes, writeSpecField, zoomAtPoint };

package/dist/index.js

@@ -2317,6 +2317,17 @@ var ALT_DRAG_DEAD_ZONE_SCREEN_PX = 4;
 var NUDGE_STEP_PX = 1;
 var NUDGE_COARSE_STEP_PX = 10;
 var nudgeMergeKey = (path) => `nudge:${path.join(":")}`;
+function normalizeCanvasBackground(value) {
+  if (value === null) return null;
+  const trim = (raw) => typeof raw === "string" && raw.trim() !== "" ? raw : null;
+  const color = trim(value.color);
+  const image = trim(value.image);
+  return color === null && image === null ? null : { color, image };
+}
+function sameCanvasBackground(a, b) {
+  if (a === null || b === null) return a === b;
+  return a.color === b.color && a.image === b.image;
+}
 function clampFindCursor(cursor, count) {
   if (count <= 0) return 0;
   return Math.min(Math.max(cursor, 0), count - 1);
@@ -3660,9 +3671,15 @@ var EditorSession = class {
     if (!paths.some((path) => pathsEqual(path, editing.path))) return;
     this.store.setEditing({ ...editing, draftSeq: (editing.draftSeq ?? 0) + 1 });
   }
-  /** 更新画布级字段（未选中图层时面板的宽/高写入口）；键由类型收窄为 width/height */
   updateCanvasProp(key, value, options = {}) {
     this.store.transact((draft) => {
+      if (key === "background") {
+        const next = normalizeCanvasBackground(value);
+        const current = draft.background ?? null;
+        if (sameCanvasBackground(current, next)) return;
+        draft.background = next;
+        return;
+      }
       draft[key] = value;
     }, options);
   }
@@ -4761,13 +4778,29 @@ function isArrayNode(node) {
 function isScalarNode(node) {
   return !isArrayNode(node) && node.properties === void 0;
 }
+function joinSegment(prefix, key) {
+  return prefix === "" ? key : `${prefix}.${key}`;
+}
+function withMeta(target, node) {
+  if (node.description !== void 0) target.description = node.description;
+  if (node.title !== void 0) target.title = node.title;
+  return target;
+}
+function descendToLayer(start, segments) {
+  let base = start;
+  for (const segment of segments) {
+    if (isArrayNode(base)) return null;
+    const child = schemaNodeAtPath(base, [segment]);
+    if (child === null) return null;
+    base = child;
+  }
+  return isArrayNode(base) || isScalarNode(base) ? null : base;
+}
 function childCandidate2(key, node, prefix) {
-  const candidate = {
-    path: prefix === "" ? key : `${prefix}.${key}`,
-    segment: key
-  };
-  if (node.description !== void 0) candidate.description = node.description;
-  if (node.title !== void 0) candidate.title = node.title;
+  const candidate = withMeta(
+    { path: joinSegment(prefix, key), segment: key },
+    node
+  );
   if (isArrayNode(node)) candidate.type = "array";
   return candidate;
 }
@@ -4786,17 +4819,40 @@ function enumerateRowsPathCandidates(startSchema, input) {
   const segments = input.split(".");
   const partial = input.endsWith(".") ? "" : segments[segments.length - 1];
   const completed = segments.slice(0, -1);
-  let base = startSchema;
-  for (const segment of completed) {
-    if (isArrayNode(base)) return null;
-    const child = schemaNodeAtPath(base, [segment]);
-    if (child === null) return null;
-    base = child;
-  }
-  if (isArrayNode(base) || isScalarNode(base)) return null;
+  const base = descendToLayer(startSchema, completed);
+  if (base === null) return null;
   const view = levelCandidates(base, completed.join("."));
   return { partial, candidates: view };
 }
+function leadsToArray(node) {
+  if (isArrayNode(node)) return true;
+  if (node.properties === void 0) return false;
+  for (const child of node.properties.values()) {
+    if (leadsToArray(child)) return true;
+  }
+  return false;
+}
+function pickerEntry(key, node, prefix) {
+  return withMeta(
+    { path: joinSegment(prefix, key), segment: key, isArray: isArrayNode(node) },
+    node
+  );
+}
+function enumerateRowsPathPickerEntries(startSchema, prefix) {
+  if (startSchema === null) return [];
+  const segments = prefix === "" ? [] : prefix.split(".");
+  if (segments.includes("")) return [];
+  const base = descendToLayer(startSchema, segments);
+  if (base === null) return [];
+  const entries = [];
+  if (base.properties !== void 0) {
+    for (const [key, child] of base.properties) {
+      if (!leadsToArray(child)) continue;
+      entries.push(pickerEntry(key, child, prefix));
+    }
+  }
+  return entries;
+}
 function resolveRowsPathStartSchema(doc, path, rootSchema) {
   if (rootSchema === null) return null;
   if (doc === null || path === null) return rootSchema;
@@ -4949,6 +5005,7 @@ export {
   deleteLayerInDraft,
   enumerateExpressionCandidates,
   enumerateRowsPathCandidates,
+  enumerateRowsPathPickerEntries,
   expressionCallSlotAtEnd,
   expressionDiagnostics,
   expressionFragmentAtCursor,