Custom Elements Manifest

.github/workflows/build.yaml

@@ -883,6 +883,9 @@ jobs:
                   name: perspective-server-wasm64-dist
                   path: rust/perspective-server/dist/wasm
 
+            - name: Consumer checks
+              run: pnpm run test:consumers
+
             - name: Run Tests
               id: run_tests
               run: pnpm run test -- --fetch-snapshots
@@ -945,9 +948,6 @@ jobs:
                   name: perspective-server-wasm64-dist
                   path: rust/perspective-server/dist/wasm
 
-            - name: Consumer checks
-              run: pnpm run test:consumers
-
             - name: Run Tests
               id: run_tests
               run: pnpm run test -- --fetch-snapshots

docs/md/how_to/javascript/viewer.md

@@ -47,18 +47,30 @@ the table after a page reload, and <code>restore()</code> will fail.</div>
 
 ## Attributes
 
-`<perspective-viewer>` can be configured via HTML attributes or JavaScript
-properties. When set as attributes, the viewer will apply the configuration on
-initialization:
+`<perspective-viewer>` reads one HTML attribute, `theme`, which selects the
+initial theme by the `--psp-theme-name` a loaded stylesheet declares. Every
+other setting is applied through the JavaScript API, typically `restore()`,
+and the viewer reflects the active theme back onto the same attribute when the
+user picks one:
 
 ```html
-<perspective-viewer
-    columns='["Sales", "Profit"]'
-    group-by='["Region"]'
-    sort='[["Sales", "desc"]]'>
-</perspective-viewer>
+<perspective-viewer theme="Pro Dark"></perspective-viewer>
 ```
 
+```javascript
+await viewer.restore({ columns: ["Sales", "Profit"], group_by: ["Region"] });
+```
+
+## Editor and tooling support
+
+`@perspective-dev/viewer` ships a
+[Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest)
+at `dist/custom-elements.json`, advertised by the `customElements` field of its
+`package.json`. It enumerates the element's methods, static methods, events,
+the `theme` attribute, slots, the `tab` shadow part and every theme CSS custom
+property, so editors, Storybook and documentation generators that read the
+manifest can offer completion and reference tables without any further setup.
+
 ## UI Features
 
 The viewer provides an interactive side panel with:

pnpm-workspace.yaml

@@ -33,6 +33,7 @@ overrides:
     "@perspective-dev/client@5.3.0>@perspective-dev/server": "5.3.0"
     "@perspective-dev/client@5.4.0>@perspective-dev/server": "5.4.0"
     "@perspective-dev/client@5.5.0>@perspective-dev/server": "5.5.0"
+    "apache-arrow>@types/node": "catalog:"
 
 allowBuilds:
     "@fortawesome/fontawesome-free": true

rust/perspective-viewer/build.mjs

@@ -23,6 +23,7 @@ import {
 } from "lightningcss";
 import { compress } from "pro_self_extracting_wasm";
 import {
+    buildCustomElementsManifest,
     buildDocsCorpus,
     get_host,
     inlineUrlVisitor,
@@ -63,6 +64,11 @@ export async function build_all() {
         `docs corpus: ${docs_stats.chunks} chunks / ${docs_stats.bytes} bytes from ${docs_stats.files} files`,
     );
 
+    const cem_stats = await buildCustomElementsManifest();
+    console.log(
+        `custom-elements.json: ${cem_stats.members} members / ${cem_stats.events} events / ${cem_stats.cssProperties} css properties / ${cem_stats.exports} exports`,
+    );
+
     // JavaScript
     const BUILD = [
         // No WASM assets inlined or linked.

rust/perspective-viewer/package.json

@@ -58,6 +58,7 @@
         "dist/**/*"
     ],
     "types": "dist/esm/perspective-viewer.d.ts",
+    "customElements": "dist/custom-elements.json",
     "scripts": {
         "build": "node ./build.mjs",
         "clean": "node ./clean.mjs",

rust/perspective-viewer/src/ts/extensions.ts

@@ -38,6 +38,26 @@ export type PerspectiveSelectEventDetail = {
     view_window: ViewWindow;
 };
 
+export type PerspectiveLayoutUpdateEventDetail = {
+    panels: string[];
+};
+
+export type PerspectiveActivePanelUpdateEventDetail = {
+    panel: string | null;
+};
+
+export type PerspectiveColumnStyleChangeEventDetail = Record<
+    string,
+    Record<string, unknown>
+> & {
+    panel?: string;
+};
+
+export type PerspectiveToggleColumnSettingsEventDetail = {
+    open: boolean;
+    column_name: string | null;
+};
+
 export type PerspectiveConfigUpdateEventDetail = {
     /**
      * Serialize the panel config that triggered this event, ON DEMAND. The
@@ -223,63 +243,124 @@ export interface PerspectiveViewerElementExt {
 
     get_worker_url(): URL;
 
+    /** Fires when a plugin's grid or chart is clicked, with the clicked row and a `config` whose filters reproduce it. */
     addEventListener(
         name: "perspective-click",
-        cb: (e: CustomEvent) => void,
+        cb: (e: CustomEvent<PerspectiveClickEventDetail>) => void,
         options?: { signal: AbortSignal },
     ): void;
 
+    /** Fires when a plugin's selection changes, with the configs whose filters to insert and remove. */
     addEventListener(
         name: "perspective-select",
-        cb: (e: CustomEvent) => void,
+        cb: (e: CustomEvent<PerspectiveSelectDetail>) => void,
         options?: { signal: AbortSignal },
     ): void;
 
+    /** Fires on a master panel's selection, before it is applied to the global filter set. */
     addEventListener(
         name: "perspective-global-filter",
         cb: (e: CustomEvent<PerspectiveSelectDetail>) => void,
         options?: { signal: AbortSignal },
     ): void;
 
+    /** Fires whenever the global filter set changes, with the new `Filter[]`. */
     addEventListener(
         name: "perspective-global-filter-update",
         cb: (e: CustomEvent<Filter[]>) => void,
         options?: { signal: AbortSignal },
     ): void;
 
+    /** Fires after the settings sidebar opens or closes, with the new open state. */
     addEventListener(
         name: "perspective-toggle-settings",
-        cb: (e: CustomEvent) => void,
+        cb: (e: CustomEvent<boolean>) => void,
         options?: { signal: AbortSignal },
     ): void;
 
+    /** Fires before the settings sidebar opens or closes, with the pending open state. */
     addEventListener(
         name: "perspective-toggle-settings-before",
-        cb: (e: CustomEvent) => void,
+        cb: (e: CustomEvent<boolean>) => void,
+        options?: { signal: AbortSignal },
+    ): void;
+
+    /** Fires when the column settings sidebar opens or closes, with the column it shows. */
+    addEventListener(
+        name: "perspective-toggle-column-settings",
+        cb: (
+            e: CustomEvent<PerspectiveToggleColumnSettingsEventDetail>,
+        ) => void,
         options?: { signal: AbortSignal },
     ): void;
 
+    /** Fires after a panel's view config changes, with a deferred `getConfig()` accessor valid only during dispatch. */
     addEventListener(
         name: "perspective-config-update",
         cb: (e: CustomEvent<PerspectiveConfigUpdateEventDetail>) => void,
         options?: { signal: AbortSignal },
     ): void;
 
+    /** Fires when a panel's active plugin changes, with the new plugin element as its detail. */
+    addEventListener(
+        name: "perspective-plugin-update",
+        cb: (e: CustomEvent<HTMLPerspectiveViewerPluginElement>) => void,
+        options?: { signal: AbortSignal },
+    ): void;
+
+    /** Fires when a panel's per-column style config changes, keyed by column name. */
+    addEventListener(
+        name: "perspective-column-style-change",
+        cb: (e: CustomEvent<PerspectiveColumnStyleChangeEventDetail>) => void,
+        options?: { signal: AbortSignal },
+    ): void;
+
+    /** Fires when a panel is added to or removed from the layout, with the placed panel ids in order. */
+    addEventListener(
+        name: "perspective-layout-update",
+        cb: (e: CustomEvent<PerspectiveLayoutUpdateEventDetail>) => void,
+        options?: { signal: AbortSignal },
+    ): void;
+
+    /** Fires when the active panel changes, with its id or `null` at zero panels. */
+    addEventListener(
+        name: "perspective-active-panel-update",
+        cb: (e: CustomEvent<PerspectiveActivePanelUpdateEventDetail>) => void,
+        options?: { signal: AbortSignal },
+    ): void;
+
+    /** Fires with the original `pointerdown` as its detail when the status bar is pressed. */
     addEventListener(
         name: "perspective-statusbar-pointerdown",
-        cb: (e: CustomEvent) => void,
+        cb: (e: CustomEvent<PointerEvent>) => void,
+        options?: { signal: AbortSignal },
+    ): void;
+
+    /** Fires when a panel's status indicator is clicked. */
+    addEventListener(
+        name: "perspective-status-indicator-click",
+        cb: (e: CustomEvent<undefined>) => void,
+        options?: { signal: AbortSignal },
+    ): void;
+
+    /** Fires when the agent invokes a tool, with a JSON string of `{name, args}` as its detail. */
+    addEventListener(
+        name: "perspective-agent-tool",
+        cb: (e: CustomEvent<string>) => void,
         options?: { signal: AbortSignal },
     ): void;
 
+    /** Fires after a panel's `Table` is deleted and the panel unloaded. */
     addEventListener(
         name: "perspective-table-delete",
-        cb: (e: CustomEvent) => void,
+        cb: (e: CustomEvent<undefined>) => void,
         options?: { signal: AbortSignal },
     ): void;
 
+    /** Fires before a panel's `Table` is deleted, while its `View` is still live. */
     addEventListener(
         name: "perspective-table-delete-before",
-        cb: (e: CustomEvent) => void,
+        cb: (e: CustomEvent<undefined>) => void,
         options?: { signal: AbortSignal },
     ): void;
 
@@ -295,11 +376,24 @@ export interface PerspectiveViewerElementExt {
         name: "perspective-toggle-settings-before",
         cb: any,
     ): void;
+    removeEventListener(
+        name: "perspective-toggle-column-settings",
+        cb: any,
+    ): void;
     removeEventListener(name: "perspective-config-update", cb: any): void;
+    removeEventListener(name: "perspective-plugin-update", cb: any): void;
+    removeEventListener(name: "perspective-column-style-change", cb: any): void;
+    removeEventListener(name: "perspective-layout-update", cb: any): void;
+    removeEventListener(name: "perspective-active-panel-update", cb: any): void;
     removeEventListener(
         name: "perspective-statusbar-pointerdown",
         cb: any,
     ): void;
+    removeEventListener(
+        name: "perspective-status-indicator-click",
+        cb: any,
+    ): void;
+    removeEventListener(name: "perspective-agent-tool", cb: any): void;
     removeEventListener(name: "perspective-table-delete", cb: any): void;
     removeEventListener(name: "perspective-table-delete-before", cb: any): void;
 }