umlimator 0.16.1 → 0.18.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,8 +42,42 @@ 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`. umlimator/all draws `uml.class` (0.18.0); other types draw as plain cards. */
+export interface Element {
+  id: string; type: string; label?: string; parent?: string; props?: Record<string, unknown>; members?: Element[];
+  [key: string]: unknown;
+}
+/** The class diagram's vocabulary (a view with `diagram: 'uml.class'`, drawn by umlimator/all from 0.18.0;
+ *  docs/conformance/uml-class.md). These describe what `type` and `props` hold; validate() reports what breaks the type's
+ *  rules, and a field written otherwise is kept as it is. */
+export type UmlClassElementType = 'uml.Class' | 'uml.Interface' | 'uml.Enumeration' | 'uml.DataType' | 'uml.PrimitiveType' | 'uml.Package' | 'uml.Comment';
+export type UmlClassMemberType = 'uml.Property' | 'uml.Operation' | 'uml.EnumerationLiteral';
+/** From the client to the supplier: a generalization from the specific to the general, a realization to the interface,
+ *  a comment link from the comment. */
+export type UmlClassLineType = 'uml.Association' | 'uml.Generalization' | 'uml.InterfaceRealization' | 'uml.Dependency' | 'uml.CommentLink';
+export type UmlVisibility = 'public' | 'private' | 'protected' | 'package';
+/** A classifier's or a package's props. Stereotypes are drawn «in guillemets»; any UML element or line may have them. */
+export interface UmlClassifierProps { isAbstract?: boolean; stereotypes?: string[]; [key: string]: unknown }
+/** An attribute's props: its UML text `+ {static} /total: Money [1] = 0` as fields. Types and defaults are text. */
+export interface UmlPropertyProps { visibility?: UmlVisibility; valueType?: string; multiplicity?: string; default?: string; isStatic?: boolean; isDerived?: boolean; stereotypes?: string[]; [key: string]: unknown }
+/** An operation's props: `+ {static} place(at: Date, in qty: Int): Order` as fields. */
+export interface UmlOperationProps {
+  visibility?: UmlVisibility; parameters?: { name: string; valueType?: string; direction?: 'in' | 'out' | 'inout' | 'return' }[];
+  returnType?: string; isStatic?: boolean; isAbstract?: boolean; stereotypes?: string[]; [key: string]: unknown;
+}
+/** One end of an association. A multiplicity is 1, *, n..m or n..*, kept as written; a composite end's is at most 1. */
+export interface UmlAssociationEnd { role?: string; multiplicity?: string; aggregation?: 'none' | 'shared' | 'composite'; navigable?: boolean }
+/** A line's props: an association's two ends, and stereotypes («use» on a dependency). */
+export interface UmlLineProps { ends?: { from?: UmlAssociationEnd; to?: UmlAssociationEnd }; stereotypes?: string[]; [key: string]: unknown }
+/** What a typed view shows of one element, in its `present` by the element's id: compartments not drawn, divider and
+ *  all, and at most `rows` rows in each, then "+k more". */
+export interface UmlPresent { collapsed?: ('attributes' | 'operations' | 'literals')[]; rows?: number }
 /** What a line means, drawn as its colour: calls (the default), feeds (hands work on), triggers (suggests, offers, fires),
  *  state (reads or writes a file, board or config: a thinner line, a muted label, no flow) and guard (a hook steps in).
  *  Colours are --um-w-<kind>. An edge's `style` (emphasis, dashed, security) wins over its kind's colour. */
@@ -111,6 +148,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. */
@@ -347,6 +388,34 @@ export function layout(model: MapModel, viewId: string, options?: { repair?: boo
  *  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; in?: 'model' }
+  /** 0.18.0: into the view's own list for its kind: a line or an item in `edges`, a node in `nodes`, else `fragments` */
+  | { op: 'add'; element: { id: string; [key: string]: unknown }; view: string; index?: number; in: 'view'; owner?: never }
+  | { 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().
+ *  From 0.18.0 `delete` gives what the element held and that stays its nearest owner left, and a diagram type's declared
+ *  references cascade (a reply with its call) or drop (an id out of a list). */
+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', 'rule' or (0.18.0) 'prop', a property a diagram type declares; 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[] }