@myrmidon/gve-snapshot-rendition 0.0.2 → 0.0.4

package/README.md

@@ -16,6 +16,11 @@ Operations also inject metadata, in form of features (essentially name=value pai
 
 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
 
 Conceptual documentation and sample data:
@@ -24,7 +29,7 @@ Conceptual documentation and sample data:
 - [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](data.json): the data loaded in the web component to test it. This is copied from [response.json](docs/sample/response.json), and contains all the data received by the web component for rendering.
+- 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.
 
 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.
@@ -51,6 +56,8 @@ pnpm run start:designer
 
 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
 
 To start working with this code:
@@ -59,12 +66,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 **update sample data**, follow these steps:
 
-1. open the GVE backend solution and run the demo.
+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. paste the request in [docs/sample/request.json](docs/sample/request.json) if you want to make it the default data.
+4. optionally, paste the request in [docs/sample/request.json](docs/sample/request.json) if you want to make it the default data.
 5. run the GVE backend API and use Postman or similar to send the request body with this header:
 
     ```txt
@@ -133,3 +140,23 @@ npm unpublish @myrmidon/gve-snapshot-rendition --force
 ```
 
 >⚠️ Unpublishing can break projects that depend on your package. Only do this for critical security issues or accidental publications.
+
+Package structure:
+
+```txt
+@myrmidon/gve-snapshot-rendition/
+├── dist/
+│   ├── index.js              # ES Module bundle
+│   ├── index.d.ts            # TypeScript declarations
+│   ├── index.cjs.min.js      # CommonJS bundle (minified)
+│   └── ...
+├── README.md
+└── LICENSE
+```
+
+## Deploy Demo at Surge
+
+To deploy demo 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. <http://gve-hint-designer.surge.sh/>).

package/dist/hint-designer/gve-hint-designer.d.ts

@@ -41,6 +41,8 @@ export declare class GveHintDesigner extends HTMLElement {
     private _pauseButton?;
     private _restartButton?;
     private _progressBar?;
+    private _variablesValidationMsg?;
+    private _variablesPanelHeader?;
     private _currentTimeline?;
     private _isPlaying;
     private _progressUpdateInterval?;
@@ -168,6 +170,11 @@ export declare class GveHintDesigner extends HTMLElement {
      * Clear the hint form.
      */
     private clearHintForm;
+    /**
+     * Validate SVG code for well-formedness and structure.
+     * Returns an error message if validation fails, or null if valid.
+     */
+    private validateSvgCode;
     /**
      * Add a new hint.
      */
@@ -192,6 +199,19 @@ export declare class GveHintDesigner extends HTMLElement {
      * Resolve variables in SVG code.
      */
     private resolveVariables;
+    /**
+     * Extract variable names from SVG code (variables in {{...}} placeholders).
+     */
+    private extractVariablesFromSvg;
+    /**
+     * Validate SVG variables and update validation message.
+     * Shows a warning if any variables used in SVG are not defined in hint variables.
+     */
+    private validateSvgVariables;
+    /**
+     * Update warning icon in variables panel header.
+     */
+    private updateVariablesHeaderWarning;
     /**
      * Play animation.
      */
@@ -280,6 +300,17 @@ export declare class GveHintDesigner extends HTMLElement {
      * Delete all variables.
      */
     private deleteAllVariables;
+    /**
+     * Extract all variable names from all hints in data.
+     * Returns a sorted array of unique variable names.
+     */
+    private extractAllVariablesFromHints;
+    /**
+     * Populate hint variables from all hints.
+     * Extracts all variables from all hints' SVG code and merges them into hintVariables.
+     * Only adds variables that don't already exist.
+     */
+    private populateVariablesFromHints;
     /**
      * Refresh the variables table.
      */