@zh-xx/antu 0.14.0 → 0.16.0

package/embed/antu-embed.d.ts

@@ -9,9 +9,36 @@ export interface AntuSpec {
   [field: string]: unknown
 }
 
-export type AntuTheme = 'document' | 'modern' | 'legal'
+export type AntuTheme = 'document' | 'modern' | 'legal' | 'dark'
 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
@@ -34,6 +61,7 @@ export type AntuEvent =
       sources: AntuSource[]
     }
   | { type: 'kindchange'; kind: string }
+  | { type: 'themechange'; theme: AntuTheme }
   | { type: 'invalid'; errors: string[] }
 
 export interface AntuPrefsStore {
@@ -51,12 +79,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 +128,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[] }
 
@@ -93,3 +148,12 @@ export function normalize(spec: unknown): { spec: unknown; changes: string[] }
 
 /** The kinds a type can be drawn in, the first being the one it opens in */
 export function kindsOf(type: string): string[]
+
+/**
+ * A small sketch of a kind as one `<svg viewBox="0 0 80 48">` string, for a host that draws its own picker. Its colours are CSS
+ * variables to set where the markup goes: `--antu-text-3` (ink), `--antu-line` (the tint of the boxes) and `--antu-bg` (the ground it sits on: a few sketches paint with it and it falls back to white, so a dark host must set it). `null` for a kind with no sketch.
+ */
+export function kindIcon(kind: string): string | null
+
+/** The name of a kind as the page's picker shows it, in `zh` or `en` (anything else gives English); `null` for an unknown kind */
+export function kindLabel(kind: string, lang?: AntuLang): string | null