signalk-symbol-manager 0.5.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Joel Kozikowski
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,304 @@
+# Signal K Symbol Manager
+
+Create and manage a library of symbols for your charts. Waypoints, note markers, etc.
+
+Symbol Manager is a plugin for your Signal K server that acts as both a "symbol resource provider" as well as a web app for building and managing a library of
+custom SVG symbols — note markers, waypoints, map pins, flags, status icons —
+that symbol-aware Signal K apps (like Freeboard-SK) can display on your charts
+and dashboards.
+
+You can:
+
+- start from a built-in template (POI / Flag / Waypoint / Blank) or upload an
+  existing SVG file,
+- edit the symbol in a lightweight visual editor — shapes, text, colors,
+  outlines, opacity, layering,
+- set the anchor point and display scale that map apps use to place the
+  symbol on a chart,
+- preview the symbol against a sample chart background at the size it will
+  actually appear,
+- **replace** the built-in icons in consumer apps by giving your symbol the
+  same id as the one they ship with.
+
+## Requirements
+
+- Signal K Server 2.x with the resource provider API.
+- Node.js 22.5 or newer (the plugin uses Node's built-in SQLite).
+- A symbol-aware consumer app. **Freeboard-SK** is the reference consumer app.
+
+
+## Installing
+
+Install through the Signal K Server **Appstore** (search for *Symbol
+Manager*) and restart the server, then enable the plugin in the **Plugin
+Config** screen. There is nothing to configure — the plugin is ready to use
+as soon as it's enabled.
+
+## Opening the Symbol Manager
+
+After the plugin is enabled, open the Signal K admin UI and choose
+**Webapps → Symbol Manager**. The library is empty the first time you open
+it.
+
+The library lives in your Signal K data directory and is *not* tracked by
+git — your symbols are yours.
+
+## The library list
+
+The main screen lists every symbol in your library, with its thumbnail,
+name, description, roles, tags, and per-row actions:
+
+| Action      | What it does                                                                |
+|-------------|-----------------------------------------------------------------------------|
+| **Edit**    | Open the visual editor on this symbol.                                      |
+| **Duplicate** | Copy the symbol. A dialog asks for the new **id** and **namespace** — keep the id and change the namespace to make an alternate of the original under `namespace:id`. |
+| **Delete**  | Remove the symbol from the library (and its SVG file from disk).            |
+
+Across the top:
+
+- **Refresh** — re-fetch the list from the server.
+- **Upload SVG** — see *Direct upload* below.
+- **New** — start a new symbol from a template.
+
+## Creating a symbol from a template
+
+**New** opens the template picker:
+
+| Template     | What it gives you                                                        |
+|--------------|--------------------------------------------------------------------------|
+| **POI**      | A "Point of Interest" symbol.  Apps like Freeboard-SK use this as the note-marker shape (the colored "tag" with a hole). The fill color of the body is editable. Has a defined "body area" — any shape you import drops into it automatically. |
+| **Flag**     | A flag-on-a-staff marker. The anchor sits at the base of the staff.       |
+| **Waypoint** | A classic map-pin teardrop with a center dot.                            |
+| **Blank**    | An empty 48×48 canvas — build a symbol from scratch.                     |
+
+Pick one and the editor opens with the template's default shape, default
+roles, and (for map-marker templates) a sensible default scale and anchor.
+
+## The editor
+
+The editor has three areas:
+
+```
+┌──────────────────────────┬─────────────────────┐
+│         toolbar          │      Preview        │
+├──────────────────────────┤   (chart sample)    │
+│                          │                     │
+│         canvas           │ ───────────────     │
+│   (drawing area, with    │      Properties     │
+│    chequerboard back-    │  (symbol-wide or    │
+│    ground showing the    │   per-shape, de-    │
+│    SVG bounds)           │   pending on what   │
+│                          │   is selected)      │
+└──────────────────────────┴─────────────────────┘
+```
+
+### Toolbar
+
+| Button | What it does                                                       |
+|--------|--------------------------------------------------------------------|
+| ▭      | Adds a rectangle                                                   |
+| ◯      | Adds a circle                                                      |
+| ╱      | Adds a line                                                        |
+| →      | Adds an arrow                                                      |
+| T      | Adds a text box                                                    |
+| ⬠      | Polygon / polyline (see *Drawing polygons*).                       |
+| Import | Add another SVG file as a shape inside the symbol.                 |
+| ↶ Undo | Undo the last change (also Cmd/Ctrl-Z).                            |
+| Zoom   | Slider — zooms the editor view only (does not change the symbol).  |
+
+### Selecting and editing shapes
+
+- **Click** a shape to select it. Its properties appear on the right.
+- **Click again** in the same spot to cycle through shapes stacked on top of
+  each other — useful when one shape is hidden behind another.
+- **Drag** a selected shape to move it; drag its handles to resize or
+  rotate.
+- **Backspace** / **Delete** removes the selected shape.
+- **Cmd/Ctrl-Z** undoes the last change.
+
+### Drawing polygons
+
+Click **⬠** button, then:
+
+1. Click each vertex on the canvas. A dashed rubber-band line follows the
+   cursor.
+2. **Double-click** to finish as an open polyline (good for tracks /
+   strokes).
+3. Or **click the start point** (highlighted with a small circle) to close
+   the shape — a closed polygon takes a fill color.
+4. **Esc** cancels the drawing.
+
+### Setting the anchor
+
+The blue ⊕ marker on the canvas is the **anchor point** — the pixel that
+consumer apps will place at the actual chart location. Drag the marker to
+move the anchor; the X/Y fields update as you drag. The marker is editor-only
+and is not written into the saved SVG. Instead, it is saved to "Map-marker metadata"
+property of the symbol.
+
+### Importing another SVG into the symbol
+
+**Import** prompts for an SVG file, sanitizes it, and drops it onto the
+canvas as a new shape group. When you're working on a **POI** template, the
+import is automatically scaled and centered into the POI's "body area". 
+For any other template, the import drops in at half size, centered. After import you can
+move and scale it like any other shape, and a **Fit into POI body** button
+in the right-hand panel re-runs the auto-fit any time.
+
+### Zooming and panning
+
+- The **Zoom** slider shows the view percentage. The minimum zoom is the
+  size at which the whole symbol fills the editor (typically a few hundred
+  percent); the maximum is 3000%.
+- When zoomed in, scrollbars appear inside the canvas frame. Drag them to
+  pan.
+- **Shift + click-drag** anywhere on the canvas pans the view.
+- **Mouse wheel / two-finger trackpad scroll** also pans (vertical wheel by
+  default, **Shift + wheel** to pan horizontally).
+- Zoom changes only how the editor *looks*. The saved symbol is unaffected.
+
+### Shape properties
+
+Selecting a shape shows controls for that shape:
+
+- **Text** field and **Font** picker (for text shapes).
+- **X / Y / W / H** in source pixels.
+- **Fill** and **Outline** color pickers (with a *none* button for
+  transparent fill), and **Outline width**.
+- **Opacity** slider, 0–100 %.
+- **Bring forward** / **Send backward** for stacking order.
+- **Fit into POI body** (only on the POI template).
+- **Delete shape**.
+
+### Symbol-wide properties
+
+With nothing selected, the panel shows whole-symbol metadata. Click anywhere
+in the editor that is outside of the symbol to show the symbol-wide properties:
+
+- **Id** - The identifier used by the consumer app (e.g. Freeboard SK)
+- **Namespace** - Used to distinguish symbols with the same **Id**
+- **Name** - Human readable name
+- **Description** - Human readable description
+- **Roles** - checkboxes describing what the symbol is *for*. The ones
+  tagged with a **chart** badge (`note`, `waypoint`, `map-marker`) mean the
+  symbol will be placed on a chart, which makes **Scale** and **Anchor**
+  required.
+- **Tags** - free-form keywords for search / filtering.
+- **Map-marker metadata** - **Scale** and **Anchor (X, Y)**. The fieldset
+  turns amber and is labelled *required* when any chart-role checkbox is
+  ticked.
+- **GPX mapping** - optional **GPX Type** and **GPX Sym** free-form text.
+  These record how the symbol maps to the `<type>` and `<sym>` fields of a
+  GPX waypoint, so a symbol-aware app can pick this symbol when importing a
+  GPX file (or write these values back when exporting). Leave them blank if
+  the symbol has no GPX equivalent.
+
+### Preview
+
+The preview pane shows the symbol against a sample nautical chart
+background, at the displayed size a consumer app will use:
+
+```
+displayed width  = source SVG width  × scale
+displayed height = source SVG height × scale
+```
+
+The **Scale** slider edits the symbol's scale metadata directly (it's not
+just a preview zoom). The *reset* link puts it back to the default (0.65,
+matching Freeboard's POI scale).
+
+### View / edit SVG source
+
+The **View / edit SVG source** link drops down a textarea with the raw SVG
+for the current canvas. You can hand-edit and click **Sanitize & apply to
+canvas** to push your edits back into the editor. The text is sanitized
+first, so any script / external reference / disallowed element is stripped
+before it lands on the canvas.
+
+### Saving
+
+**Save** sanitizes the SVG, validates that map-marker symbols have a scale
+and anchor, and writes the symbol to the library.
+
+## Direct upload (bypassing the editor)
+
+The visual editor handles a focused set of SVG features. If you have a
+complex SVG (gradients, filters, embedded fonts, intricate paths) that the
+editor would normalize away, use **Upload SVG** from the library list to
+add the file directly. You'll be asked to fill in the metadata (and, for
+map-marker symbols, scale and anchor) in a small form. The file is sanitized
+and stored as-is, with no editor round-trip.
+
+## Symbol references and overriding default icons
+
+This is how custom symbols **replace** the built-in icons in consumer apps.
+
+Every symbol has a **namespace** and an **id**, saved internally as
+`namespace:id` — for example `user:dive-site`. The Symbol Manager stores
+all symbols under the namespace **`user`** by default.
+
+Consumer apps that support symbol resources can ask the Signal K server
+for a symbol either way:
+
+| Lookup kind  | Example                                                | Returns                                                |
+|--------------|--------------------------------------------------------|--------------------------------------------------------|
+| Qualified    | `user:dive-site`                                       | Always your `user:dive-site` symbol.                   |
+| Unqualified  | `dive-site`                                            | The single symbol with that id, **regardless of namespace**. |
+
+That second form is what makes overrides work. Consumer apps typically ship
+default icons under their own namespace (e.g. Freeboard-SK ships
+`dive-site`, `anchor`, `mooring`, etc.). When the app asks the Signal K
+server for `dive-site` *without* a namespace and the Symbol Manager has
+**exactly one** symbol with id `dive-site`, the server returns yours — so
+your custom drawing appears on the chart in place of the app's built-in
+one.
+
+**To replace a built-in icon:**
+
+1. Find the id the consumer app uses (Freeboard's POI types are documented
+   in its own docs — e.g. `dive-site`, `anchor`, `mooring`, `marina`,
+   `restaurant`, …).
+2. In the Symbol Manager, create a new symbol with the **same id**.
+   Leave the namespace as `user` (default).
+3. Save. The consumer app picks up your symbol the next time it asks for
+   that id.
+
+A few notes:
+
+- The override only works for **unqualified** lookups. If the consumer app
+  hard-codes the qualified `built-in:dive-site` form, your `user:dive-site`
+  symbol will not replace it. Most consumer apps that support overrides use
+  the unqualified form on purpose.
+- If you create the *same* id under two different namespaces, the
+  unqualified lookup becomes ambiguous and the server returns an error
+  instead of guessing. Pick one namespace per id.
+- The id must match `[A-Za-z0-9_-]+` — letters, digits, underscores, and
+  dashes only.
+
+## Where things are stored
+
+Symbols and the SQLite metadata index live under your Signal K plugin data
+directory:
+
+```
+<signalk-data-dir>/plugin-config-data/signalk-symbol-manager/
+   symbols.sqlite       # metadata index
+   assets/<namespace>/<id>.svg    # the SVG files themselves
+```
+
+To back up your library, copy that directory. To start fresh, stop the
+server, delete it, and restart.
+
+## Limitations
+
+- The visual editor is intentionally small and focused on map-marker
+  symbols. For anything that would tax it, use **Upload SVG**.
+- Symbol creation, edits, and deletes go through the manager UI and require
+  Signal K **admin** access. Reading symbols is public if your server
+  allows read-only resource access.
+- The plugin does not generate native S-57 / ENC chart-portrayal catalogs —
+  that's a future enhancement.
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "signalk-symbol-manager",
+  "version": "0.5.0",
+  "description": "Create and manage chart symbols (icons for waypoints, notes, etc.)",
+  "main": "plugin/index.js",
+  "scripts": {
+    "dev": "vite",
+    "build:server": "tsc -p tsconfig.json",
+    "build:web": "vite build",
+    "build": "npm run build:server && npm run build:web",
+    "watch:server": "tsc -p tsconfig.json -w",
+    "watch:web": "vite build --watch",
+    "clean": "rm -rf plugin public/index.html public/assets",
+    "test": "npm run build:server && node --test test/*.test.js",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "signalk-node-server-plugin",
+    "signalk-webapp",
+    "signalk-category-chart-plotters",
+    "signalk-category-chart-utility",
+    "signalk",
+    "symbols",
+    "icons",
+    "svg",
+    "resource-provider",
+    "freeboard"
+  ],
+  "signalk": {
+    "appIcon": "assets/symbol-manager.png",
+    "displayName": "Chart Symbol Manager",
+    "screenshots": [
+      "./docs/screenshots/1_symbol-manager.png",
+      "./docs/screenshots/2_symbol-manager.png",
+      "./docs/screenshots/3_symbol-manager.png"
+    ],
+    "appstore": {
+      "displayName": "Chart Symbol Manager",
+      "categories": [
+        "chart-plotters",
+        "utilities"
+      ],
+      "author": "Joel Kozikowski",
+      "description": "Chart marker SVG editor with symbol provider"
+    },
+    "webapp": {
+      "name": "Chart Symbol Manager",
+      "description": "Chart marker SVG editor with symbol provider",
+      "location": "/signalk-symbol-manager/"
+    }
+  },
+  "files": [
+    "plugin",
+    "public",
+    "templates",
+    "assets",
+    "docs/screenshots",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "Joel Kozikowski",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joelkoz/signalk-symbol-manager.git"
+  },
+  "bugs": {
+    "url": "https://github.com/joelkoz/signalk-symbol-manager/issues"
+  },
+  "homepage": "https://github.com/joelkoz/signalk-symbol-manager#readme",
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "dependencies": {
+    "@xmldom/xmldom": "^0.9.6"
+  },
+  "devDependencies": {
+    "@signalk/server-api": "^2.10.1",
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.5.0",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "fabric": "^6.0.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-tag-input-component": "^2.0.2",
+    "typescript": "^5.5.4",
+    "vite": "^5.4.2"
+  }
+}