@peter.prib/renderengine 0.2.6 → 0.2.7

package/README.md

@@ -39,6 +39,10 @@ other browsers download the file instead.
 
 - **Open and save Archi files** (`.archimate`, and archives that include pictures). Save writes back to the file you
   opened; Save As picks a new one. Unsaved changes are marked (•), and the page asks before you leave or close them.
+- **Kept in the browser, backed up to the cloud.** Every model is kept in the browser as you edit it, and those open
+  reopen next time, with no file saved. File ▸ This browser backs them all up to a folder you choose once: pick one
+  that OneDrive, Google Drive or Dropbox syncs and the backups reach the cloud (each named with the date and time,
+  plus one under its plain name); browsers that cannot write to a folder download them instead.
 - **Import a spreadsheet** into the open model: choose the name, type, id, documentation, property and "related
   to" columns; existing elements are updated, not duplicated (Archi's elements.csv imports as it is).
 - **draw.io export**: every view a page, in draw.io's ArchiMate shapes, with the elements' properties.

package/REFERENCE.md

@@ -723,7 +723,7 @@ types — see `ARCHITECTURE.md`):
   `'cylinder'`, ...) and `labelPosition: 'below'` keeps the shape's size. In Chen a relationship's diamond holds
   its name and sits midway between its two entities when both have `x`/`y`, or when something is drawn there (an entity, a
   note, another diamond) the nearest clear spot across the line (`RelationshipAsNodeStrategy.spotFor`,
-  `DataModelDiagram.boxOf`); its lines have no arrowheads.
+  `DataModelDiagram.boxOf`); its lines have no arrowheads; when no spot near the line is clear, the least covered one.
   Each level and notation has a `label` for menus (`'Conceptual'`, `"Crow's Foot"`).
   **Levels of their own, and how they map.** A `DataModel` (`src/charting/datamodel/`, exported from the package
   root) keeps each level as its own schema, a `LevelSchema` (`model.level('conceptual' | 'logical' | 'physical')`):
@@ -782,8 +782,137 @@ types — see `ARCHITECTURE.md`):
   `DataModelContext.fields(model, context?)` and `DataModelContext.specFrom(values, model, context?)` (meanings, dates,
   and rules a line each, `the rule | the concepts, by name`).
 
+  **BIAN service domains.** `BianNotation` (`src/bian.js`, exported from the package root) holds BIAN's vocabulary:
+  the nineteen functional patterns, each with its generic artifact, description, creating action term and behaviour
+  qualifier type (`BianNotation.functionalPattern('Fulfill')`, a `BianFunctionalPattern`), the seventeen action terms
+  in their four groups, and the v14.0 behaviour qualifier types. Each pattern's artifact, creating term and qualifier
+  type are as BIAN's v14 model has them (its service landscape portal: the artifact a pattern accesses, the qualifier
+  type the artifact aggregates, the creating term the pattern aggregates), the names control records have as its
+  release 14 semantic APIs do (Fulfill's is a *Facility*, the guide's *Arrangement* kept in `formerArtifacts`); none
+  is `inferred`. BIAN spells *Analyze* (the guide's *Analyse* still finds it); `BianNotation.findPattern(text)` finds
+  one by its name in any case, and `BianNotation.patternOfControlRecord(name)` by the artifact a control record's name
+  ends with (`'CurrentAccountFacility'`: Fulfill). A `ServiceDomain` is a kind of perspective (`kind: 'service-domain'`; a perspective spec's
+  `kind` picks its class, `DataModelPerspective.from`, `register`): its business area and domain, the `asset` it manages,
+  its functional `pattern`, its `controlRecord` (a logical entity; `controlRecordName` is the asset and the pattern's
+  artifact, *Current Account Facility*) and `qualifiers` (`[{ name, type?, entity }]`). `serviceOperations()` gives
+  its semantic API as BIAN names it (*initiate Current Account Facility | Interest*, `BianNotation.serviceOperations`).
+  Seen through at the logical level it shows its control record and qualifiers whatever they realise, coloured and
+  saying what they are on hover, with a note of its service operations; a perspective kind adds to a view through
+  `alsoShows(level)`, `decorate(entity, level)` and `notes(level)`. Model ▸ **New service domain…** makes one
+  (`ServiceDomain.fields`, `specFrom`: the pattern from BIAN's, qualifiers a line each, `name | type | logical entity`).
+  The data-model example's second base, *Retail banking (BIAN)*, has six. See `BIAN_ALIGNMENT.md` for the design.
+
+  **Ownership and the model check.** As in BIAN, each business object (a logical entity) is owned by one service
+  domain: a perspective owns what `ownedEntities()` gives (none for a plain one; a service domain owns its control
+  record, its qualifiers' entities and those it names in `owns`, its dialog's *Also owns*), `model.ownersOf(id)`
+  says who owns one, and the logical level shows it on hover (*owned by*). `model.checker()` is a `DataModelChecker`
+  (a `ModelChecker`, the base `ViewSetChecker` extends too): a business object owned by more than one service domain
+  (`owned-twice`), owned by none once any are owned (`unowned`), a service domain without a control record or with
+  one, or a qualifier, that is no logical entity, or with a pattern BIAN lacks, and a mapping joining an entity that
+  is not there. Model ▸ **Check model…** lists the findings in the `ModelCheckDialog` the diagram editors' check uses;
+  choosing one shows it (the entity's level, the service domain seen through, the mapping view).
+  The ontology base keeps BIAN's **Agreement** (the contract) apart from its **Arrangement** (the terms a product is
+  provided on), and has **Product Feature** and **Condition**; its concepts say which BIAN business object they are
+  (`details.bian`, on hover).
+
+  **The service landscape.** Level ▸ **Service landscape** (offered once a model has a service domain;
+  `DataModel.LANDSCAPE`) draws the service domains as BIAN draws its landscape: a column per business area, a frame
+  per business domain in it, a box per service domain coloured by its functional pattern (grey for one BIAN lacks),
+  its pattern, control record and asset on hover. Those with no area or domain go under *No business area* /
+  *No business domain*. It is laid out from that structure each time (`ServiceLandscape.view(serviceDomains)`), so
+  a box dragged there is not kept; double-click one to see the model through it at the logical level. Mapping and
+  the landscape are `DataModel.OTHER_VIEWS`, the views that are no level, which the Level choice and `view()` read.
+
+  **Reading BIAN's landscape.** Model ▸ **Read service domains from a BIAN landscape…** reads an ArchiMate model
+  (an Archi file or the Exchange Format; `BianLandscapeReader.parse`). In BIAN's v14 model a business area is a
+  Grouping marked *BusinessArea*, composed of business domains (Capabilities marked *BusinessDomain*), composed of
+  service domains (Capabilities marked *ServiceDomain*), each realized by its functional pattern; other Groupings
+  aggregate service domains as overlays (a value chain, a release wave). Where the file keeps the stereotypes (Archi
+  specializations, or a *Stereotype* property) they say which is which: a service domain's business domain is the
+  container marked so and its area the one holding that; a Capability in a business domain is a service domain though
+  unmarked (BIAN leaves a few so); of copies of one, the placed one is it. Without stereotypes it goes by structure: a
+  Capability nothing sits in is a service domain, its nearest container its business domain, the outermost its area.
+  What holds what: composition before aggregation, then a box drawn inside another in a view. A service domain's
+  pattern is the one realizing it (an element named as a BIAN pattern), else its *Functional Pattern* property; its
+  asset its *Asset Type* property. The types, relationships, stereotypes and property keys are options of
+  `new BianLandscapeReader({...})`. Run over BIAN's v14 model it places all 344 service domains the model places in
+  their area and domain, and gives 349 of 350 their pattern; by structure alone it would take 820 Capabilities for
+  service domains.
+  `model.serviceDomainsCommand(specs, source)` brings them in as one undo step: a new one is added; one already
+  there (by id, else by name) keeps its control record, qualifiers and the rest, taking its area and domain from
+  the landscape, and its asset and pattern where it has none. `examples/bian-landscape-sample.xml` is a small
+  excerpt in that shape to try it with (not BIAN's landscape, which is BIAN's to publish).
+
+  ```javascript
+  const specs = new BianLandscapeReader().read(BianLandscapeReader.parse(xml));
+  model.history.execute(model.serviceDomainsCommand(specs, '"bian.xml"'));
+  model.view({ level: DataModel.LANDSCAPE });   // { entities, folders, elementFolders, ... }
+  ```
+
+  **Data types.** A model's `dataTypes` are the types its attributes have, each defined once: a `DataType` (a plain
+  named type, `basedOn` another), an `EnumerationType` (`values: [{ name, description? }]`) or a `StructuredType`
+  (`fields: [{ name, type?, description?, iso20022? }]`), its `kind` in a spec picking the class (`DataType.from`,
+  `register`), as BIAN publishes its data types and DAMA-DMBOK2 calls domains. An attribute names one by its `type`
+  (the type's id, else its name in any case: `model.typeOf(attribute)`); a plain type (`VARCHAR(20)`) names none.
+  On hover an entity lists its attributes' data types; `model.usesOf(id)` says where one is used. Level ▸ **Data types**
+  draws each as a box with a row per value or field, joined to the types a structure's fields are. Model ▸ **Data
+  types** ▸ makes one of each kind, edits or deletes each (a dialog per kind: values a line each, `value | meaning`;
+  fields `name | type`). They are saved, compared and merged as the rest of the model is (`DataTypesCompared`), and
+  the model check reports an enumeration with no values or a value twice, two types of one name, and a type nothing uses.
+
+  **ISO 20022.** An entity, an attribute or a data type may say which ISO 20022 type it is (`iso20022: 'CurrencyCode'`;
+  `DataType.iso20022Url(name)` its page in the ISO 20022 standards repository). On hover an entity lists its own and
+  its attributes' (an attribute's own, else its data type's).
+
+  **Reading a BIAN semantic API.** BIAN publishes a semantic API per service domain (OpenAPI files, YAML; the plain ones
+  and those extended with ISO 20022, at github.com/bian-official/public, Apache-2.0). Model ▸ **Read a BIAN service
+  domain (semantic API)…** reads one (`.yaml`, `.yml` or `.json`; `BianSemanticApiReader`): its control record and
+  behaviour qualifiers (the operations' `CR - …` and `BQ - …` tags) become logical entities with the attributes their
+  schemas have, the qualifiers joined to the control record; the schemas those attributes are become data types (an
+  `enum` an enumeration, each value's meaning from BIAN's description; an object a structure; else a plain type), as
+  deep as `depth` (1); a class the model already has as a logical entity stays a reference to it; the ISO 20022 version
+  gives each attribute its ISO 20022 type. The service domain is named by the API's title, its pattern and asset by its
+  control record's name. `model.bringCommand({ entities, relationships, dataTypes, serviceDomains }, label)` brings
+  it in as one undo step: what is new is added; an entity or data type there by name stays and is used; only the data
+  types the new entities need come (and the types those need); a service domain there keeps what it has (as for a
+  landscape) and gains the behaviour qualifiers it lacks; one that would come out the same is left alone. Every one
+  of release 14's 258 APIs reads, in both versions.
+
+  ```javascript
+  const read = new BianSemanticApiReader().read(BianSemanticApiReader.parse(yamlText));
+  model.history.execute(model.bringCommand(read, 'Read Current Account'));
+  model.typeOf(model.level('logical').entity('current-account-facility').attributes[1]);   // EnumerationType
+  ```
+
+  `YamlReader.parse(text)` (`src/yaml/YamlReader.js`) is the dependency-free reader it uses: block mappings and
+  sequences, quoted and plain scalars (typed as YAML 1.2's core schema has them), block scalars with chomping, flow
+  collections, comments; it refuses anchors, aliases and tags with the line they are on.
+
+  ```js
+  const sd = model.addPerspective({ kind: 'service-domain', name: 'Current Account', asset: 'Current Account', pattern: 'Fulfill',
+      controlRecord: 'current-account', qualifiers: [{ name: 'Interest', entity: 'interest' }] });
+  sd.controlRecordName;                  // 'Current Account Facility'
+  sd.serviceOperations()[3].name;        // 'initiate Current Account Facility'
+  ```
+
+  **Compared and merged.** `model.compareWith(other)` is a `ModelComparison`, as for ArchiMate models, kind by kind
+  (`model.comparedKinds()`): each level's entities (`LevelEntitiesCompared`; where a box is drawn does not count) and
+  relationships (`LevelRelationshipsCompared`; one with no id known by its ends and name, and needing them), the
+  mappings (`MappingsCompared`, a pair each, needing its two entities), contexts and perspectives (a perspective
+  needing the context it is read in). `comparison.mergeCommand(keys)` brings the chosen differences and what they
+  need, as one step on `model.history`.
+
+  **Saved, kept and backed up.** A data model is a file of its own, `.datamodel.json` (`DataModelFileFormat`: its
+  `name`, levels, mappings, layouts, perspectives and contexts, `model.toJSON()`; the older one-entity form reads
+  too). It knows when it changed since it was saved (`model.edited()`, `markSaved()`, `isDirty()`, `onEdit(fn)`):
+  a perspective or context made, changed or removed, a box or note moved.
+
   **In the workbench:** `DataModelPart` (type `data-model`, `RenderEngineWorkspace.DataModelPart`) shows one
-  model: Model ▸ New / Edit / Delete perspective and context (those dialogs), Perspective and Context selects (when
+  model: File ▸ Open…, Save, Save As… (Ctrl+O, Ctrl+S; `part.file`, the `ModelFile` editors use, • while changed,
+  asking before the page is left with changes unsaved), and hosted by a `ModelsPart` (`editorType: 'data-model'`)
+  New ▸ (New model, From base: …), Duplicate model, Close model and This browser ▸ (with `keep`: kept in this browser
+  as it changes, reopened next time, backed up to a folder chosen once, as the modeller's models are); Edit ▸ Undo
+  and Redo; Tools ▸ Compare with and Merge from (the other open models and the bases; a merge is one undo step); Model ▸ New / Edit / Delete perspective and context (those dialogs), Perspective and Context selects (when
   it has some; a perspective brings its context, and the context's scope shows beside them), Level (Conceptual,
   Logical, Physical, and Mapping), Notation, and Export ▸ PNG / SVG. A box or note dragged stays on the level it
   was dragged on (the mapping view's in its own layout). `examples/data-model.html` (`npm run datamodel`) uses every
@@ -1359,6 +1488,34 @@ mine.history.execute(comparison.mergeCommand(['view:id-extra']));   // the view,
 mine.history.undo();
 ```
 
+**A model tab's menu.** Right-click a model's tab for what can be done with that model (`models.tabMenuItems(part)`):
+Save and Save As… (an editor that saves files), Duplicate model, Compare with ▸ and Merge from ▸, This browser ▸
+(with `keep`), Close model and Close other models. The work area hands a tab's right-click to its `tabMenu` option
+(`(partId, event) => shown`), through `TabsNode`'s `ctx.onTabMenu`; with none, the browser's own menu shows.
+
+**Bases, and copies.** A `ModelsPart` spec's `bases` are reference models kept as given: each made from its own copy
+of its spec when the workbench is first drawn (`models.bases()`, parts never opened, edited or kept, so an open model
+sharing the spec's data cannot reach them). File ▸ New ▸ **From base: …** (`models.newFromBase(i)`,
+`models.baseItems()`) opens a model as a copy of one; Tools ▸ **Compare with** and **Merge from** offer them, after
+the other open models (`models.toolItems(part)`); File ▸ **Duplicate model** (`models.duplicate(part)`) opens a copy
+of the model in front, written and read back through its own file format. A copy, from a base or duplicated, is named
+"… (copy)" (`ModelsPart.copyName`, the suffix once).
+
+**Kept in this browser, and backed up.** With `keep: true` in its spec, a `ModelsPart` keeps every model it holds
+in this browser, so work outlives the page without saving a file: a moment after each edit (`ModelsPart.KEEP_DELAY`)
+and at once when imported, each in its editor's own file format (`part.keepEntry()`: the file's format, else the
+part's save format), in a `ModelLibrary` over an IndexedDB store (`KeyValueStore`: `IndexedDbStore`, or a
+`MemoryStore` where the browser has none). Those open when the page closed open again next time
+(`models.ready` resolves once they have), in place of the starting model if it was left untouched; a tab closed
+is kept but not reopened. File ▸ **This browser** has **Open a kept model…**, **Stop keeping this model**, **Back
+up kept models now** and **Backup folder…**. Backups (`BackupFolder`, after au-accounts-app's) go to a folder chosen
+once and remembered (the File System Access API, in Chrome and Edge, from `file://` too): choose one that OneDrive,
+Google Drive or Dropbox syncs and they reach the cloud, with no sign-in in the page. Each is written stamped with
+the date and time (`BackupFolder.stamped('shop.archimate')` gives `shop-20261015-093012.archimate`), so they gather
+as a history, and under its plain name too (`keepUnstamped`); where a folder cannot be written (Firefox, Safari,
+permission refused) they download instead. `backups.log()` records each (newest first, `LOG_MAX`), and
+`backups.daysSinceLast()` how long ago the last was. `examples/archimate.html` keeps its models.
+
 ```js
 ws.addParts([{ id: 'models', type: 'models', editorType: 'archimate-canvas', newModel: { analysis: true },
     models: [{ id: 'modeller', title: 'Sample model', elements: [...], views: [...] }] }]);
@@ -1945,6 +2102,11 @@ parts.children.length;   // 3: front, top and side faces
 context, and the template draws its parts as SVG (`glyphToSvg`; `glyphElement(part)` gives the tag and
 attributes, by the SVG renderer's rules) and attaches lines to the glyph's `outline(ctx)`. Every glyph
 has an outline: its box by default, the real shape for round, skewed and pointed ones.
+`graphDiagram` (and the data-model diagram drawn by it) does the same: a line ends where it meets the node's
+glyph outline (`NodeGeometry.outline(shape, size)`, crossed by `EdgeGeometry.rayPolygonT`), so it reaches a wide
+ellipse or product box rather than stopping short on a circle as wide as the node; a shape no glyph draws keeps
+that circle. Centred initials stand in for a name drawn below the shape: a node whose name is inside it gets none
+(`GraphDiagram.showsInitials(node)`).
 
 **ArchiMate in the template editor.** `ArchimateElementTemplate(instance, model, {nodeOptions})` and
 `ArchimateEdge(instance, view)` put an `ArchimateView` into a `DiagramEditor`. Neither keeps a copy:
@@ -2196,6 +2358,22 @@ its `fileFormats()`, none by default, then the image export), and its editor dis
 import goes through `replaceModel(model)`, which a subclass follows in `modelReplaced(model)`.
 `DiagramEditorPart`, `ArchimateEditorPart` and `ArchimateCanvasPart` extend it.
 
+**Tabs, as a browser has them.** A part's tabs are the views open (`part.openViews`, an `OpenViewList` over its
+model), not every view: a model opened or imported starts with its first view only, so an Archi file of many
+views does not fill the strip. Going to a view (choosing it in the model tree, a search match, a new view)
+opens its tab; a tab's **×** closes the tab and leaves the view in the model (one tab always stays, and the
+tab in front closed brings its neighbour); **+** after the tabs makes something new (`newItems()`: a view, or
+a menu of a view, a canvas, from a template). `part.viewTabs({ orientation })` builds the strip
+(`ViewTabStrip` with `canClose` and `onAdd`). Drawing every view for the HTML report opens none
+(`openViews.while(fn)`). The spec's `openViews` (view ids) chooses which open at the start.
+
+**Panels that fold and resize.** The side panels (the model tree, the palette and analysis) have a splitter
+on their inner edge: drag it to resize the panel, drag it nearly shut or double-click it to fold the panel to
+a stub that names it, and click the stub to open it at its width again. `part.layout` (a `PanelLayout`:
+`resize(name, width)`, `toggle(name)`, `widthOf(name)`) keeps the widths and folds across renders; the spec's
+`layout` (`{ side: { width, collapsed }, aside: {...} }`) sets them at the start. `EditorShell` draws them
+when given a `layout` and stub `labels`.
+
 `DiagramEditorPart` (workspace bundle) puts this together: `MenuBar` (File creates and deletes
 diagrams; Settings has the grid and line-style levels), the palette, a `ViewTabStrip` (right-click
 a tab for its **Properties…**: name, documentation and the diagram's line style; **Duplicate**;