@adminiumjs/adminium 0.1.0-rc.1

package/dist/widget-data/shapers.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Row → data-contract envelope shapers (04-widget-registry.md §5.2 step 5).
+ *
+ * The server returns payloads in exactly the §3 canonical envelopes, with a
+ * `shape` discriminant so client narrowing is a tagged union: single-metric
+ * `{ value }`, metric+delta `{ value, prior?, deltaPct? }`, timeseries
+ * `{ points: [{ t, v }], compare? }`, categorical `{ items, total }`, and
+ * record-list `{ rows, columns, total }` (PII-masked).
+ */
+import { type Row } from '../crud/mask.js';
+import { type CompiledWidgetQuery } from './compiler.js';
+export interface TsPoint {
+    /** ISO 8601 bucket start. */
+    t: string;
+    v: number;
+}
+export interface ShapedSingleMetric {
+    shape: 'single-metric';
+    value: number;
+}
+export interface ShapedMetricDelta {
+    shape: 'metric+delta';
+    value: number;
+    prior?: number;
+    deltaPct?: number;
+}
+export interface ShapedTimeseries {
+    shape: 'timeseries';
+    points: TsPoint[];
+    compare?: TsPoint[];
+}
+export interface ShapedCategorical {
+    shape: 'categorical';
+    items: {
+        key: string;
+        label: string;
+        value: number;
+    }[];
+    total: number;
+}
+export interface ColumnMeta {
+    name: string;
+    logicalType: string;
+    nullable: boolean;
+    isPrimaryKey: boolean;
+}
+export interface ShapedRecordList {
+    shape: 'record-list';
+    rows: Row[];
+    columns: ColumnMeta[];
+    total: number;
+}
+export interface ShapedStream {
+    shape: 'stream';
+    /** Authoritative WS channel the client subscribes to (04 §5.3). */
+    channel: string;
+    /** Initial (PII-masked) rows, newest-first. */
+    snapshot: Row[];
+    columns: ColumnMeta[];
+}
+export type ShapedPayload = ShapedSingleMetric | ShapedMetricDelta | ShapedTimeseries | ShapedCategorical | ShapedRecordList | ShapedStream;
+/** PG returns numerics/bigints as strings — coerce every metric to number. */
+export declare function toNumber(value: unknown): number;
+export interface ShapeInput {
+    compiled: CompiledWidgetQuery;
+    rows: Row[];
+    priorRows?: Row[] | undefined;
+    /** `record-list` exact count (from the compiled `count` twin). */
+    total?: number | undefined;
+    canReadPii: boolean;
+    /** Connection id — needed to build the `stream` channel name. */
+    connectionId?: string | undefined;
+}
+export declare function shapeRows(input: ShapeInput): ShapedPayload;
+//# sourceMappingURL=shapers.d.ts.map

package/dist/widget-data/shapers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapers.d.ts","sourceRoot":"","sources":["../../src/widget-data/shapers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAY,KAAK,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAErD,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAE3E,MAAM,WAAW,OAAO;IACtB,6BAA6B;IAC7B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,eAAe,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,aAAa,CAAC;IACrB,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,EAAE,GAAG,EAAE,CAAC;IAChB,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GACrB,kBAAkB,GAClB,iBAAiB,GACjB,gBAAgB,GAChB,iBAAiB,GACjB,gBAAgB,GAChB,YAAY,CAAC;AAEjB,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQ/C;AA0BD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,SAAS,CAAC,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC;IAC9B,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAWD,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,CA4E1D"}

package/dist/widget-data/shapers.js

@@ -0,0 +1,128 @@
+/**
+ * Row → data-contract envelope shapers (04-widget-registry.md §5.2 step 5).
+ *
+ * The server returns payloads in exactly the §3 canonical envelopes, with a
+ * `shape` discriminant so client narrowing is a tagged union: single-metric
+ * `{ value }`, metric+delta `{ value, prior?, deltaPct? }`, timeseries
+ * `{ points: [{ t, v }], compare? }`, categorical `{ items, total }`, and
+ * record-list `{ rows, columns, total }` (PII-masked).
+ */
+import { maskRows } from '../crud/mask.js';
+import { widgetDataChannel } from '../realtime/hub.js';
+import { GROUP_BUCKET_CAP } from './compiler.js';
+/** PG returns numerics/bigints as strings — coerce every metric to number. */
+export function toNumber(value) {
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    if (typeof value === 'bigint')
+        return Number(value);
+    return 0;
+}
+function toIso(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === 'string') {
+        const parsed = new Date(value);
+        if (!Number.isNaN(parsed.getTime()))
+            return parsed.toISOString();
+        return value;
+    }
+    return String(value);
+}
+function firstAlias(compiled) {
+    const alias = compiled.aggregationAliases[0];
+    if (alias === undefined)
+        throw new Error('shaper: no aggregation alias (compiler bug)');
+    return alias;
+}
+function metricOf(rows, alias) {
+    return toNumber(rows[0]?.[alias]);
+}
+function pointsOf(rows, bucketAlias, valueAlias) {
+    return rows.map((row) => ({ t: toIso(row[bucketAlias]), v: toNumber(row[valueAlias]) }));
+}
+function columnMetaOf(compiled) {
+    return compiled.selectedColumns.map((column) => ({
+        name: column.name,
+        logicalType: column.logicalType,
+        nullable: column.nullable,
+        isPrimaryKey: column.isPrimaryKey,
+    }));
+}
+export function shapeRows(input) {
+    const { compiled, rows, priorRows, canReadPii } = input;
+    switch (compiled.shape) {
+        case 'single-metric':
+            return { shape: 'single-metric', value: metricOf(rows, firstAlias(compiled)) };
+        case 'metric+delta': {
+            const alias = firstAlias(compiled);
+            const value = metricOf(rows, alias);
+            if (priorRows === undefined)
+                return { shape: 'metric+delta', value };
+            const prior = metricOf(priorRows, alias);
+            return prior === 0
+                ? { shape: 'metric+delta', value, prior }
+                : { shape: 'metric+delta', value, prior, deltaPct: (value - prior) / Math.abs(prior) };
+        }
+        case 'timeseries': {
+            const alias = firstAlias(compiled);
+            const bucketAlias = compiled.bucketAlias ?? '__bucket';
+            const points = pointsOf(rows, bucketAlias, alias);
+            return priorRows === undefined
+                ? { shape: 'timeseries', points }
+                : { shape: 'timeseries', points, compare: pointsOf(priorRows, bucketAlias, alias) };
+        }
+        case 'categorical': {
+            const alias = firstAlias(compiled);
+            const groupAlias = compiled.groupAlias ?? '__group';
+            const items = rows.map((row) => {
+                const key = row[groupAlias] === null ? '__null' : String(row[groupAlias]);
+                return {
+                    key,
+                    label: row[groupAlias] === null ? '—' : String(row[groupAlias]),
+                    value: toNumber(row[alias]),
+                };
+            });
+            // Cardinality cap: rows arrive ordered by value desc (compiler); fold
+            // the tail into `__other` (04 §5.2 guardrails — fold is over fetched
+            // rows, themselves bounded by the hard LIMIT).
+            let capped = items;
+            if (items.length > GROUP_BUCKET_CAP) {
+                const head = items.slice(0, GROUP_BUCKET_CAP);
+                const otherValue = items.slice(GROUP_BUCKET_CAP).reduce((sum, item) => sum + item.value, 0);
+                capped = [...head, { key: '__other', label: 'Other', value: otherValue }];
+            }
+            const total = capped.reduce((sum, item) => sum + item.value, 0);
+            return { shape: 'categorical', items: capped, total };
+        }
+        case 'record-list': {
+            return {
+                shape: 'record-list',
+                rows: maskRows(rows, compiled.table, canReadPii),
+                columns: columnMetaOf(compiled),
+                total: input.total ?? rows.length,
+            };
+        }
+        case 'stream': {
+            // Server-authoritative channel from the RESOLVED table id — the client
+            // subscribes to exactly what the CRUD/job publisher fans out on (04 §5.3).
+            if (input.connectionId === undefined) {
+                throw new Error('shaper: stream shape requires connectionId (route bug)');
+            }
+            return {
+                shape: 'stream',
+                channel: widgetDataChannel(input.connectionId, compiled.table.id),
+                snapshot: maskRows(rows, compiled.table, canReadPii),
+                columns: columnMetaOf(compiled),
+            };
+        }
+        default:
+            throw new Error(`shaper: unsupported shape ${String(compiled.shape)} (compiler bug)`);
+    }
+}
+//# sourceMappingURL=shapers.js.map

package/dist/widget-data/shapers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapers.js","sourceRoot":"","sources":["../../src/widget-data/shapers.ts"],"names":[],"mappings":"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"}

package/dist/widget-data/stream-publisher.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Widget-data stream publisher (04-widget-registry.md §5.3). The single place
+ * server code fans a data mutation out to the live stream widgets subscribed to
+ * `widget-data:{connectionId}:{table.id}` — the CRUD write path and, for
+ * data-producing jobs, the job-completion path.
+ *
+ * PII/secret gating (acceptance #5, "never stream a forbidden column"): both the
+ * row AND the primary key are masked here with `unmasked = false`, so secret
+ * columns are stripped and PII columns nulled regardless of any subscriber's
+ * grants. The pk gets the same treatment as the row because a natural key can
+ * itself be a PII column (e.g. email/phone as the primary key) — leaving it raw
+ * would leak the exact value the row masking nulls out. A subscriber still had
+ * to pass the table-read check to be on the channel (`authorizeChannel`), but
+ * masking is the belt-and-braces guarantee since the channel is shared across
+ * roles. Publishing with no subscribers is a silent no-op.
+ */
+import type { ResolvedTable } from '../crud/identifiers.js';
+import { type Row } from '../crud/mask.js';
+import { type RealtimeHub } from '../realtime/hub.js';
+export interface WidgetStreamMutation {
+    connectionId: string;
+    /** Resolved snapshot table (carries the masking metadata + the id). */
+    table: ResolvedTable;
+    /** Event type, e.g. `record.create` | `record.update` | `record.delete`. */
+    type: string;
+    /**
+     * Primary key of the affected row, keyed by PK column name (a `Row`). Masked
+     * before publish just like `row`, since a natural key can be a PII column.
+     */
+    pk?: Row | null | undefined;
+    /** Affected row: the after-image for create/update, the pre-image for delete. */
+    row?: Row | null | undefined;
+    /** Event timestamp (ms); defaults to the hub's `Date.now()`. */
+    at?: number | undefined;
+}
+/**
+ * Publish one widget-data stream event. The `row` is PII-masked before it
+ * leaves the process; `delete` events (or callers with no row) publish
+ * `row: null` and rely on `pk` for buffer removal client-side.
+ */
+export declare function publishWidgetDataStream(hub: RealtimeHub, mutation: WidgetStreamMutation): void;
+//# sourceMappingURL=stream-publisher.d.ts.map

package/dist/widget-data/stream-publisher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-publisher.d.ts","sourceRoot":"","sources":["../../src/widget-data/stream-publisher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAW,KAAK,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEzE,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,KAAK,EAAE,aAAa,CAAC;IACrB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,EAAE,CAAC,EAAE,GAAG,GAAG,IAAI,GAAG,SAAS,CAAC;IAC5B,iFAAiF;IACjF,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,GAAG,SAAS,CAAC;IAC7B,gEAAgE;IAChE,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAW9F"}

package/dist/widget-data/stream-publisher.js

@@ -0,0 +1,34 @@
+/**
+ * Widget-data stream publisher (04-widget-registry.md §5.3). The single place
+ * server code fans a data mutation out to the live stream widgets subscribed to
+ * `widget-data:{connectionId}:{table.id}` — the CRUD write path and, for
+ * data-producing jobs, the job-completion path.
+ *
+ * PII/secret gating (acceptance #5, "never stream a forbidden column"): both the
+ * row AND the primary key are masked here with `unmasked = false`, so secret
+ * columns are stripped and PII columns nulled regardless of any subscriber's
+ * grants. The pk gets the same treatment as the row because a natural key can
+ * itself be a PII column (e.g. email/phone as the primary key) — leaving it raw
+ * would leak the exact value the row masking nulls out. A subscriber still had
+ * to pass the table-read check to be on the channel (`authorizeChannel`), but
+ * masking is the belt-and-braces guarantee since the channel is shared across
+ * roles. Publishing with no subscribers is a silent no-op.
+ */
+import { maskRow } from '../crud/mask.js';
+import { widgetDataChannel } from '../realtime/hub.js';
+/**
+ * Publish one widget-data stream event. The `row` is PII-masked before it
+ * leaves the process; `delete` events (or callers with no row) publish
+ * `row: null` and rely on `pk` for buffer removal client-side.
+ */
+export function publishWidgetDataStream(hub, mutation) {
+    const channel = widgetDataChannel(mutation.connectionId, mutation.table.id);
+    const row = mutation.row === null || mutation.row === undefined
+        ? null
+        : maskRow(mutation.row, mutation.table, false);
+    const pk = mutation.pk === null || mutation.pk === undefined
+        ? null
+        : maskRow(mutation.pk, mutation.table, false);
+    hub.publish(channel, mutation.type, { type: mutation.type, pk, row }, mutation.at);
+}
+//# sourceMappingURL=stream-publisher.js.map

package/dist/widget-data/stream-publisher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-publisher.js","sourceRoot":"","sources":["../../src/widget-data/stream-publisher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,OAAO,EAAY,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAoB,MAAM,oBAAoB,CAAC;AAmBzE;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAgB,EAAE,QAA8B;IACtF,MAAM,OAAO,GAAG,iBAAiB,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC5E,MAAM,GAAG,GACP,QAAQ,CAAC,GAAG,KAAK,IAAI,IAAI,QAAQ,CAAC,GAAG,KAAK,SAAS;QACjD,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACnD,MAAM,EAAE,GACN,QAAQ,CAAC,EAAE,KAAK,IAAI,IAAI,QAAQ,CAAC,EAAE,KAAK,SAAS;QAC/C,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAClD,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;AACrF,CAAC"}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@adminiumjs/adminium",
+  "version": "0.1.0-rc.1",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MoSofi/Adminium.git",
+    "directory": "apps/server"
+  },
+  "homepage": "https://adminium.dev",
+  "bugs": "https://github.com/MoSofi/Adminium/issues",
+  "type": "module",
+  "description": "Fastify server: REST /api/v1, auth, jobs, serves the dashboard build",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "adminium": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "dashboard",
+    "vocabulary",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@adminium/adapter-mysql": "npm:@adminiumjs/adapter-mysql@0.1.0-rc.1",
+    "@adminium/adapter-postgres": "npm:@adminiumjs/adapter-postgres@0.1.0-rc.1",
+    "@adminium/adapter-sqlite": "npm:@adminiumjs/adapter-sqlite@0.1.0-rc.1",
+    "@adminium/engine": "npm:@adminiumjs/engine@0.1.0-rc.1",
+    "@adminium/llm": "npm:@adminiumjs/llm@0.1.0-rc.1",
+    "@adminium/meta": "npm:@adminiumjs/meta@0.1.0-rc.1",
+    "@adminium/schema-import": "npm:@adminiumjs/schema-import@0.1.0-rc.1",
+    "@fastify/cookie": "^11.0.2",
+    "@fastify/cors": "^10.1.0 || ^11.0.0",
+    "@fastify/helmet": "^13.1.0",
+    "@fastify/rate-limit": "^11.1.0",
+    "@fastify/static": "^8.2.0",
+    "@fastify/websocket": "^11.0.2",
+    "argon2": "^0.44.0",
+    "better-sqlite3": "^12.2.0",
+    "croner": "^9.1.0",
+    "fastify": "^5.4.0",
+    "fastify-plugin": "^5.0.1",
+    "fastify-type-provider-zod": "^5.0.0 || ^6.0.0",
+    "fflate": "^0.8.3",
+    "kysely": "^0.28.2",
+    "otpauth": "^9.4.0",
+    "pino": "^9.7.0",
+    "zod": "^4.4.3"
+  },
+  "//optionalDependencies": [
+    "The META-STORE drivers (07-meta-store.md; 01-architecture.md §4.2).",
+    "src/meta/store.ts opens the meta store with a bare `await import('pg')` /",
+    "`import('mysql2')`. They are declared HERE, on the server, and not merely",
+    "reached through @adminium/adapter-postgres / -mysql, because a bare",
+    "specifier resolves against the IMPORTING package's node_modules: the",
+    "Dockerfile's `pnpm deploy --filter=@adminium/server --prod` produces an",
+    "isolated tree where an adapter's own dependency lands under .pnpm and is",
+    "unreachable from /app/dist. Without these the published image can run only",
+    "the embedded SQLite fallback that §3.1 tells people not to use in",
+    "production, while docker-compose.yml documents a postgres meta store — a",
+    "crash-loop under `restart: unless-stopped`, with the printed remedy",
+    "(`npm install pg`) impossible inside a non-root image.",
+    "OPTIONAL, not required: both are pure JS so they always install in",
+    "practice, but `--no-optional` stays a supported way to ship a SQLite-only",
+    "install, and MetaDriverMissingError still explains that case."
+  ],
+  "optionalDependencies": {
+    "mysql2": "^3.15.3",
+    "pg": "^8.16.3"
+  }
+}

package/vocabulary/llm-allowlist.json

@@ -0,0 +1,76 @@
+{
+  "LLM_ALLOWED_TEMPLATES": [
+    "page-board",
+    "page-calendar",
+    "page-chat",
+    "page-dashboard",
+    "page-directory",
+    "page-files",
+    "page-log-viewer",
+    "page-master-detail",
+    "page-queue-inbox",
+    "page-scheduler"
+  ],
+  "LLM_ALLOWED_WIDGETS": [
+    "accordion-list",
+    "activity-feed",
+    "auto-insights",
+    "card-gallery",
+    "chart-anomaly",
+    "chart-bar",
+    "chart-boxplot",
+    "chart-bullet",
+    "chart-bump",
+    "chart-candlestick",
+    "chart-chord",
+    "chart-choropleth-grid",
+    "chart-cohort-matrix",
+    "chart-correlation-matrix",
+    "chart-donut",
+    "chart-forecast",
+    "chart-funnel",
+    "chart-heat-month",
+    "chart-heatmap-calendar",
+    "chart-hexbin",
+    "chart-line-area",
+    "chart-marimekko",
+    "chart-multiline",
+    "chart-parallel-coordinates",
+    "chart-pareto",
+    "chart-radar",
+    "chart-radial-bar",
+    "chart-ranking-bars",
+    "chart-ridgeline",
+    "chart-sankey",
+    "chart-scatter-bubble",
+    "chart-slope",
+    "chart-sparkline",
+    "chart-stacked-bar-100",
+    "chart-stream",
+    "chart-sunburst",
+    "chart-timeline-lanes",
+    "chart-treemap",
+    "chart-violin",
+    "chart-waterfall",
+    "chart-wordcloud",
+    "gauge-arc",
+    "gauge-ring",
+    "grouped-summary-table",
+    "kpi-stat-card",
+    "kpi-stat-tile-compact",
+    "load-older-paginator",
+    "log-table",
+    "metric-hero",
+    "micro-kpi-subtitle",
+    "mini-table",
+    "period-comparison",
+    "ranked-entity-list",
+    "realtime-feed",
+    "sparkline-table",
+    "stat-pair-card",
+    "timeline-vertical",
+    "top-movers-list",
+    "unread-badge",
+    "usage-meter"
+  ]
+}