@ai-matrx/office 0.0.0 → 0.2.0

package/dist/core.d.ts

@@ -0,0 +1,397 @@
+import { ComponentType, ReactNode } from 'react';
+export { D as DEFAULT_DOCUMENT_PAGE_STYLE, a as DEFAULT_PAGE_COLOR, P as PAGE_COLORS, b as PAGE_COLOR_KEY, c as PAPER_SIZES, d as PX_PER_INCH, e as PageSetupValues, f as PaperSizeName, g as defaultDocumentPageStyle, i as isLegacySqueezedPageStyle, p as pageSetupCommandParams, h as pageSetupFromStyle } from './document-page-style-BFLrgdLI.js';
+import '@univerjs/core';
+
+/**
+ * The editor chrome's command model — ONE data tree per editor that the menu
+ * bar, the "Menus" search and the keyboard bindings all read. A row exists
+ * only when it runs a real editor command; nothing here is decorative.
+ *
+ * Pure (no React, no DOM beyond KeyboardEvent shape) so the command mapping is
+ * testable with a fake editor port.
+ */
+
+/** A keyboard shortcut. `mod` is Cmd on a Mac and Ctrl elsewhere. */
+type EditorShortcut = {
+    key: string;
+    mod?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    /**
+     * true: the chrome binds this key itself (the editor engine does not).
+     * false/absent: the engine already binds it; the label only tells the truth.
+     */
+    bind?: boolean;
+};
+type IconType$1 = ComponentType<{
+    className?: string;
+}>;
+type EditorMenuAction = {
+    kind: "action";
+    id: string;
+    label: string;
+    icon?: IconType$1;
+    shortcut?: EditorShortcut;
+    /** Extra words the Menus search matches (e.g. "freeze" for "1 row"). */
+    keywords?: string[];
+    run: () => unknown;
+    checked?: () => boolean;
+    /** Only for edit gates (a viewer); never "not built". */
+    disabled?: () => boolean;
+    /**
+     * A Google menu row we cannot run yet: the registered Coming Soon id it announces
+     * (`lib/coming-soon/editor-menus.ts`). Drawn in muted ink; `run` announces the promise.
+     */
+    soon?: string;
+};
+type EditorMenuSubmenu = {
+    kind: "submenu";
+    id: string;
+    label: string;
+    icon?: IconType$1;
+    keywords?: string[];
+    items: EditorMenuEntry[];
+};
+type EditorMenuSeparator = {
+    kind: "separator";
+};
+type EditorMenuEntry = EditorMenuAction | EditorMenuSubmenu | EditorMenuSeparator;
+type EditorMenu = {
+    id: string;
+    label: string;
+    items: EditorMenuEntry[];
+};
+/** One runnable row as the Menus search sees it: the action plus its path. */
+type FlatEditorAction = EditorMenuAction & {
+    path: string[];
+};
+declare function flattenMenus(menus: EditorMenu[]): FlatEditorAction[];
+/** Search the flattened commands: every word must hit the label, path or keywords. */
+declare function searchActions(actions: FlatEditorAction[], query: string, limit?: number): FlatEditorAction[];
+declare function isMacPlatform(): boolean;
+/** "⌘⇧1" on a Mac, "Ctrl+Shift+1" elsewhere — Google's notation. */
+declare function formatShortcut(s: EditorShortcut, mac?: boolean): string;
+declare function matchesShortcut(e: Pick<KeyboardEvent, "key" | "code" | "metaKey" | "ctrlKey" | "shiftKey" | "altKey">, s: EditorShortcut, mac?: boolean): boolean;
+/** The actions whose shortcut the chrome binds itself. */
+declare function boundActions(menus: EditorMenu[]): FlatEditorAction[];
+type ToolbarIconType = ComponentType<{
+    className?: string;
+}>;
+/** One control in an editor's toolbar row (moved unchanged from EditorToolbar.tsx; pure data). */
+type EditorToolbarItem = {
+    kind: "button";
+    id: string;
+    label: string;
+    icon: ToolbarIconType;
+    run: () => unknown;
+    shortcut?: EditorShortcut;
+    active?: boolean;
+    disabled?: boolean;
+} | {
+    kind: "separator";
+    id: string;
+} | {
+    kind: "menu";
+    id: string;
+    label: string;
+    icon?: ToolbarIconType;
+    /** Text shown on the trigger (e.g. "100%", "Arial"). */
+    text?: string;
+    /** Trigger width class for text triggers (keeps the row still as text changes). */
+    widthClass?: string;
+    items: EditorMenuEntry[];
+    disabled?: boolean;
+} | {
+    kind: "node";
+    id: string;
+    node: ReactNode;
+};
+
+/**
+ * The Microsoft 365 look's ribbon — a SECOND PRESENTATION of the editor's ONE command map.
+ *
+ * A ribbon layout is pure data: tabs → groups → controls, where each control names something that
+ * already exists in the editor's model by id —
+ *   - a toolbar item (`tb.bold`, `tb.font`, …) from the same `EditorToolbarItem[]` the Google
+ *     toolbar draws,
+ *   - a menu row (`view.freeze`, `data.filter`, …) from the same `EditorMenu[]` the Google menu
+ *     bar draws (an action runs; a submenu opens as a dropdown),
+ *   - a whole menu (`menu:help`) as one dropdown.
+ * Nothing here runs anything itself, so the two looks cannot drift: `ribbonCoverage` proves every
+ * command of the model is reachable from the ribbon (forcing test per editor).
+ *
+ * Pure (no React) so the mapping is testable with a fake editor host.
+ */
+
+type IconType = ComponentType<{
+    className?: string;
+}>;
+/**
+ * - `large`: icon over a label, a whole column (Office's Paste, Freeze Panes).
+ * - `small`: icon + label in a row, three stacked per column.
+ * - `icon`: an icon (or value dropdown) in a row of tools (Office's Font group).
+ */
+type RibbonSize = "large" | "small" | "icon";
+type RibbonControlSpec = {
+    /** A toolbar item id, a menu entry id, or `menu:<menuId>` for a whole menu. */
+    ref: string;
+    size?: RibbonSize;
+    /** Office's own word for the same command ("Freeze Panes" for Freeze). */
+    label?: string;
+    /** An icon for a row that has none in the model (a large control needs one). */
+    icon?: IconType;
+};
+type RibbonGroupSpec = {
+    id: string;
+    label: string;
+    controls: Array<string | RibbonControlSpec>;
+    /** Icon rows hold this many tools before wrapping to the next row (default 6). */
+    perRow?: number;
+};
+type RibbonTabSpec = {
+    id: string;
+    label: string;
+    groups: RibbonGroupSpec[];
+};
+/** Menu rows (or whole submenus) the Microsoft ribbon deliberately does not place, with the reason. */
+type GoogleOnlyRows = Record<string, string>;
+type ResolvedRibbonControl = {
+    kind: "toolbar";
+    key: string;
+    size: RibbonSize;
+    label?: string | undefined;
+    icon?: IconType | undefined;
+    item: Exclude<EditorToolbarItem, {
+        kind: "separator";
+    }>;
+} | {
+    kind: "action";
+    key: string;
+    size: RibbonSize;
+    label?: string | undefined;
+    icon?: IconType | undefined;
+    action: EditorMenuAction;
+} | {
+    kind: "submenu";
+    key: string;
+    size: RibbonSize;
+    label?: string | undefined;
+    icon?: IconType | undefined;
+    submenu: Pick<EditorMenuSubmenu, "id" | "label" | "icon" | "items">;
+};
+type ResolvedRibbonGroup = {
+    id: string;
+    label: string;
+    perRow: number;
+    controls: ResolvedRibbonControl[];
+};
+type ResolvedRibbonTab = {
+    id: string;
+    label: string;
+    groups: ResolvedRibbonGroup[];
+};
+type Indexed = {
+    kind: "toolbar";
+    item: Exclude<EditorToolbarItem, {
+        kind: "separator";
+    }>;
+} | {
+    kind: "action";
+    action: EditorMenuAction;
+} | {
+    kind: "submenu";
+    submenu: Pick<EditorMenuSubmenu, "id" | "label" | "icon" | "items">;
+};
+/** Every addressable command of one editor: toolbar ids, menu entry ids, `menu:<id>`. */
+declare function indexCommands(menus: EditorMenu[], toolbar: EditorToolbarItem[]): Map<string, Indexed>;
+/**
+ * The layout bound to the live model. A control whose id the model does not hold right now (a
+ * row that exists only in some states, e.g. "Remove image") is left out; empty groups and tabs go.
+ */
+declare function resolveRibbon(tabs: RibbonTabSpec[], menus: EditorMenu[], toolbar: EditorToolbarItem[]): ResolvedRibbonTab[];
+/**
+ * What the ribbon can reach vs. what the model holds. `missingActions`: menu rows no ribbon
+ * control leads to; `missingToolbar`: toolbar tools absent from the ribbon; `unknownRefs`: layout
+ * ids the model does not have (a typo, or a renamed command).
+ */
+declare function ribbonCoverage(tabs: RibbonTabSpec[], menus: EditorMenu[], toolbar: EditorToolbarItem[], googleOnly?: GoogleOnlyRows): {
+    missingActions: string[];
+    badGoogleOnly: string[];
+    wholeMenuRefs: string[];
+    missingToolbar: string[];
+    unknownRefs: string[];
+};
+
+/**
+ * Google parity rows the three editors share: a Coming Soon row (`soon`), Google's Extensions
+ * menu, and the head of Google's Help menu. Pure data (the announce module loads on click), so
+ * the menu builders stay testable without React.
+ */
+
+declare const sep: EditorMenuEntry;
+/** A Google row we cannot run yet: muted, and clicking it announces the registered promise. */
+declare function soon(id: string, label: string, promise: string, opts?: {
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    keywords?: string[];
+    shortcut?: EditorShortcut;
+}): EditorMenuAction;
+type GoogleProduct = "sheets" | "docs" | "slides";
+/** Google's Extensions menu (the host's own tools follow these rows). */
+declare function googleExtensionsMenu(product: GoogleProduct, built?: {
+    macros?: EditorMenuEntry;
+}): EditorMenu;
+/** The head of Google's Help menu; the editor's own rows (shortcuts, function list) follow. */
+declare function googleHelpHead(opts?: {
+    sendFeedback?: () => void;
+}): EditorMenuEntry[];
+
+/**
+ * The Microsoft look's homes for the Google parity rows every editor shares (`google-parity.ts`):
+ * the Help group's head and the Automate tab (add-ins, scripts). Spread into each editor's
+ * ribbon so the shared rows are placed once, the same way.
+ */
+
+declare const HELP_HEAD_CONTROLS: RibbonControlSpec[];
+declare const AUTOMATE_TAB: RibbonTabSpec;
+
+/** The product-neutral page setup every Office editor's Page setup dialog reads and writes. */
+interface PageSetup {
+    size: "letter" | "legal" | "a4" | "a3" | {
+        w: number;
+        h: number;
+        unit: "in" | "mm";
+    };
+    orientation: "portrait" | "landscape";
+    /** Inches. */
+    margins: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    headerFooter?: {
+        header?: string;
+        footer?: string;
+        pageNumbers?: boolean;
+    };
+}
+
+/**
+ * Where each Office product lives. The map is CONFIGURATION, not a constant: the app passes its own
+ * (production `https://sheets.aimatrx.com`, development `http://sheets.localhost:5190`), so links
+ * generated here always match the app that is running.
+ *
+ * The routes are the same on every host: `/` the product's File Home, `/templates`,
+ * `/new?template=<id>`, `/f/<id>` an item.
+ */
+type OfficeProduct = "sheets" | "docs" | "slides" | "bases" | "boards" | "pdf";
+declare const OFFICE_PRODUCTS: readonly OfficeProduct[];
+type OfficeHostMap = Record<OfficeProduct, string>;
+/** Set the product → origin map (an origin such as `https://sheets.aimatrx.com`, no trailing slash needed). Call once at start-up. */
+declare function configureOfficeHosts(map: OfficeHostMap): void;
+/** The configured origin of a product. Throws when the app never configured the hosts. */
+declare function officeOrigin(product: OfficeProduct): string;
+/**
+ * An absolute link into a product: no id is its File Home, an id opens that item (`/f/<id>`).
+ * `sub` appends a path segment (`officeHref("docs", undefined, { sub: "templates" })` is the Templates page).
+ */
+declare function officeHref(product: OfficeProduct, id?: string, o?: {
+    sub?: string;
+}): string;
+
+/**
+ * The Office record rows: the workbook and document rows and their snapshots, exactly as the
+ * `workbench` schema returns them (moved from matrx-frontend `features/data-tables/types`, W1-G1a).
+ * Written out here because a package cannot import an app's generated database types; the app proves
+ * the two agree with a compile-time check against its generated `Database` type.
+ *
+ * `Json` columns are `unknown`: a reader narrows what it reads, nothing is assumed.
+ */
+type WorkbookSource = "created" | "imported_xlsx" | "imported_gsheet" | "imported_csv" | "linked_gsheet";
+type DocumentSource = "created" | "imported_docx" | "imported_md" | "imported_txt" | "linked_gdoc";
+/** `platform.shown_to`. */
+type ShownTo = "only_me" | "my_team" | "everyone" | "everyone_on_ai_matrx";
+/** `platform.visibility`. */
+type Visibility = "personal" | "internal" | "link" | "public";
+/** A row of `workbench.udt_workbooks`. */
+interface Workbook {
+    created_at: string;
+    created_by: string;
+    custom_fields: unknown;
+    deleted_at: string | null;
+    description: string | null;
+    id: string;
+    is_public: boolean;
+    metadata: unknown;
+    organization_id: string;
+    original_file_id: string | null;
+    project_id: string | null;
+    published_to_web: boolean;
+    published_to_web_at: string | null;
+    published_to_web_by: string | null;
+    shown_to: ShownTo | null;
+    source: WorkbookSource;
+    task_id: string | null;
+    updated_at: string;
+    updated_by: string | null;
+    user_id: string;
+    version: number;
+    visibility: Visibility;
+    workbook_name: string;
+}
+/** A row of `workbench.udt_workbook_snapshots`. */
+interface WorkbookSnapshot {
+    created_at: string;
+    created_by: string | null;
+    custom_fields: unknown;
+    id: string;
+    label: string | null;
+    metadata: unknown;
+    organization_id: string;
+    /** Free text in the database; "autosave" | "manual" | "imported" | "restored" by convention. */
+    origin: string;
+    snapshot: unknown;
+    workbook_id: string;
+}
+/** A row of `workbench.udt_documents`. */
+interface DocumentRow {
+    created_at: string;
+    created_by: string;
+    custom_fields: unknown;
+    deleted_at: string | null;
+    description: string | null;
+    document_name: string;
+    id: string;
+    is_public: boolean;
+    metadata: unknown;
+    organization_id: string | null;
+    original_file_id: string | null;
+    project_id: string | null;
+    published_to_web: boolean;
+    published_to_web_at: string | null;
+    published_to_web_by: string | null;
+    shown_to: ShownTo | null;
+    source: DocumentSource;
+    task_id: string | null;
+    updated_at: string;
+    updated_by: string | null;
+    user_id: string;
+    version: number;
+    visibility: Visibility;
+}
+/** A row of `workbench.udt_document_snapshots`. */
+interface DocumentSnapshot {
+    created_at: string;
+    created_by: string | null;
+    custom_fields: unknown;
+    document_id: string;
+    id: string;
+    label: string | null;
+    metadata: unknown;
+    origin: string;
+    snapshot: unknown;
+}
+
+export { AUTOMATE_TAB, type DocumentRow, type DocumentSnapshot, type DocumentSource, type EditorMenu, type EditorMenuAction, type EditorMenuEntry, type EditorMenuSeparator, type EditorMenuSubmenu, type EditorShortcut, type EditorToolbarItem, type FlatEditorAction, type GoogleOnlyRows, type GoogleProduct, HELP_HEAD_CONTROLS, OFFICE_PRODUCTS, type OfficeHostMap, type OfficeProduct, type PageSetup, type ResolvedRibbonControl, type ResolvedRibbonGroup, type ResolvedRibbonTab, type RibbonControlSpec, type RibbonGroupSpec, type RibbonSize, type RibbonTabSpec, type ShownTo, type Visibility, type Workbook, type WorkbookSnapshot, type WorkbookSource, boundActions, configureOfficeHosts, flattenMenus, formatShortcut, googleExtensionsMenu, googleHelpHead, indexCommands, isMacPlatform, matchesShortcut, officeHref, officeOrigin, resolveRibbon, ribbonCoverage, searchActions, sep, soon };