@myrmidon/gve-snapshot-rendition 0.0.8 → 1.0.0

package/README.md

@@ -1,47 +1,33 @@
 # GVE Snapshot Rendition Component
 
-This workspace contains a custom web component for the rendition of a complex Academic model representing the transformations of an autograph text. This peculiar document was written by the hand of the author, and contains a lot of often chaotic annotations on top of a base text. These annotations represent changes to the first draft of the text mostly by the hand of the author himself, thus providing a unique insight in the writer's creative process.
-
-For the purpose of the visualization of the digital model designed to represent this text with all its variations together with its diplomatic data, we consider 3 entities to display:
-
-- the base text, which is the starting point and the bearer of all the annotations.
-- the added text. This is text added by operations like add or replace.
-- all other signs: these are the visual counterparts of editing operations on the text, which hint at them in a graphical way. For instance, a line on top of a text meaning it should be deleted. There is no limit to the variety of these signs: they might be lines, shapes, callouts, boxes, etc.
-
-Text (whether it is base or added text) is represented character by character; each character is named _node_, because in backend, where all the transformations happen, there is a graph-like structure which recombines the same characters to form different versions of the text, just like nodes are connected by edges in a graph.
-
-The transformations are essentially represented by a set of editing operations (like delete, replace, add, move, swap) which are executed one after another starting with a base text. The base text is known as version 0 (tag=`v0`). All the operations are executed in their order and each outputs a new version of the text, progressively numbered (`v1`, `v2`...).
-
-Operations also inject metadata, in form of features (essentially name=value pairs), either into versions as a whole (for global features), or into specific characters of the output text (node features). A specific set of features (rendition features, all starting with prefix `r_`) is used to represent the visual counterpart of each operation; for instance, a delete might be visually represented by a diagonal line on top of the portion of the text being deleted. In this case, multiple features of the operation (which injects them into nodes) are used to set the drawing connected to it, in this case a line, and specify additional parameters like its color. Such drawings are often recurring multiple times; so, they belong to a catalog of so-called "hints", because they hint at the operation with their appearance (e.g. a line stroke on a text hints at its deletion). These hints have entrance animations, handled by GSAP (like any other animations in this project). These too typically belong to a catalog of animations.
-
-Both hints and animations are part of the settings for the component. The component is found under [src/core/gve-snapshot-rendition.ts](src/core/gve-snapshot-rendition.ts), and most of its logic is properly encapsulated in its own set of classes, following a systematic separation of concerns to ensure flexibility, extendibility, and easy maintenance.
-
-## Usage Guide
-
-- [Angular integration](docs/dev/angular-integration.md)
-- [vanilla integration](docs/dev/vanilla-integration.md)
-
-## Documentation
+## 📖 Documentation
 
 Conceptual documentation and sample data:
 
 - [snapshot backend model](docs/snapshot.md): overview of the backend data used by the component.
-- [rendition description](docs/rendition.md): details about the architecture and logic of this component.
-- [sample request to backend snapshot processor](docs/sample/request.json): the request used to generate our sample data via backend. This is used only when we want to change our sample data.
-- [sample response from backend snapshot processor](docs/sample/response.json): the response received from backend corresponding to our request. This is used only when we want to change our sample data.
-- data used in the demo are found in the `data` folder. Each sample has 3 files for base text, data received from backend service, and settings. For the default sample, data is copied from [response.json](docs/sample/response.json). These represent all the data received by the web component for rendering.
-- [features adapter services](docs/adapter.md): complementary services independent from the GVE snapshot rendition component, possibly used to adapt data before passing it to the component.
+- [rendition description](docs/rendition.md): documentation about the architecture and logic of the snapshot renderer custom web control.
+- data used in the demo are found in the `data` folder. Each sample has 4 files:
+  - (no suffix): base text and operations DSL. This is the snapshot data.
+  - `*.base.txt`: base text.
+  - `*.request.json`: request to API. You can generate this from the backend demo app.
+  - `*.data.json`: response from API. These are the data bound to the renderer control.
+  - `*.settings.json`: settings for the renderer control.
+- [hint designer](docs/hint-designer.md): documentation about hints designer custom web control.
+- [features adapter services](docs/adapter.md): documentation about complementary services independent from the GVE snapshot rendition component, optionally used to adapt data before passing it to the component.
+
+Developer's usage guide:
 
-The test page used in this project is `index.html` and its code is `consumer.js`. The data model is `CharChainResult` and it is found with all the imported models in `models.ts`. These are the models imported from another package and should not be touched.
+- [Angular integration](docs/dev/angular-integration.md)
+- [vanilla integration](docs/dev/vanilla-integration.md)
 
-### Feature Adapter
+### 🟢 Feature Adapter
 
 The **Feature Adapter** is a utility system for transforming features in snapshot data. It enables you to adapt high-level features into low-level rendition features that the component can use:
 
-- [Feature Adapter Overview](docs/adapter.md): Architecture and usage guide.
-- [Detailed Documentation](src/adapter/README.md): Complete API reference and examples.
+- [Feature Adapter Overview](docs/adapter.md): architecture and usage guide.
+- [Detailed Documentation](src/adapter/README.md): complete API reference and examples.
 
-### Hint Designer
+### 🟢 Hint Designer
 
 The **Hint Designer** is a companion web component which can be used to help users edit and test their hints SVG and JS animation code. The main web component used for display has no relation with it. Rather, the hint designer component reuses some logic from the main component, while still being aside.
 
@@ -58,7 +44,7 @@ This will build the component and open the hint designer in your browser.
 
 >If you want to pick a different sample, add it to the URL with a `sample` argument, e.g. <localhost:3000?sample=h5-48>.
 
-## Quick Start
+## 🚀 Quick Start
 
 To start working with this code:
 
@@ -66,12 +52,12 @@ To start working with this code:
 2. download dependencies with `pnpm i`.
 3. run with `pnpm start`.
 
-💡 Note: if you need to **update sample data**, follow these steps:
+💡 Note: if you need to **create sample data**, follow these steps:
 
-1. open the [GVE backend solution](https://github.com/vedph/gve-core) and run the demo.
-2. set text and operations as you want (to start with the current data, pick the "rendition features" preset).
-3. click the "build request" button.
-4. optionally, paste the request in [docs/sample/request.json](docs/sample/request.json) if you want to make it the default data.
+1. create a .txt file with base text and operations DSL.
+2. open the [GVE backend solution](https://github.com/vedph/gve-core) and run the demo.
+3. set text and operations copying them from the .txt file.
+4. click the "build request" button.
 5. run the GVE backend API and use Postman or similar to send the request body with this header:
 
     ```txt
@@ -82,24 +68,15 @@ To start working with this code:
     ...paste your JSON request body here...
     ```
 
-6. copy the response and paste it into [data.json](data.json) and also into [docs/sample/response.json](docs/sample/response.json) if you want to make it the default data.
+6. copy the response and paste it into a new set of data files.
+7. run with the name of the data file: <localhost:3000?NAME>.
 
-## Requirements
+## 📦 Deployment
 
-This component requires the following packages:
-
-- [GSAP](https://gsap.com) for animations (`pnpm i gsap @types/gsap`).
-- [svg-pan-zoom](https://github.com/bumbu/svg-pan-zoom) for zooming and panning (`pnpm i svg-pan-zoom @types/svg-pan-zoom`).
-- [fast-diff](https://github.com/jhchen/fast-diff) for text diffing (`pnpm i fast-diff @types/fast-diff`).
-- [feather-icons](https://github.com/feathericons/feather) for icons. See also the [icons list](https://feathericons.com) (`pnpm i feather-icons`).
-- [highlight.js](https://highlightjs.org/) for the hint designer (syntax highlight for SVG and JS code; `pnpm i highlight.js`).
-
-## Deployment
-
-🚀 You must be logged into NPM with your account (verify with `npm whoami`, login with `npm login` if required).
+You must be logged into NPM with your account (verify with `npm whoami`, login with `npm login` if required).
 
 1. ensure that tests pass (`pnpm test`) and be sure to build (`pnpm build`).
-2. publish via `pnpm run publish:public` or directly via `npm publish --access=public`.
+2. publish via `pnpm run publish:public` or directly via `pnpm publish --access=public`.
 
 Check that your package is available:
 
@@ -148,9 +125,7 @@ Package structure:
 └── LICENSE
 ```
 
-## Deploy Demo at Surge
-
-To deploy demo in surge:
+To **deploy a static HTML demo page in surge**:
 
 1. run the script for the demo you want to create (`deploy-demo.ps1` or `deploy-hint-demo.ps1`).
 2. in the created folder, run `surge`, enter your credentials, confirm the local source directory, and specify a URL to use (e.g. <gve-rendition.surge.sh> or <gve-hint-designer.surge.sh/>).