@zh-xx/antu 0.14.0 → 0.15.0

package/embed/antu-embed.d.ts

@@ -12,6 +12,33 @@ export interface AntuSpec {
 export type AntuTheme = 'document' | 'modern' | 'legal'
 export type AntuLang = 'zh' | 'en'
 
+/**
+ * How a mounted diagram opens and what it shows (issue 200). Every value a reader can change may be set here:
+ * the theme and language, the label card and dock folds, and every switch of the flowchart and route map.
+ * Unknown keys, wrong types and values outside an enum make `mount` throw.
+ */
+export interface AntuViewState {
+  theme?: AntuTheme
+  lang?: AntuLang
+  shell?: { headerFolded?: boolean; dockFolded?: boolean }
+  view?: {
+    flow?: {
+      states?: boolean
+      conditions?: boolean
+      detail?: boolean
+      mainLine?: boolean
+      stages?: boolean
+      rules?: boolean
+      orientation?: 'vertical' | 'horizontal'
+      linkStyle?: 'straight' | 'curved'
+    }
+    route?: { labels?: boolean; states?: boolean }
+  }
+}
+
+/** The names `persist` may list: one per prefs key whose write may reach the host's store */
+export type AntuPersistName = 'theme' | 'lang' | 'kind' | 'shell.headerFolded' | 'shell.dockFolded' | 'view.flow' | 'view.route'
+
 /** A source as written in the spec's `sources` (`loc` is shaped by the source's `type`, e.g. a contract's { file, clause, page }) */
 export interface AntuSource {
   id: string
@@ -51,12 +78,27 @@ export interface MountOptions {
   theme?: AntuTheme
   /** The language of the page's own words; the case is never translated. Default: the browser's. */
   lang?: AntuLang
-  /** Pieces of the page's chrome to leave out; all shown by default */
-  ui?: { header?: boolean; capsule?: boolean; minimap?: boolean; zoom?: boolean }
+  /**
+   * Pieces of the page's chrome to leave out; all shown by default.
+   * `panOnScroll: false` lets the wheel scroll the host page (a chat card).
+   * `panOnDrag: false` stops press-and-drag from panning. See `cardUi`.
+   */
+  ui?: {
+    header?: boolean
+    capsule?: boolean
+    minimap?: boolean
+    zoom?: boolean
+    panOnScroll?: boolean
+    panOnDrag?: boolean
+  }
   /** Where the reader's choices are kept: 'none' (default) while mounted only, 'local' in the viewer page's localStorage key, or the host's store */
   prefs?: 'none' | 'local' | AntuPrefsStore
-  /** How it opens, ahead of the reader's stored choices (the reader can still change it). An unknown key or a wrong value: `mount` throws. */
-  initial?: { headerFolded?: boolean }
+  /** How it opens, ahead of the reader's stored choices (the reader can still change it). `headerFolded` is the old alias of `shell.headerFolded`. An unknown key or a wrong value: `mount` throws. */
+  initial?: AntuViewState & { headerFolded?: boolean }
+  /** Values forced for this mount; their controls are hidden (a locked `shell.dockFolded: true` hides the dock). An unknown key or a wrong value: `mount` throws. */
+  locked?: AntuViewState
+  /** Which of the reader's changes reach the prefs store: true (all, the default), false (none, kept while mounted), or a list of names. An unknown name or a wrong type: `mount` throws. */
+  persist?: boolean | AntuPersistName[]
   onEvent?: (event: AntuEvent) => void
 }
 
@@ -85,6 +127,18 @@ export interface AntuHandle {
 /** Draw `spec` inside `element` (in a shadow root; the element needs a height). Throws if one is already mounted there, or if `kind`/`kinds` name a way of drawing the spec's type does not have. */
 export function mount(element: HTMLElement, spec: AntuSpec, options?: MountOptions): AntuHandle
 
+/**
+ * Recommended `ui` for a chat card: no label card, capsule, minimap or zoom buttons, and the wheel
+ * does not pan the diagram (the host page can still scroll). Spread into `mount(…, { ui: { …cardUi } })`.
+ */
+export declare const cardUi: Readonly<{
+  header: false
+  capsule: false
+  minimap: false
+  zoom: false
+  panOnScroll: false
+}>
+
 /** Check a spec the way the diagram checks it before drawing; each error names its field */
 export function validate(spec: unknown): { ok: boolean; errors: string[] }