@braincrew-lab/langchain-canvas 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -52,7 +52,7 @@ interface ChartOptions {
     colors?: string[];
 }
 interface ChartData {
-    chart: "line" | "bar" | "area" | "pie";
+    chart: "line" | "bar" | "area" | "pie" | "scatter" | "donut";
     /** Tidy/long-form rows, consumed directly by the charting library. */
     rows: Array<Record<string, string | number>>;
     /** Category / x-axis field. */
@@ -110,6 +110,14 @@ interface SlideElement {
     shape?: "rect" | "ellipse" | "line";
     /** Fill (rect/ellipse) or stroke (line) color for a shape. */
     fill?: string;
+    /** Rotation in degrees, clockwise, about the element's center. Purely visual:
+     *  `x`/`y`/`w`/`h` always describe the unrotated box. */
+    rotate?: number;
+    /** How an image fills its box — "contain" (default, letterboxed) or "cover"
+     *  (fill and crop). */
+    fit?: "contain" | "cover";
+    /** Corner radius in px (0–32) for images and rect shapes. */
+    radius?: number;
     /** Editor-only grouping: elements sharing a `group` id select and move as
      *  one. Purely additive — exporters and the presenter ignore it. */
     group?: string;
@@ -229,6 +237,16 @@ interface CanvasStatus {
     id: string;
     status: ArtifactStatus;
 }
+/**
+ * Promote the artifact's current state to a described version snapshot.
+ * `revision` is the opaque store revision when a CanvasStore backs the canvas.
+ */
+interface CanvasCommit {
+    type: "canvas.commit";
+    id: string;
+    description: string;
+    revision?: string;
+}
 interface CanvasClose {
     type: "canvas.close";
     id: string;
@@ -241,7 +259,7 @@ interface DoneEvent {
     type: "done";
 }
 type ChatEvent = MessageDelta | MessageEnd | ToolStart | ToolEnd;
-type CanvasEvent = CanvasCreate | CanvasAppend | CanvasPatch | CanvasNodePatch | CanvasReplace | CanvasStatus | CanvasClose;
+type CanvasEvent = CanvasCreate | CanvasAppend | CanvasPatch | CanvasNodePatch | CanvasReplace | CanvasStatus | CanvasCommit | CanvasClose;
 type StreamEvent = ChatEvent | CanvasEvent | ErrorEvent | DoneEvent;
 /** Narrow a `StreamEvent` to the canvas family. */
 declare function isCanvasEvent(event: StreamEvent): event is CanvasEvent;
@@ -508,6 +526,34 @@ declare function useCanvasReplay(): {
  */
 declare function useArtifactPatch(id: string): (patch: Record<string, unknown>) => void;
 
+/**
+ * `useCanvasSave` — debounced whole-artifact persistence for user edits.
+ *
+ * The store's `onUserEdit` handler fires per committed user edit (never for
+ * agent streaming). This hook turns an `onSave` handler into a debounced
+ * per-edit callback for that signal: after `debounceMs` of quiet it hands the
+ * latest reconciled artifact to `onSave`. The host decides where it goes — a
+ * `CanvasStore`-backed endpoint, local storage, anywhere.
+ *
+ * `<Canvas onSave={...}>` wires this automatically (composed with the host's
+ * own `onUserEdit`, both sharing the store's single user-edit slot). Headless
+ * hosts can call the hook themselves and register the returned callback via
+ * `setOnUserEdit`.
+ *
+ * `baseRevision` is the artifact's last known store revision (stamped into
+ * `meta.revision` by `canvas.commit` events); hosts pass it to their save
+ * endpoint so a stale write can be rejected instead of overwriting.
+ */
+
+interface CanvasSavePayload {
+    artifactId: string;
+    artifact: Artifact;
+    /** Store revision the user's edit is based on, when known. */
+    baseRevision: string | null;
+}
+type CanvasSaveHandler = (payload: CanvasSavePayload) => void | Promise<void>;
+declare function useCanvasSave(onSave: CanvasSaveHandler | undefined, debounceMs?: number): ((artifact: Artifact) => void) | null;
+
 /**
  * Schema fixtures — scripted wire-event sequences that render the canvas with no
  * backend. Feed one to `useCanvasReplay().play(scenario.events)`.
@@ -525,6 +571,699 @@ interface Scenario {
 }
 declare const scenarios: Scenario[];
 
+type CanvasLocale = "en" | "ko";
+declare const MESSAGES: {
+    undo: {
+        en: string;
+        ko: string;
+    };
+    redo: {
+        en: string;
+        ko: string;
+    };
+    export: {
+        en: string;
+        ko: string;
+    };
+    openInTab: {
+        en: string;
+        ko: string;
+    };
+    copyHtml: {
+        en: string;
+        ko: string;
+    };
+    copied: {
+        en: string;
+        ko: string;
+    };
+    versionHistory: {
+        en: string;
+        ko: string;
+    };
+    prevVersion: {
+        en: string;
+        ko: string;
+    };
+    nextVersion: {
+        en: string;
+        ko: string;
+    };
+    backToLatest: {
+        en: string;
+        ko: string;
+    };
+    historyNote: {
+        en: string;
+        ko: string;
+    };
+    loading: {
+        en: string;
+        ko: string;
+    };
+    noRenderer: {
+        en: string;
+        ko: string;
+    };
+    writing: {
+        en: string;
+        ko: string;
+    };
+    open: {
+        en: string;
+        ko: string;
+    };
+    kindWeb: {
+        en: string;
+        ko: string;
+    };
+    kindDocument: {
+        en: string;
+        ko: string;
+    };
+    kindChart: {
+        en: string;
+        ko: string;
+    };
+    kindTable: {
+        en: string;
+        ko: string;
+    };
+    kindSlides: {
+        en: string;
+        ko: string;
+    };
+    kindPdf: {
+        en: string;
+        ko: string;
+    };
+    design: {
+        en: string;
+        ko: string;
+    };
+    code: {
+        en: string;
+        ko: string;
+    };
+    add: {
+        en: string;
+        ko: string;
+    };
+    heading: {
+        en: string;
+        ko: string;
+    };
+    text: {
+        en: string;
+        ko: string;
+    };
+    button: {
+        en: string;
+        ko: string;
+    };
+    image: {
+        en: string;
+        ko: string;
+    };
+    divider: {
+        en: string;
+        ko: string;
+    };
+    pageMenu: {
+        en: string;
+        ko: string;
+    };
+    sectionMenu: {
+        en: string;
+        ko: string;
+    };
+    outlineMenu: {
+        en: string;
+        ko: string;
+    };
+    layoutMenu: {
+        en: string;
+        ko: string;
+    };
+    themeMenu: {
+        en: string;
+        ko: string;
+    };
+    fontMenu: {
+        en: string;
+        ko: string;
+    };
+    shapeMenu: {
+        en: string;
+        ko: string;
+    };
+    a11yCheck: {
+        en: string;
+        ko: string;
+    };
+    a11yTitle: {
+        en: string;
+        ko: string;
+    };
+    a11yClean: {
+        en: string;
+        ko: string;
+    };
+    bgImage: {
+        en: string;
+        ko: string;
+    };
+    present: {
+        en: string;
+        ko: string;
+    };
+    bold: {
+        en: string;
+        ko: string;
+    };
+    italic: {
+        en: string;
+        ko: string;
+    };
+    inlineCode: {
+        en: string;
+        ko: string;
+    };
+    bulletList: {
+        en: string;
+        ko: string;
+    };
+    numberedList: {
+        en: string;
+        ko: string;
+    };
+    quote: {
+        en: string;
+        ko: string;
+    };
+    link: {
+        en: string;
+        ko: string;
+    };
+    words: {
+        en: string;
+        ko: string;
+    };
+    minRead: {
+        en: string;
+        ko: string;
+    };
+    addColumn: {
+        en: string;
+        ko: string;
+    };
+    addRow: {
+        en: string;
+        ko: string;
+    };
+    sortBy: {
+        en: string;
+        ko: string;
+    };
+    filterRows: {
+        en: string;
+        ko: string;
+    };
+    cleanStyling: {
+        en: string;
+        ko: string;
+    };
+    freezeHeader: {
+        en: string;
+        ko: string;
+    };
+    fillColor: {
+        en: string;
+        ko: string;
+    };
+    textColor: {
+        en: string;
+        ko: string;
+    };
+    alignLeft: {
+        en: string;
+        ko: string;
+    };
+    alignCenter: {
+        en: string;
+        ko: string;
+    };
+    alignRight: {
+        en: string;
+        ko: string;
+    };
+    numberFormat: {
+        en: string;
+        ko: string;
+    };
+    mergeCells: {
+        en: string;
+        ko: string;
+    };
+    unmergeCells: {
+        en: string;
+        ko: string;
+    };
+    sheetHint: {
+        en: string;
+        ko: string;
+    };
+    quickFunction: {
+        en: string;
+        ko: string;
+    };
+    quickFunctionTip: {
+        en: string;
+        ko: string;
+    };
+    mergeTip: {
+        en: string;
+        ko: string;
+    };
+    unmergeTip: {
+        en: string;
+        ko: string;
+    };
+    cleanStylingTip: {
+        en: string;
+        ko: string;
+    };
+    freezeOnTip: {
+        en: string;
+        ko: string;
+    };
+    freezeOffTip: {
+        en: string;
+        ko: string;
+    };
+    numberFormatTip: {
+        en: string;
+        ko: string;
+    };
+    sortByColumn: {
+        en: string;
+        ko: string;
+    };
+    ascending: {
+        en: string;
+        ko: string;
+    };
+    descending: {
+        en: string;
+        ko: string;
+    };
+    filterTip: {
+        en: string;
+        ko: string;
+    };
+    fxPlaceholder: {
+        en: string;
+        ko: string;
+    };
+    groupInsert: {
+        en: string;
+        ko: string;
+    };
+    groupFont: {
+        en: string;
+        ko: string;
+    };
+    groupAlign: {
+        en: string;
+        ko: string;
+    };
+    groupNumber: {
+        en: string;
+        ko: string;
+    };
+    groupEdit: {
+        en: string;
+        ko: string;
+    };
+    groupView: {
+        en: string;
+        ko: string;
+    };
+    boldGlyph: {
+        en: string;
+        ko: string;
+    };
+    textGlyph: {
+        en: string;
+        ko: string;
+    };
+    autoSum: {
+        en: string;
+        ko: string;
+    };
+    fmtGeneral: {
+        en: string;
+        ko: string;
+    };
+    fmtCurrency: {
+        en: string;
+        ko: string;
+    };
+    fmtPercent: {
+        en: string;
+        ko: string;
+    };
+    fmtThousands: {
+        en: string;
+        ko: string;
+    };
+    fmtDecimal: {
+        en: string;
+        ko: string;
+    };
+    fmtDate: {
+        en: string;
+        ko: string;
+    };
+    chartTitle: {
+        en: string;
+        ko: string;
+    };
+    editData: {
+        en: string;
+        ko: string;
+    };
+    doneEditing: {
+        en: string;
+        ko: string;
+    };
+    addRowBtn: {
+        en: string;
+        ko: string;
+    };
+    downloadPng: {
+        en: string;
+        ko: string;
+    };
+    stacked: {
+        en: string;
+        ko: string;
+    };
+    seriesColor: {
+        en: string;
+        ko: string;
+    };
+    seriesName: {
+        en: string;
+        ko: string;
+    };
+    removeRow: {
+        en: string;
+        ko: string;
+    };
+    addText: {
+        en: string;
+        ko: string;
+    };
+    addImage: {
+        en: string;
+        ko: string;
+    };
+    addShape: {
+        en: string;
+        ko: string;
+    };
+    arrangeMenu: {
+        en: string;
+        ko: string;
+    };
+    padding: {
+        en: string;
+        ko: string;
+    };
+    duplicate: {
+        en: string;
+        ko: string;
+    };
+    delete: {
+        en: string;
+        ko: string;
+    };
+    group: {
+        en: string;
+        ko: string;
+    };
+    ungroup: {
+        en: string;
+        ko: string;
+    };
+    bringToFront: {
+        en: string;
+        ko: string;
+    };
+    sendToBack: {
+        en: string;
+        ko: string;
+    };
+    fontSize: {
+        en: string;
+        ko: string;
+    };
+    resizeTip: {
+        en: string;
+        ko: string;
+    };
+    fitToggle: {
+        en: string;
+        ko: string;
+    };
+    cornerRadius: {
+        en: string;
+        ko: string;
+    };
+    rotateStep: {
+        en: string;
+        ko: string;
+    };
+    rotationDeg: {
+        en: string;
+        ko: string;
+    };
+    duplicateShort: {
+        en: string;
+        ko: string;
+    };
+    bringForward: {
+        en: string;
+        ko: string;
+    };
+    sendBackward: {
+        en: string;
+        ko: string;
+    };
+    groupShort: {
+        en: string;
+        ko: string;
+    };
+    ungroupShort: {
+        en: string;
+        ko: string;
+    };
+    alignLeftEdges: {
+        en: string;
+        ko: string;
+    };
+    alignHCenters: {
+        en: string;
+        ko: string;
+    };
+    alignRightEdges: {
+        en: string;
+        ko: string;
+    };
+    alignTopEdges: {
+        en: string;
+        ko: string;
+    };
+    alignVCenters: {
+        en: string;
+        ko: string;
+    };
+    alignBottomEdges: {
+        en: string;
+        ko: string;
+    };
+    deleteSelection: {
+        en: string;
+        ko: string;
+    };
+    presentHint: {
+        en: string;
+        ko: string;
+    };
+    speakerNotes: {
+        en: string;
+        ko: string;
+    };
+    download: {
+        en: string;
+        ko: string;
+    };
+    openBtn: {
+        en: string;
+        ko: string;
+    };
+    fitWidth: {
+        en: string;
+        ko: string;
+    };
+    zoomIn: {
+        en: string;
+        ko: string;
+    };
+    zoomOut: {
+        en: string;
+        ko: string;
+    };
+    waitingPdf: {
+        en: string;
+        ko: string;
+    };
+    addTextBox: {
+        en: string;
+        ko: string;
+    };
+    addImageTip: {
+        en: string;
+        ko: string;
+    };
+    addShapeTip: {
+        en: string;
+        ko: string;
+    };
+    applyLayout: {
+        en: string;
+        ko: string;
+    };
+    autoLayoutTip: {
+        en: string;
+        ko: string;
+    };
+    bgColor: {
+        en: string;
+        ko: string;
+    };
+    bgImageTip: {
+        en: string;
+        ko: string;
+    };
+    padTip: {
+        en: string;
+        ko: string;
+    };
+    presentTip: {
+        en: string;
+        ko: string;
+    };
+    duplicateSlide: {
+        en: string;
+        ko: string;
+    };
+    deleteSlide: {
+        en: string;
+        ko: string;
+    };
+    theme: {
+        en: string;
+        ko: string;
+    };
+    desktop: {
+        en: string;
+        ko: string;
+    };
+    tablet: {
+        en: string;
+        ko: string;
+    };
+    mobile: {
+        en: string;
+        ko: string;
+    };
+    a11yIssues: {
+        en: string;
+        ko: string;
+    };
+    a11yNone: {
+        en: string;
+        ko: string;
+    };
+    pageTemplateTitle: {
+        en: string;
+        ko: string;
+    };
+    sectionTemplateTitle: {
+        en: string;
+        ko: string;
+    };
+    jumpToHeading: {
+        en: string;
+        ko: string;
+    };
+    insertSlideLayout: {
+        en: string;
+        ko: string;
+    };
+    applySlideTheme: {
+        en: string;
+        ko: string;
+    };
+    insertShape: {
+        en: string;
+        ko: string;
+    };
+    slideFont: {
+        en: string;
+        ko: string;
+    };
+    slideBgImage: {
+        en: string;
+        ko: string;
+    };
+    moveUp: {
+        en: string;
+        ko: string;
+    };
+    moveDown: {
+        en: string;
+        ko: string;
+    };
+    waitingData: {
+        en: string;
+        ko: string;
+    };
+    calculating: {
+        en: string;
+        ko: string;
+    };
+    loadingSheet: {
+        en: string;
+        ko: string;
+    };
+    dropToOpen: {
+        en: string;
+        ko: string;
+    };
+};
+type MessageKey = keyof typeof MESSAGES;
+interface CanvasLocaleProviderProps {
+    locale?: CanvasLocale;
+    children: ReactNode;
+}
+declare function CanvasLocaleProvider({ locale, children }: CanvasLocaleProviderProps): react.JSX.Element;
+declare function useLocale(): CanvasLocale;
+/** `const t = useT(); t("sortBy")` → the label in the canvas's locale. */
+declare function useT(): (key: MessageKey) => string;
+
 interface RendererProps<TData = unknown> {
     artifact: Artifact<TData>;
 }
@@ -543,6 +1282,8 @@ declare function mergeRegistries(...registries: ArtifactRegistry[]): ArtifactReg
 interface CanvasProps {
     /** Renderer map. Defaults to the built-in html/document/chart/table renderers. */
     registry?: ArtifactRegistry;
+    /** UI language for the canvas chrome (toolbars, menus, states). Default "en". */
+    locale?: CanvasLocale;
     /** Rendered when no artifact has been opened yet. */
     emptyState?: ReactNode;
     /**
@@ -559,8 +1300,15 @@ interface CanvasProps {
      * debounce further on the host before hitting the network.
      */
     onUserEdit?: (artifact: Artifact) => void;
+    /**
+     * Persist user edits: the debounced companion to `onUserEdit` (see
+     * `useCanvasSave`). Called after edits go quiet, with the artifact and the
+     * `baseRevision` to hand a store-backed save endpoint. When omitted, edits
+     * stay in-memory exactly as before.
+     */
+    onSave?: CanvasSaveHandler;
 }
-declare function Canvas({ registry, emptyState, onEditElement, onUserEdit }: CanvasProps): react.JSX.Element;
+declare function Canvas({ registry, locale, emptyState, onEditElement, onUserEdit, onSave }: CanvasProps): react.JSX.Element;
 
 interface ExportMenuProps {
     artifact: Artifact;
@@ -695,7 +1443,7 @@ declare function printToPdf(html: string): void;
  */
 
 /** Extensions we can turn into an artifact, for `accept="…"` and drop filtering. */
-declare const IMPORTABLE_EXTENSIONS: readonly [".csv", ".md", ".markdown", ".txt", ".html", ".htm", ".json", ".xlsx", ".pdf", ".hwpx", ".hwp"];
+declare const IMPORTABLE_EXTENSIONS: readonly [".csv", ".md", ".markdown", ".txt", ".html", ".htm", ".json", ".xlsx", ".pdf", ".hwpx", ".hwp", ".docx", ".pptx"];
 /** True when the file has an extension we know how to import. */
 declare const canImport: (file: File) => boolean;
 /**
@@ -720,4 +1468,4 @@ declare function useCanvasImport(): {
     canImport: (file: File) => boolean;
 };
 
-export { type Artifact, ArtifactCard, type ArtifactRegistry, type ArtifactRenderer, type ArtifactStatus, Canvas, type CanvasAppend, type CanvasClose, type CanvasCreate, type CanvasEvent, type CanvasNodePatch, type CanvasPatch, type CanvasProps, CanvasProvider, type CanvasProviderProps, CanvasRegistryProvider, type CanvasReplace, type CanvasState, type CanvasStatus, type CanvasStore, type ChartArtifact, type ChartData, type ChartOptions, ChartRenderer, type ChartSeries, type ChatEvent, type ChatMessage, type ChatRequest, type DocumentArtifact, type DocumentData, DocumentRenderer, type DoneEvent, type ElementSelection, type ErrorEvent, ExportMenu, type FileExport, type HtmlArtifact, type HtmlData, HtmlRenderer, IMPORTABLE_EXTENSIONS, INSPECTOR_MARK, type IframeCommand, type KnownArtifact, type MessageDelta, type MessageEnd, type MockStreamOptions, type PdfArtifact, type PdfData, PdfRenderer, type RendererProps, STYLE_PROPS, type Scenario, SelectionBar, type Slide, type SlideElement, type SlidesArtifact, type SlidesData, SlidesRenderer, type StreamEvent, type StreamOptions, StylePanel, type TableArtifact, type TableColumn, type TableData, TableRenderer, type ToolEnd, type ToolStart, type UseCanvasStreamOptions, type UserEditHandler, builtinRenderers, canImport, createCanvasStore, dataExporters, downloadBlob, emptyCanvasState, importFile, isCanvasEvent, isChatEvent, mergePatch, mergeRegistries, mockStream, parseCsv, parseSSE, printToPdf, reduceCanvas, scenarios, slidesToPrintHtml, slugify, streamChat, toStandaloneHtml, useArtifactPatch, useCanvasImport, useCanvasReplay, useCanvasStore, useCanvasStoreApi, useCanvasStream, useRenderer, withInspector };
+export { type Artifact, ArtifactCard, type ArtifactRegistry, type ArtifactRenderer, type ArtifactStatus, Canvas, type CanvasAppend, type CanvasClose, type CanvasCommit, type CanvasCreate, type CanvasEvent, type CanvasLocale, CanvasLocaleProvider, type CanvasNodePatch, type CanvasPatch, type CanvasProps, CanvasProvider, type CanvasProviderProps, CanvasRegistryProvider, type CanvasReplace, type CanvasSaveHandler, type CanvasSavePayload, type CanvasState, type CanvasStatus, type CanvasStore, type ChartArtifact, type ChartData, type ChartOptions, ChartRenderer, type ChartSeries, type ChatEvent, type ChatMessage, type ChatRequest, type DocumentArtifact, type DocumentData, DocumentRenderer, type DoneEvent, type ElementSelection, type ErrorEvent, ExportMenu, type FileExport, type HtmlArtifact, type HtmlData, HtmlRenderer, IMPORTABLE_EXTENSIONS, INSPECTOR_MARK, type IframeCommand, type KnownArtifact, type MessageDelta, type MessageEnd, type MessageKey, type MockStreamOptions, type PdfArtifact, type PdfData, PdfRenderer, type RendererProps, STYLE_PROPS, type Scenario, SelectionBar, type Slide, type SlideElement, type SlidesArtifact, type SlidesData, SlidesRenderer, type StreamEvent, type StreamOptions, StylePanel, type TableArtifact, type TableColumn, type TableData, TableRenderer, type ToolEnd, type ToolStart, type UseCanvasStreamOptions, type UserEditHandler, builtinRenderers, canImport, createCanvasStore, dataExporters, downloadBlob, emptyCanvasState, importFile, isCanvasEvent, isChatEvent, mergePatch, mergeRegistries, mockStream, parseCsv, parseSSE, printToPdf, reduceCanvas, scenarios, slidesToPrintHtml, slugify, streamChat, toStandaloneHtml, useArtifactPatch, useCanvasImport, useCanvasReplay, useCanvasSave, useCanvasStore, useCanvasStoreApi, useCanvasStream, useLocale, useRenderer, useT, withInspector };