@xiongtao.xt/tau-plugins 0.18.0 → 0.20.0

package/types/packages/editor/src/{ui → core/ui}/Tooltip.d.ts

@@ -1,4 +1,4 @@
-import { type TooltipProps } from "../../../ui/src/index";
+import { type TooltipProps } from "../../../../ui/src/index";
 /**
  * 编辑器内的提示：外观同 @tau/ui，层级抬到悬浮工具条（z 9999）与编辑器浮层（~10100）之上，
  * 否则工具条按钮的提示会被工具条自身盖住。

package/types/packages/editor/src/{utils → core/utils}/blockNavigation.d.ts

@@ -22,7 +22,7 @@ export declare const registerBlockNavigation: (element: SlateElement, handler: B
 export declare const unregisterBlockNavigation: (element: SlateElement) => void;
 export declare const hasBlockNavigation: (element: SlateElement) => boolean;
 export declare const focusElementByNavigator: (editor: Editor, element: SlateElement, position: BlockFocusPosition, meta: BlockNavigationMeta) => boolean;
-export declare const getSiblingBlockEntry: (editor: Editor, fromPath: Path, direction: BlockNavigationDirection) => NodeEntry<import("../../api").ParagraphElement> | undefined;
+export declare const getSiblingBlockEntry: (editor: Editor, fromPath: Path, direction: BlockNavigationDirection) => NodeEntry<import("../../../api").ParagraphElement> | undefined;
 export declare const focusPreviousBlock: (editor: Editor, fromPath: Path, meta: BlockNavigationMeta) => boolean;
 export declare const focusNextBlock: (editor: Editor, fromPath: Path, meta: BlockNavigationMeta) => boolean;
 export declare const hasBlockNavigationBoundary: (editor: Editor, path: Path) => boolean;

package/types/packages/markdown/src/codec.d.ts

@@ -41,7 +41,7 @@ export interface MarkdownCodec {
      */
     fence?: {
         language: string | readonly string[];
-        /** 源码落进元素的字段名，默认 "content"（mermaid 用 "chart"） */
+        /** 源码落进元素的字段名，默认 "content"，由领域声明覆盖。 */
         property?: string;
     };
     /**
@@ -69,7 +69,7 @@ export interface MarkdownCodec {
         parent: Descendant | null;
         previousSibling: Descendant | null;
         nextSibling: Descendant | null;
-        /** 把块级子元素降级为行内形态（image→inline-image、html-block→html-inline），无声明则原样返回 */
+        /** 按领域声明把块级子元素降级为行内形态，无声明则原样返回。 */
         demote: (child: Descendant) => Descendant;
     }) => Descendant[] | null;
     /** 按目标类型贡献规范化，先于该类型自身 normalize；按 codec 顺序首个非 null 替换生效。 */

package/types/packages/plugins/src/categories.d.ts

@@ -0,0 +1,40 @@
+/** 插件中心分类按扩展点划分，顺序即展示顺序；新增面向用户的扩展点时同步扩充。 */
+export declare const PLUGIN_CATEGORIES: readonly [{
+    readonly id: "sync";
+    readonly label: "同步";
+}, {
+    readonly id: "upload";
+    readonly label: "资源上传";
+}, {
+    readonly id: "editor";
+    readonly label: "编辑器";
+}, {
+    readonly id: "whiteboard";
+    readonly label: "白板";
+}, {
+    readonly id: "blog-template";
+    readonly label: "博客模板";
+}, {
+    readonly id: "ai";
+    readonly label: "AI";
+}, {
+    readonly id: "voice";
+    readonly label: "语音";
+}, {
+    readonly id: "page";
+    readonly label: "页面";
+}];
+export type PluginCategory = (typeof PLUGIN_CATEGORIES)[number]["id"];
+export declare const PLUGIN_KEYWORD_LIMIT = 5;
+export declare const PLUGIN_KEYWORD_MAX_LENGTH = 20;
+export declare const isPluginCategory: (value: unknown) => value is PluginCategory;
+export interface PluginCatalogFields {
+    categories?: readonly PluginCategory[];
+    keywords?: readonly string[];
+}
+/**
+ * 读取 manifest 中的分类与关键词。
+ * strict 用于门户上传，非法值直接报错；客户端用宽松模式静默丢弃，
+ * 使老客户端不会因词表新增或上限调整而拒收插件。
+ */
+export declare function readCatalogFields(item: Record<string, unknown>, strict: boolean): PluginCatalogFields;

package/types/packages/plugins/src/ids.d.ts

@@ -0,0 +1 @@
+export declare function assertLocalId(value: string): void;

package/types/packages/plugins/src/inline-source.d.ts

@@ -1,16 +1,5 @@
-import type { ReactElement } from "react";
-import type { Editor, Element } from "slate";
-import type { PluginRuntimeStyleCompiler } from "./source-editor";
-export interface InlineSourceRuntime {
-    useInlineSource(element: Element): {
-        readOnly: boolean;
-        compiler: PluginRuntimeStyleCompiler | undefined;
-        update(properties: Record<string, unknown>): void;
-        remove(): void;
-    };
-    insertInlineSource(editor: Editor, element: Element): void;
-    InlineSourceBoundary(): ReactElement;
-}
+import type { InlineSourceRuntime } from "../../editor/source-contracts";
+export type { InlineSourceRuntime } from "../../editor/source-contracts";
 export declare function configureInlineSource(value: InlineSourceRuntime): void;
 export declare const useInlineSource: InlineSourceRuntime["useInlineSource"];
 export declare const insertInlineSource: InlineSourceRuntime["insertInlineSource"];

package/types/packages/plugins/src/package.d.ts

@@ -0,0 +1,38 @@
+export { assertLocalId } from "./ids";
+import { type PluginCategory } from "./categories";
+export { comparePluginVersions } from "./version";
+export { PLUGIN_CATEGORIES, PLUGIN_KEYWORD_LIMIT, PLUGIN_KEYWORD_MAX_LENGTH, isPluginCategory, type PluginCategory, } from "./categories";
+export declare const PLUGIN_SHARED_MODULES: readonly ["@tau/plugins", "@tau/plugins/whiteboard", "@tau/plugins/sync", "@tau/ui", "react", "react-dom", "react-dom/client", "react/jsx-runtime", "react/jsx-dev-runtime"];
+export interface PluginManifest {
+    formatVersion: 1;
+    id: string;
+    name: string;
+    version: string;
+    minAppVersion?: string;
+    apiVersion: 1;
+    platform: "desktop";
+    format: "cjs";
+    main: string;
+    /** 无界面的同步存储入口，Node产物与UI入口分别校验。 */
+    styles?: string;
+    /** 静态编辑器贡献在窗口启动时装配，启停需重启。 */
+    editor?: true;
+    whiteboard?: true;
+    /** 插件中心分类，作者自填，不与实际注册对账。 */
+    categories?: readonly PluginCategory[];
+    /** 仅参与搜索匹配。 */
+    keywords?: readonly string[];
+    integrity: Record<string, string>;
+}
+/** 宿主内部传输的已读取产物，不属于作者运行时 API。 */
+export interface DevelopmentPluginPackage {
+    manifest: PluginManifest;
+    code: string;
+    css?: string;
+}
+/** strict 供门户上传使用：分类或关键词不合规时报错，客户端默认静默丢弃。 */
+export declare function validatePluginManifest(value: unknown, options?: {
+    strict?: boolean;
+}): PluginManifest;
+/** 静态内容贡献在启动时固定，启停与更新需要重启。 */
+export declare const isContentPlugin: (manifest: Pick<PluginManifest, "editor" | "whiteboard">) => boolean;

package/types/packages/plugins/src/publish-artifacts.d.ts

@@ -0,0 +1,14 @@
+export { validatePluginManifest, PLUGIN_SHARED_MODULES } from "./package";
+import type { DevelopmentPluginPackage } from "./package";
+export declare const PLUGIN_RENDER_VERSION: 1;
+export type { PublishedPluginRender } from "./render-artifact";
+/** 协议层只检查贡献归属，具体扩展类型由模板选用的渲染器解释。 */
+export interface EvaluatedPluginDefinition {
+    id: string;
+    name: string;
+    version: string;
+    apiVersion: 1;
+    editorExtensions?: readonly unknown[];
+}
+export declare function evaluatePluginPackage(artifact: DevelopmentPluginPackage, modules: Readonly<Record<string, unknown>>): EvaluatedPluginDefinition;
+export declare function assertRenderTypes(definition: EvaluatedPluginDefinition, types: string[]): void;

package/types/packages/plugins/src/publish-client.d.ts

@@ -0,0 +1,8 @@
+import type { DataClient } from "./publish-data";
+export declare class DataError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare function createClient({ manifestUrl }: {
+    manifestUrl: string;
+}): DataClient;

package/types/packages/plugins/src/publish-data.d.ts

@@ -0,0 +1,280 @@
+/** 发布数据协议不包含公开路由、DOM、组件或宿主生命周期。 */
+export type DataKind = "home" | "card" | "article" | "doc" | "quest" | "list";
+export interface ContentRef {
+    key: string;
+    type: DataKind;
+    id?: number;
+}
+export interface ResourceRef {
+    href: string;
+    integrity: string;
+}
+export interface ManifestItem extends ContentRef {
+    collectionType?: "card" | "article" | "doc" | "quest";
+    title: string;
+    projectId?: number;
+    data: string;
+    integrity: string;
+}
+export interface SiteData {
+    title: string;
+    description: string;
+    basePath: string;
+    publicUrl?: string;
+    favicon?: {
+        href: string;
+        format: "svg" | "png" | "ico";
+        mimeType: string;
+    };
+}
+export interface PublishSettings {
+    appearance?: {
+        image?: {
+            borderRadius?: string;
+            shadow?: string | boolean;
+        };
+    };
+}
+/** 站点级数据只在清单中出现一次，各内容文件不重复携带。 */
+export interface DataManifest {
+    version: 1;
+    site: SiteData;
+    search: {
+        data: string;
+        integrity: string;
+    };
+    items: ManifestItem[];
+    settings?: PublishSettings;
+    collections?: Collection[];
+    cardTagTree?: CardTagTree[];
+    /** 键为项目 id。 */
+    projectTrees?: Record<string, TreeItem[]>;
+}
+export interface ContentNode {
+    [field: string]: unknown;
+    text?: string;
+    type?: string;
+    children?: ContentNode[];
+}
+export interface TreeItem {
+    title: string;
+    target?: ContentRef;
+    children?: TreeItem[];
+}
+export interface Collection {
+    type: "project";
+    label: string;
+    items: {
+        id: number;
+        title: string;
+        target: ContentRef;
+        kind: "project";
+    }[];
+}
+export interface RelatedCard {
+    id: number;
+    target: ContentRef;
+    summary: string;
+    tags: string[];
+}
+export interface CardData {
+    id: number;
+    content: ContentNode[];
+    tags: string[];
+    createTime: number;
+    updateTime: number;
+    linkedCards?: RelatedCard[];
+}
+export interface ArticleData extends Omit<CardData, "linkedCards"> {
+    title: string;
+    author: string;
+    bannerBg?: string;
+}
+export interface DocData {
+    id: number;
+    projectId: number;
+    title: string;
+    content: ContentNode[];
+    breadcrumb: {
+        label: string;
+        target?: ContentRef;
+    }[];
+    prevPage?: {
+        title: string;
+        target: ContentRef;
+    };
+    nextPage?: {
+        title: string;
+        target: ContentRef;
+    };
+    createTime: number;
+    updateTime: number;
+}
+export type QuestStatus = "not_started" | "in_progress" | "resolved";
+export interface QuestAnswer {
+    id: number;
+    createTime: number;
+    updateTime: number;
+    content?: ContentNode[];
+    source?: {
+        type: "card" | "article" | "project-item" | "custom";
+        id?: number;
+        contentId: number;
+        target?: ContentRef;
+        title?: string;
+        published: boolean;
+    };
+}
+export interface QuestMaterial {
+    index: number;
+    kind: string;
+    group: "external" | "note" | "discussion";
+    title: string;
+    meta: string;
+    excerpt: string;
+    note?: string;
+    target?: ContentRef;
+    url?: string;
+    citeKey?: string;
+}
+export interface QuestTrail {
+    time: number;
+    tone: "start" | "milestone" | "plain" | "note" | "done";
+    text: string;
+    refs: number[];
+}
+export interface QuestData {
+    id: number;
+    title: string;
+    summary: string;
+    target: ContentRef;
+    groupId: number;
+    groupTitle: string;
+    groupColor?: string;
+    status: QuestStatus;
+    answers: QuestAnswer[];
+    materials: QuestMaterial[];
+    trail: QuestTrail[];
+    description?: ContentNode[];
+    createTime: number;
+    updateTime: number;
+    resolvedTime?: number | null;
+}
+export interface TimelineItem {
+    type: "card" | "article" | "doc" | "quest";
+    id: number;
+    title?: string;
+    summary: string;
+    target: ContentRef;
+    tags: string[];
+    publishTime: number;
+}
+export interface HomeData {
+    hero?: {
+        title: string;
+        description: string;
+    };
+    timeline: TimelineItem[];
+    stats: {
+        articles: number;
+        cards: number;
+    };
+    docStats: {
+        projects: number;
+    };
+}
+export interface ListItem {
+    id: number;
+    title?: string;
+    summary: string;
+    target: ContentRef;
+    tags: string[];
+    createTime: number;
+    updateTime?: number;
+    groupId?: number;
+    groupTitle?: string;
+    status?: QuestStatus;
+    answerCount?: number;
+}
+export interface ListData {
+    title: string;
+    type: "card" | "article" | "doc" | "quest";
+    items: ListItem[];
+    tags?: {
+        name: string;
+        count: number;
+    }[];
+}
+export interface CardTagTree {
+    tag: string;
+    count: number;
+    cards: {
+        id: number;
+        summary: string;
+        target: ContentRef;
+        createTime: number;
+    }[];
+    children?: CardTagTree[];
+}
+export interface PublishedCommon {
+    version: 1;
+    key: string;
+    /** 本文正文里已发布的站内链接目标，键与 QuestMaterial.citeKey 同一口径；未发布的链接不在其中。 */
+    links?: Record<string, ContentRef>;
+    pluginRenderers?: import("./render-artifact").PublishedPluginRender[];
+    contentStyles?: ResourceRef[];
+}
+export type PublishedData = {
+    [K in DataKind]: PublishedCommon & {
+        meta: {
+            type: K;
+            publishTime: number;
+        };
+        content: {
+            home: HomeData;
+            card: CardData;
+            article: ArticleData;
+            doc: DocData;
+            quest: QuestData;
+            list: ListData;
+        }[K];
+    };
+}[DataKind];
+export interface DataResult {
+    data: PublishedData;
+    dataUrl: string;
+    /** 清单中的发布设置，由客户端随正文带回。 */
+    settings?: PublishSettings;
+}
+export interface SearchDocument extends ContentRef {
+    type: "card" | "article" | "doc" | "quest";
+    title: string;
+    summary: string;
+    content: string;
+    tags: string[];
+}
+export interface SearchFile {
+    version: 1;
+    documents: SearchDocument[];
+}
+export interface SearchMatch {
+    field: "title" | "summary" | "content" | "tags";
+    text: string;
+    ranges: [number, number][];
+}
+export interface SearchHit extends Omit<SearchDocument, "content"> {
+    matches?: SearchMatch[];
+}
+export interface DataClient {
+    readManifest(options?: {
+        signal?: AbortSignal;
+    }): Promise<DataManifest>;
+    readData(options: {
+        key: string;
+        signal?: AbortSignal;
+    }): Promise<DataResult>;
+    search(query: string, options?: {
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<SearchHit[]>;
+}

package/types/packages/plugins/src/render-artifact.d.ts

@@ -0,0 +1,9 @@
+import type { PluginManifest } from "./package";
+/** 发布内容只携带插件产物元数据，不依赖编辑器或 UI 类型。 */
+export interface PublishedPluginRender {
+    runtimeVersion: 1;
+    manifest: PluginManifest;
+    entry: string;
+    styles?: string;
+    nodeTypes: string[];
+}

package/types/packages/plugins/src/source-editor.d.ts

@@ -1,41 +1,5 @@
-import type { ReactNode, ReactElement } from "react";
-import type { LucideIcon } from "lucide-react";
-import type { Editor, Element, Path } from "slate";
-import type { ElementBehaviors, ParagraphElement, BlockElement } from "../../editor/api";
-export interface SourceBlockEditorProps {
-    mode: string;
-    title: string;
-    icon: LucideIcon;
-    initValue: string;
-    onChange(value: string): void;
-    element: Element;
-    center?: boolean;
-    extend?: boolean;
-    fluid?: boolean;
-    children?: ReactNode;
-}
-export interface PluginRuntimeStyleCompiler {
-    compile(request: {
-        source: string;
-        language: "html" | "tsx";
-    }): Promise<string>;
-}
-export interface SourceEditorRuntime {
-    SourceBlockEditor(props: SourceBlockEditorProps): ReactElement;
-    useSourceBlock(element: Element): {
-        theme: {
-            isDark: boolean;
-            token(word: string): string;
-        };
-        compiler: PluginRuntimeStyleCompiler | undefined;
-        update(properties: Record<string, unknown>): void;
-    };
-    useReportPreviewError(error: string | null, options?: {
-        stale?: boolean;
-    }): boolean;
-    insertSourceBlock(editor: Editor, element: BlockElement, line?: number): Path | undefined;
-    sourceBlockParagraphBehavior(type: string): ElementBehaviors<ParagraphElement>;
-}
+import type { SourceEditorRuntime } from "../../editor/source-contracts";
+export type { SourceBlockEditorProps, RuntimeStyleCompiler as PluginRuntimeStyleCompiler, SourceEditorRuntime, } from "../../editor/source-contracts";
 export declare function configureSourceEditor(value: SourceEditorRuntime): void;
 export declare const SourceBlockEditor: SourceEditorRuntime["SourceBlockEditor"];
 export declare const useSourceBlock: SourceEditorRuntime["useSourceBlock"];

package/types/packages/plugins/src/version.d.ts

@@ -0,0 +1,4 @@
+export declare function comparePluginVersions(left: string, right: string): number;
+export declare function assertPluginCompatibility(manifest: {
+    minAppVersion?: string;
+}, clientVersion: string): void;

package/types/packages/editor/src/types/text.d.ts

@@ -1 +0,0 @@
-export type { FormattedText } from "../../../markdown/src/model";