@printstack/print-studio 0.0.0-stage → 0.1.0

package/designer/template-library/registry.d.ts

@@ -0,0 +1,13 @@
+import { TemplateLibraryCatalog, TemplateLibraryProvider } from './types';
+/**
+ * 模板库注册表：按来源（provider）聚合模板。
+ * 同 id 重复注册后者覆盖前者，注销后恢复；单个来源失败不影响其他来源。
+ */
+export declare class TemplateLibraryRegistry {
+    private readonly providers;
+    /** 聚合所有来源的模板；失败的来源记录在 failures 中，由调用方统一上报 */
+    collect(): Promise<TemplateLibraryCatalog>;
+    get(id: string): TemplateLibraryProvider | undefined;
+    list(): TemplateLibraryProvider[];
+    register(provider: TemplateLibraryProvider): () => void;
+}

package/designer/template-library/remote-provider.d.ts

@@ -0,0 +1,25 @@
+import { PrintDocument } from '../../core/types';
+import { TemplateLibraryProvider } from './types';
+/** 远程清单中的模板项：document 内联文档，或 url 指向文档 JSON（相对清单地址解析） */
+export interface RemoteTemplateManifestItem {
+    category?: string;
+    description?: string;
+    document?: PrintDocument;
+    id: string;
+    name: string;
+    url?: string;
+}
+export interface RemoteTemplateManifest {
+    templates: RemoteTemplateManifestItem[];
+}
+export interface RemoteTemplateProviderOptions {
+    /** 自定义请求（鉴权、代理、测试替身）；缺省使用全局 fetch */
+    fetcher?: (url: string, init?: RequestInit) => Promise<Response>;
+    headers?: Record<string, string>;
+    id: string;
+    /** 清单地址，返回 RemoteTemplateManifest JSON */
+    manifestUrl: string;
+    title: () => string;
+}
+/** 远程模板库来源：宿主通过插件 `ctx.templateLibrary.register(createRemoteTemplateProvider(...))` 接入 */
+export declare function createRemoteTemplateProvider(options: RemoteTemplateProviderOptions): TemplateLibraryProvider;

package/designer/template-library/types.d.ts

@@ -0,0 +1,35 @@
+import { PrintDocument } from '../../core/types';
+/** 模板库条目：列表阶段只暴露元信息，文档在选用时才惰性加载（便于远程按需拉取） */
+export interface TemplateLibraryEntry {
+    category?: string;
+    description?: string;
+    id: string;
+    /** 加载完整文档；失败应抛出 DesignerException */
+    load: () => PrintDocument | Promise<PrintDocument>;
+    name: string;
+    remove?: () => Promise<void>;
+    update?: (document: PrintDocument) => Promise<void>;
+}
+/** 模板库来源：内置、远程接口、宿主自定义等均实现此契约后注册 */
+export interface TemplateLibraryProvider {
+    create?: (document: PrintDocument) => Promise<void>;
+    /** 全局唯一标识，如 'builtin'、'my-company:remote' */
+    id: string;
+    list: () => Promise<TemplateLibraryEntry[]> | TemplateLibraryEntry[];
+    /** 来源展示名（分组标题） */
+    title: () => string;
+}
+export interface TemplateLibrarySection {
+    entries: TemplateLibraryEntry[];
+    providerId: string;
+    title: string;
+}
+export interface TemplateLibraryFailure {
+    error: unknown;
+    providerId: string;
+    title: string;
+}
+export interface TemplateLibraryCatalog {
+    failures: TemplateLibraryFailure[];
+    sections: TemplateLibrarySection[];
+}

package/designer/tools.d.ts

@@ -0,0 +1,18 @@
+export interface ToolItem {
+    elementType?: string;
+    icon: string;
+    /** store.view.activeTool 的值：'select' | 'hand' | 'element:<type>' */
+    id: string;
+    kind: 'element' | 'hand' | 'select';
+    label: string;
+    shortcut?: string;
+}
+export declare function buildToolList(registry?: import('../core/element-registry').ElementRegistry): ToolItem[];
+export declare function findToolById(id: string, registry?: import('../core/element-registry').ElementRegistry): ToolItem | undefined;
+/**
+ * 元素创建工具是否对同类型可编辑元素开放内联交互
+ * （文本类工具对齐 PS / AI 文字工具：元素保持可拖动，双击进入内联编辑，
+ * 空白处仍是创建）。数据预览模式下画布展示的是解析后的副本，
+ * 内联编辑会把示例值写回模板，一律排除。
+ */
+export declare function toolOwnsInlineEdit(activeTool: string, nodeType: string, previewWithData: boolean, registry?: import('../core/element-registry').ElementRegistry): boolean;

package/designer/tutorials/builtins.d.ts

@@ -0,0 +1,20 @@
+import { PrintDocument } from '../../core/types';
+import { TutorialDefinition, TutorialStep } from './types';
+export declare const builtinTutorials: TutorialDefinition[];
+export declare function createTutorialDocument(): PrintDocument;
+export declare function tutorialCourseLabel(id: string, key: string): string;
+export declare const TUTORIAL_TABLE_ID = "tutorial-details";
+export declare const tutorialTableColumns: readonly [{
+    readonly align: "left";
+    readonly bind: "name";
+    readonly key: "columnName";
+}, {
+    readonly align: "center";
+    readonly bind: "quantity";
+    readonly key: "columnQuantity";
+}, {
+    readonly align: "right";
+    readonly bind: "amount";
+    readonly key: "columnAmount";
+}];
+export declare const tutorialSteps: TutorialStep[];

package/designer/tutorials/interaction-guard.d.ts

@@ -0,0 +1,3 @@
+/** 教程播放期间需要拦截的全部用户输入事件。 */
+export declare const TUTORIAL_GUARDED_EVENTS: string[];
+export declare function isTutorialInteractionAllowed(event: Event): boolean;

package/designer/tutorials/playback.d.ts

@@ -0,0 +1,17 @@
+import { EditorContext } from '../context/editor-context';
+import { TutorialOperation, TutorialTarget } from './types';
+export declare function resolveTutorialTarget(ctx: EditorContext, root: HTMLElement, target: TutorialTarget): HTMLElement | undefined;
+export declare function waitForTutorialDelay(duration: number, signal: AbortSignal): Promise<void>;
+export interface TutorialPerformOptions {
+    /** 恢复重放：不等待演示节奏，目标限时查找 */
+    replay?: boolean;
+}
+export declare function performTutorialOperation(ctx: EditorContext, root: HTMLElement, operation: TutorialOperation, signal: AbortSignal, options?: TutorialPerformOptions): Promise<void>;
+/**
+ * 流程恢复：当前操作所需的界面或数据上下文缺失时，
+ * 先关闭残留界面，再按分组重放前置操作，使目标重新出现。
+ * - 当前操作引用的教程元素若由其他分组生成，先重放该生成分组（已存在的元素不会重复创建）；
+ * - 随后重放当前分组中位于当前操作之前的全部操作。
+ * 每个分组都从稳定状态开始，且提交类操作位于分组末尾，因此重放不会重复提交。
+ */
+export declare function restoreTutorialContext(ctx: EditorContext, root: HTMLElement, operations: TutorialOperation[], index: number, signal: AbortSignal): Promise<void>;

package/designer/tutorials/scene.d.ts

@@ -0,0 +1,11 @@
+import { EditorContext } from '../context/editor-context';
+import { UiRestoreState } from '../stores/types';
+type SceneAction = (ctx: EditorContext) => void;
+export declare function createTutorialScene(): {
+    capture: () => SceneAction;
+    closeUi: () => void;
+    openContextMenu: (ids: string[], args?: string[]) => void;
+    remember: (action: SceneAction) => void;
+    updateUi: (patch: Partial<UiRestoreState>) => void;
+};
+export {};

package/designer/tutorials/screenplay.d.ts

@@ -0,0 +1,3 @@
+import { ElementDefinition } from '../../core/element-registry';
+import { TutorialDefinition, TutorialOperation } from './types';
+export declare function buildTutorialOperations(course: TutorialDefinition, definition?: ElementDefinition): TutorialOperation[];

package/designer/tutorials/types.d.ts

@@ -0,0 +1,64 @@
+import { EditorContext } from '../context/editor-context';
+import { createDataSourceStore } from '../stores/data-source-store';
+import { createDocumentStore } from '../stores/document-store';
+import { createElementStore } from '../stores/element-store';
+import { createFollowBlockStore } from '../stores/follow-block-store';
+import { createPageStore } from '../stores/page-store';
+import { createTemplateStore } from '../stores/template-store';
+import { createViewStore } from '../stores/view-store';
+export interface TutorialEditor {
+    dataSource: Pick<ReturnType<typeof createDataSourceStore>, 'upsert'>;
+    document: Pick<ReturnType<typeof createDocumentStore>, 'data' | 'rename'>;
+    element: Pick<ReturnType<typeof createElementStore>, 'add' | 'updateProps'>;
+    followBlock: Pick<ReturnType<typeof createFollowBlockStore>, 'create'>;
+    page: Pick<ReturnType<typeof createPageStore>, 'add' | 'setActive' | 'update'>;
+    template: Pick<ReturnType<typeof createTemplateStore>, 'applyToPages' | 'create' | 'enterEdit' | 'exitEdit' | 'update' | 'updatePage'>;
+    view: Pick<ReturnType<typeof createViewStore>, 'updateSettings'>;
+}
+export interface TutorialDefinition {
+    height: number;
+    id: string;
+    itemCount: number;
+    width: number;
+}
+export interface TutorialStep {
+    apply?: (editor: TutorialEditor, course: TutorialDefinition) => void;
+    id: string;
+    target: 'canvas' | 'menu';
+}
+export interface TutorialTarget {
+    input?: boolean;
+    selector: string;
+    text?: string;
+}
+export type TutorialContextKey = 'template-edit';
+export interface TutorialOperation {
+    action: 'click' | 'command' | 'contextmenu' | 'draw' | 'input' | 'inspect';
+    args?: (context: EditorContext) => unknown[];
+    body: string;
+    command?: string;
+    drawing?: {
+        height: number;
+        width: number;
+        x: number;
+        y: number;
+    };
+    /** 该操作产出的教程元素 id，用于恢复选区并避免重放时重复创建。 */
+    elementId?: string;
+    /** 流程分组：同组操作共享一段界面上下文，目标丢失时从组首重放以恢复 */
+    group?: number;
+    id: string;
+    inputs?: {
+        target: TutorialTarget;
+        value?: string;
+    }[];
+    /** 本操作建立的界面状态；与 requires 配对，用于状态丢失时重建 */
+    provides?: TutorialContextKey;
+    /** 本操作依赖的持续性界面状态（如模板编辑模式），丢失时先重建再重放分组 */
+    requires?: TutorialContextKey;
+    restore?: (context: EditorContext) => void;
+    target: TutorialTarget;
+    title: string;
+    value?: string;
+}
+export type TutorialScript = (() => TutorialOperation[]) | TutorialOperation[];

package/designer/tutorials/use-tutorial-interaction-guard.d.ts

@@ -0,0 +1,2 @@
+import { EditorContext } from '../context/editor-context';
+export declare function useTutorialInteractionGuard(ctx: EditorContext, getRoot: () => HTMLElement | undefined): void;

package/designer/tutorials/use-tutorial-playback.d.ts

@@ -0,0 +1,30 @@
+import { EditorContext } from '../context/editor-context';
+export declare function useTutorialPlayback(ctx: EditorContext, getRoot: () => HTMLElement | undefined): {
+    demonstrate: () => Promise<void>;
+    drawingStyle: import('vue').ComputedRef<{
+        '--tutorial-drag-x'?: undefined;
+        '--tutorial-drag-y'?: undefined;
+        height?: undefined;
+        left?: undefined;
+        top?: undefined;
+        width?: undefined;
+    } | {
+        '--tutorial-drag-x': string;
+        '--tutorial-drag-y': string;
+        height: string;
+        left: string;
+        top: string;
+        width: string;
+    }>;
+    pause: () => Promise<void>;
+    previous: () => Promise<void>;
+    ringStyle: import('vue').ComputedRef<{
+        height: string;
+        left: string;
+        top: string;
+        width: string;
+    }>;
+    seek: (index: number) => Promise<void>;
+    target: import('vue').Ref<HTMLElement | undefined, HTMLElement | undefined>;
+    togglePlaying: () => void;
+};

package/designer/types.d.ts

@@ -0,0 +1,39 @@
+import { DesignerSettings } from '../core/events';
+import { DesignStudio, PrintStudioOptions } from '../studio-types';
+import { EditorContext } from './context/editor-context';
+import { PluginInput } from './plugins/types';
+import { DesignerPresets } from './presets';
+export interface DesignerOptions {
+    plugins?: PluginInput[];
+    presets?: DesignerPresets;
+    settings?: Partial<DesignerSettings>;
+    ui?: {
+        infoBar?: boolean;
+        menuBar?: boolean;
+        optionsBar?: boolean;
+        panels?: boolean;
+        toolBar?: boolean;
+    };
+    zIndex?: number;
+}
+export interface PrintDesignerProps extends DesignerOptions, Pick<PrintStudioOptions, 'elements' | 'initialDocument' | 'onSave' | 'parsers' | 'rendering' | 'storage'> {
+    context?: EditorContext;
+    studio?: DesignStudio;
+}
+export interface MountPrintDesignerOptions extends DesignerOptions, PrintStudioOptions {
+    onDirtyChange?: (dirty: boolean) => void;
+    onError?: (error: unknown) => void;
+    studio?: DesignStudio;
+}
+/** 设计器界面挂载选项；工作区创建选项在工作区创建时配置 */
+export interface StudioMountOptions extends DesignerOptions {
+    /** 挂载容器元素或 CSS 选择器；容器需要有明确高度 */
+    el: HTMLElement | string;
+    onDirtyChange?: (dirty: boolean) => void;
+    onError?: (error: unknown) => void;
+}
+export interface MountedPrintDesigner {
+    readonly ready: Promise<void>;
+    readonly studio: DesignStudio;
+    unmount(): void;
+}

package/designer.d.ts

@@ -0,0 +1,7 @@
+export { mountPrintDesigner } from './designer/mount-print-designer';
+export type { DesignerPlugin } from './designer/plugins/types';
+export type { DesignerPresets } from './designer/presets';
+export { createRemoteTemplateProvider } from './designer/template-library/remote-provider';
+export type { RemoteTemplateManifest, RemoteTemplateProviderOptions, } from './designer/template-library/remote-provider';
+export type { TemplateLibraryEntry, TemplateLibraryProvider, } from './designer/template-library/types';
+export type { DesignerOptions, MountedPrintDesigner, MountPrintDesignerOptions, StudioMountOptions, } from './designer/types';

package/designer.js

@@ -0,0 +1,45 @@
+import { t as e } from "./mount-print-designer-BzHLGlv-.js";
+import { A as t, B as n } from "./cloneDeep-C5UZRjbH.js";
+// src/designer/template-library/remote-provider.ts
+function r(e) {
+	let r = e.fetcher ?? ((e, t) => fetch(e, t));
+	function i(e, r) {
+		return new t(n("designer.templateLibrary.remoteFailed", { url: e }), {
+			cause: r,
+			code: "template-library.remote-failed"
+		});
+	}
+	async function a(t) {
+		try {
+			let n = await r(t, { headers: e.headers });
+			if (!n.ok) throw Error(`HTTP ${n.status}`);
+			return await n.json();
+		} catch (e) {
+			throw i(t, e);
+		}
+	}
+	function o(t) {
+		return {
+			category: t.category,
+			description: t.description,
+			id: t.id,
+			async load() {
+				if (t.document) return t.document;
+				if (!t.url) throw i(t.id);
+				let n = new URL(e.manifestUrl, location.href);
+				return await a(new URL(t.url, n).href);
+			},
+			name: t.name
+		};
+	}
+	return {
+		id: e.id,
+		async list() {
+			let t = await a(e.manifestUrl);
+			if (!Array.isArray(t?.templates)) throw i(e.manifestUrl);
+			return t.templates.map(o);
+		},
+		title: e.title
+	};
+}
+export { r as createRemoteTemplateProvider, e as mountPrintDesigner };