Plugin Interface

A TypeScript library for plugin management, built with React, TypeScript, and Vite.

Automatic Releases

Releases are automatically created when code is merged to main using semantic-release. Use conventional commit messages to trigger version bumps.

Commit Types

| Commit Type | Version Bump | Example | | ----------- | ------------ | ----------------------------- | | fix: | Patch | fix: resolve memory leak | | feat: | Minor | feat: add plugin validation | | feat!: | Major | feat!: refactor plugin API |

Other types (docs:, test:, chore:, etc.) do not trigger releases.

Version Examples

| Current | Commit Type | New Version | | ------- | ----------- | ----------- | | 0.0.1 | fix: | 0.0.2 | | 0.0.1 | feat: | 0.1.0 | | 0.1.0 | feat!: | 1.0.0 |

Process

1. Commit with conventional message (fix:, feat:, etc.)
2. Merge to main branch
3. CI/CD runs tests → builds → publishes (if tests pass)

Note: Only commits on main trigger releases. Multiple commits use the highest version bump type.

Development

npm install          # Install dependencies
npm run dev          # Development server
npm test             # Run tests
npm run build:lib    # Build library
npm run lint         # Lint code

Storybook

Storybook provides an interactive development environment for exploring and testing plugin integrations in isolation.

Running Storybook

npm run dev          # Start Storybook dev server (usually http://localhost:6006)

Available Stories

Located in the ./dev folder:

• PluginIntegration: Shows real-time interaction with plugin state (time, animation, lifecycle controls)

Benefits

• Isolated Development: Test components without running the full application
• Live Documentation: Interactive examples with editable props via Controls panel
• Visual Testing: See component states and variations side-by-side
• Accessibility: Built-in a11y addon helps catch accessibility issues early
• Rapid Prototyping: Quickly iterate on plugin behavior and UI integration

Stories include comprehensive documentation explaining the plugin architecture, custom hooks, and usage patterns.

Time Scope API

import {
  PluginManager,
  setTime,
  toIso8601Utc,
  assertIso8601Utc,
  type Iso8601Utc,
} from "plugin-interface";

const manager = new PluginManager();
const instance =
  /* previously registered plugin instance with 'time' scope */ null as any;

// Basic: pass a valid UTC timestamp literal (compile-time shape checked)
setTime(instance, "2024-10-10T10:10:10Z");

// From Date: convert explicitly
const isoFromDate = toIso8601Utc(new Date());
setTime(instance, isoFromDate);

// Dynamic strings: setTime performs runtime validation and throws on invalid input
const raw = await fetchSomeTimestamp();
setTime(instance, raw);

// Optional pre-validation for clearer local error handling
try {
  const safe: Iso8601Utc = assertIso8601Utc(raw);
  setTime(instance, safe);
} catch (err) {
  console.error("Invalid time format", err);
}

// Explicit conversion example
const iso: Iso8601Utc = toIso8601Utc(new Date("2025-01-01T00:00:00.999Z"));
setTime(instance, iso);

Time Format & Validation

• Format: UTC ISO 8601 at seconds precision (YYYY-MM-DDTHH:MM:SSZ).
• Compile-time: template literal type Iso8601Utc validates only literal shapes.
• Runtime: setTime and helpers validate strings; errors include actionable hints (e.g., milliseconds present).

Helpers

• setTime(instance, iso): Dispatches the time scope setTime event if iso is valid.
• toIso8601Utc(date): Returns a compliant UTC string; removes milliseconds.
• assertIso8601Utc(str): Throws if str is not compliant; narrows type to Iso8601Utc when valid.

If you need offsets or milliseconds support in the future, extend the validation and helpers while preserving the current API surface.