umlimator 0.16.0 → 0.17.0

package/lib/umlimator.d.ts

@@ -2,6 +2,9 @@
 
 /** A map model: engine/references/schema.md § Map model, plus the README's umlimator fields. Never mutated. */
 export interface MapModel {
+  /** 1 (or none): a map, read as always. 2: it may hold typed elements and typed views (docs/diagrams/model.md). A newer
+   *  version is an error: validate() says so and migrate() throws (0.17.0). */
+  schemaVersion?: number;
   title?: string;
   root?: string;
   nodes: MapNode[];
@@ -39,6 +42,15 @@ export interface MapNode {
   owner?: string;
   /** The card's own shape, in every notation (0.15.0); without it, the notation draws the card by its kind. */
   shape?: Shape;
+  /** In schema version 2 (0.17.0) a node may also be a typed Element: type, parent, props, members. */
+  [key: string]: unknown;
+}
+/** A typed element in schema version 2's envelope (docs/diagrams/model.md §1): a node, a member, a typed edge, a
+ *  fragment. Nodes, edges, members and fragments share one id space; an id never contains "->". A typed edge is an
+ *  Element with `from` and `to`, which may name a member. A typed view is a MapView with `diagram` (uml.class), and may
+ *  have `subject`, `direction` ('right' | 'down'), `notation`, `present`, `fragments` and `timeline`. None is drawn yet. */
+export interface Element {
+  id: string; type: string; label?: string; parent?: string; props?: Record<string, unknown>; members?: Element[];
   [key: string]: unknown;
 }
 /** What a line means, drawn as its colour: calls (the default), feeds (hands work on), triggers (suggests, offers, fires),
@@ -111,6 +123,10 @@ export interface Events {
   open: { target: Ref; view: string; preventDefault(): void };   // view: the one the card opens, which may not be in the model yet
   viewchange: { view: string; from: string };
   change: Change;                                           // only with `editable`
+  /** A gesture on a typed view (a schema version 2 view whose `diagram` is set and is not 'map'), with `editable`
+   *  (0.17.0): a transaction for the host to apply with apply(model, commands) and hand back with update(). Nothing is
+   *  drawn before. Map views emit `change`, never this. */
+  edit: { view: string; commands: Command[] };
   /** E or Alt + click on a stacked card, or the ⤡ tab of the box it unfolded into (#71): before the card unfolds in place
    *  (expanded: true) or folds back (false). view: the card's inner view, which may not be in the model yet; the card
    *  unfolds once it is: the update() that brings it unfolds the card (here or later), or expand(). preventDefault(): no change. */
@@ -344,9 +360,33 @@ export function history(model: MapModel, limit?: number): History;
 export function layout(model: MapModel, viewId: string, options?: { repair?: boolean; measure?: (text: string, px: number) => number; expand?: string[] }): Geometry & { unfolded?: string[] };
 /** A model's own problem. path says where: "views[2].nodeIds[4]". Errors draw as holes or not at all (missing,
  *  repeated or dangling ids, a box inside itself); warnings draw other than they say (an unknown kind, weight or side,
- *  a view a card opens that the host has not loaded yet). The JSON Schema is umlimator/schema.json. */
+ *  a view a card opens that the host has not loaded yet, a line from a card or box to itself, which is not drawn). The JSON Schema is umlimator/schema.json. */
 export interface Problem { level: 'error' | 'warning'; path: string; message: string }
 export function validate(model: MapModel): Problem[];
+/** The model at the schema version this release reads (0.17.0). Versions 1 and 2 come back unchanged; lines with no id
+ *  keep their positional names. Throws on a newer version (a whole number above 2). */
+export function migrate<M extends MapModel>(model: M): M;
+/** A command on the model (0.17.0). `path` is a dotted path, or a list of keys when a key holds a dot; `value`
+ *  undefined removes the field. `id`, `members`, `parent`, `from` and `to` change by their own commands, not by set. */
+export type Command =
+  | { op: 'set'; id: string; path: string | string[]; value: unknown }
+  | { op: 'set'; view: string; path: string | string[]; value: unknown }
+  | { op: 'add'; element: { id: string; [key: string]: unknown }; owner?: string; index?: number; view?: string }
+  | { op: 'move'; id: string; index: number; owner?: string; view?: never }
+  | { op: 'move'; id: string; view: string; index: number; owner?: never }
+  | { op: 'hide'; id: string; view: string }
+  | { op: 'delete'; id: string }
+  | { op: 'reparent'; id: string; parent: string | null };
+/** The model after a transaction: one command, or a list run in order, on a copy (0.17.0). A command that cannot run
+ *  throws, and none of the transaction is applied. `delete` takes with it the element's members, what it owns, the lines
+ *  to them and every place that names them (references()); one already gone in the same transaction is passed over.
+ *  `hide` takes it out of one view with all the view says of it. Undo is the model before: keep it with history(). */
+export function apply<M extends MapModel>(model: M, commands: Command | Command[]): M;
+/** Where a model names an element, other than the element itself (0.17.0): the keys from the model down to the place
+ *  (['views', 0, 'nodeIds', 2]) and what it is: 'end', 'parent', 'part', 'view', 'pin', 'present', 'override',
+ *  'subject', 'story', 'lens' or 'rule'; later releases may add kinds. */
+export interface Reference { path: (string | number)[]; kind: string }
+export function references(model: MapModel, id: string): Reference[];
 /** One issue of the layout check: its message, as the page's check words it, and the cards, lines and boxes it is about
  *  (exactly those, even where two cards share a label). */
 export interface CheckIssue { message: string; targets: Ref[] }