feat: add api + interfaces

Author: stee-re

.github/actions/setup-node-env/action.yml

@@ -0,0 +1,49 @@
+name: 'Setup Node Environment'
+description: 'Setup Node, cache and clean install'
+
+inputs:
+  registry-url:
+    description: 'the url for the registry (github or npm)'
+    required: false
+    default: 'https://registry.npmjs.org'
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Node.js
+      uses: actions/setup-node@v3
+      with:
+        node-version: '20'
+        registry-url: ${{ inputs.registry-url }}
+
+    - name: Cache Node Modules
+      id: cache-node-modules
+      uses: actions/cache@v4
+      with:
+        path: |
+          node_modules
+        key: modules-${{ hashFiles('package-lock.json') }}
+
+    - name: Cache Playwright Binaries
+      id: cache-playwright
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cache/ms-playwright
+        key: playwright-${{ hashFiles('package-lock.json') }}
+
+    - name: Install dependencies
+      if: steps.cache-node-modules.outputs.cache-hit != 'true'
+      run: npm ci
+      shell: bash
+
+    - name: Install playwright browsers
+      if: steps.cache-playwright.outputs.cache-hit != 'true'
+      run: npx playwright install --with-deps
+      shell: bash
+
+    - name: Install system dependencies for WebKit
+      # Some WebKit dependencies seem to lay outside the cache and will need to be installed separately
+      if: steps.cache-playwright.outputs.cache-hit == 'true'
+      run: npx playwright install-deps webkit
+      shell: bash

.github/workflows/release-please.yml

@@ -0,0 +1,39 @@
+name: release-please
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  npm-publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-node-env
+        with:
+          registry-url: "https://registry.npmjs.org"
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/test.yml

@@ -0,0 +1,17 @@
+name: Test
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - uses: ./.github/actions/setup-node-env
+
+      - name: Build
+        run: npm run-script build
+
+      - name: Run unit tests
+        run: npm run-script test

.gitignore

@@ -0,0 +1,15 @@
+node_modules
+*.js
+*.map
+*.d.ts
+*.tsbuildinfo
+
+## editors
+/.idea
+/.vscode
+
+## build artifacts
+dist
+coverage
+
+

.release-please-manifest.json

@@ -0,0 +1 @@
+{ ".": "0.0.1" }

README.md

@@ -0,0 +1,25 @@
+# OpenSCD API
+
+This package defines a common set of APIs, types, and interfaces for use by [OpenSCD](https://openscd.org) distributions and plugins.  
+It does **not** contain any business logic or implementation—only the shared contracts that enable interoperability between OpenSCD core, plugins, and distribution builders.
+
+## Purpose
+
+- **For Plugin Developers:**  
+  Provides the types and event interfaces needed to build plugins that integrate seamlessly with OpenSCD core.  
+  See [docs/plugin-api.md](docs/plugin-api.md) for a detailed description of the plugin API.
+
+- **For Distribution Builders:**  
+  Supplies the types and interfaces for the OpenSCD root element and other extension points.  
+  _API documentation for the OpenSCD root element and constraints for `plugin.json` will be provided in future docs._
+
+## Documentation
+
+- [Plugin API](docs/plugin-api.md):  
+  Comprehensive guide for plugin authors, including property contracts, event types, and theming.
+
+- _Additional documentation (e.g., for the OpenSCD root element and `plugin.json` constraints) will be added soon._
+
+## License
+
+[Apache-2.0](LICENSE)

Transactor.ts

@@ -0,0 +1,44 @@
+export type CommitOptions = {
+  /** An optional human-readable description of the committed change */
+  title?: string;
+  /**
+   * If true, the commit will be squashed into the previous commit,
+   * overriding the previous title if a title is also provided.
+   */
+  squash?: boolean;
+};
+/** Record of changes committed */
+export interface Commit<Change> {
+  /** The inverse of the changes that were committed */
+  undo: Change[];
+  /** The changes that were committed */
+  redo: Change[];
+  /** An optional human-readable description of the committed changes */
+  title?: string;
+}
+export type TransactedCallback<Change> = (txRecord: Commit<Change>) => void;
+/**
+ * Transactor is an interface that defines a transaction manager for managing
+ * changes in a system. It provides methods to commit changes, undo and redo
+ * changes, and subscribe to transaction events.
+ * @template Change - The type of changes that can be committed.
+ */
+export interface Transactor<Change> {
+  /** Commits a change, returning the resultant record. */
+  commit(change: Change, options?: CommitOptions): Commit<Change>;
+  /** Undoes the most reset `past` `Commit`, if any, returning it. */
+  undo(): Commit<Change> | undefined;
+  /** Redoes the most recent `future` `Commit`, if any, returning it. */
+  redo(): Commit<Change> | undefined;
+  /** All changes that have been committed and not yet undone. */
+  past: Commit<Change>[];
+  /** All changes that have been undone and can be redone. */
+  future: Commit<Change>[];
+  /**
+   * Registers `txCallback`, which will be called on every new `commit`.
+   * @returns a function that will **unsubscribe** the callback, returning it.
+   */
+  subscribe(
+    txCallback: TransactedCallback<Change>,
+  ): () => TransactedCallback<Change>;
+}