@myrmidon/gve-core 1.0.0 → 2.0.0

package/README.md

@@ -1,8 +1,10 @@
 # Gve Core
 
+- 🚀 `npm i @myrmidon/gve-core`.
+
 This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 17.0.0.
 
-This is the core UI library for GVE.
+This is the core UI library for [GVE](https://vedph.github.io/gve-doc).
 
 ```plantuml
 @startuml
@@ -19,6 +21,7 @@ This is the core UI library for GVE.
 [feature set view]
 [ln heights editor]
 [batch ops editor]
+[snapshot text editor]
 [op source editor]
 [snapshot editor]
 [steps map]
@@ -38,6 +41,7 @@ This is the core UI library for GVE.
 [chain result view] --> [base text view]
 [chain result view] --> [feature set view]
 [chain result view] --> [steps map]
+[snapshot editor] --> [snapshot text editor]
 [snapshot editor] --> [batch ops editor]
 [snapshot editor] --> [animation timeline set]
 [snapshot editor] --> [base text editor]
@@ -49,3 +53,38 @@ This is the core UI library for GVE.
 [snapshot editor] --> [api service]
 @enduml
 ```
+
+## Snapshot Editor
+
+The snapshot editor is the top-level component in the library and orchestrates the behavior of all the components included in it. Its API is very simple, as it just deals with a full snapshot:
+
+- ▶️ `snapshot` (`Snapshot`): the snapshot to edit.
+- ▶️ `batchOps` (`string`): the batch operations text to set for the editor.
+- ▶️ `noSave` (`boolean`): true to disable saving.
+- 🔥 `snapshotChange` (`Snapshot`): emitted when the user saves the edited snapshot.
+- 🔥 `snapshotCancel` (`void`): emitted when the user cancels the snapshot editing.
+
+The only data directly handled by the component are:
+
+- size and style;
+- base text and related data;
+- background image.
+
+Operations and timelines are handled by other children components. The snapshot model is built dynamically when required (via `getSnapshot`), and it is displayed by a snapshot view.
+
+View data, wrapping the snapshot and some options (debug mode, delayed rendering, rules, grid, pan and zoom, transparent SVG elements IDs), are built via `setViewData`, which in turns gets the snapshot from `getSnapshot` unless it receives one.
+
+The key logic for displaying the snapshot is implemented in `runTo`, which runs the operations up to the specified index. This gets called when:
+
+- a preview is requested by the operation editor.
+- the currently edited operation is saved.
+- the user picks a step in the chain result view.
+- `runToLast` is called, which happens when:
+  - setting the snapshot from the parent.
+  - the number of operations changes, either by parsing a batch of operations or by deleting an operation.
+
+This function gets the snapshot (via `getSnapshot`), patches it so that it corresponds to the set of operations up to the specified index, and runs all these operations. Once done, it extracts the transparent elements IDs from the last operation, updates view data (via `setViewData` passing the built snapshot to it), and returns the execution result.
+
+After running operations, the result is stored in `result` (of type `CharChainResult`), which feeds the `ChainResultViewComponent` in charge of showing the details of each generated text version. In turn, this may fire step-pick events, which are handled by getting the snapshot at that step, updating the transparent element IDs, and updating view data (via `setViewData` passing the built snapshot to it); also, an animation is played if required, after running operations up to the one corresponding to the picked step.
+
+When an operation is saved from the child operation editor (`onOperationChange`), all the operations are run up to the saved one.