@r0hitsharma/dashboard-kit 0.12.0-rohit-fork-ci.1

package/src/schema.ts

@@ -0,0 +1,148 @@
+/**
+ * `@r0hitsharma/dashboard-kit` — the generic, manifest-driven dashboard
+ * engine.
+ *
+ * Three concerns stay SEPARABLE rather than conflated the way Grafana (flat,
+ * absolute `gridPos` + string-interpolated query blobs) or Superset (three
+ * disconnected config blobs) do:
+ *
+ *   1. `layout`  — a recursive composition tree (Vega-Lite `hconcat`/
+ *      `vconcat` style), independent of what each leaf renders.
+ *   2. `widgets` — a flat, id-keyed registry of widget nodes (`{component,
+ *      props, dataBinding}`), each resolved through a string -> component
+ *      registry key (see `registry.tsx`).
+ *   3. `dataBinding` — a typed `{source, fields}` pointer at a data source,
+ *      uniform across whatever transport a consuming app resolves `source`
+ *      ids against (live tail, replay cursor, a REST poll, ...).
+ *
+ * The one addition none of Grafana/Superset/Perspective/Vega-Lite model as
+ * part of the *widget* node itself is `interaction.reads`/`writes`: the
+ * shared-selection keys a widget consumes or produces. Declaring it here
+ * makes cross-filtering a declared, auditable property of the manifest
+ * instead of implicit wiring buried in component code — see `interaction.ts`
+ * for how those keys reach a real interaction store.
+ */
+
+export type LayoutDirection = 'row' | 'column';
+
+/** A recursive split node — maps onto the design-system's `SplitLayout` orientation. */
+export type SplitLayoutNode = {
+  type: 'split';
+  direction: LayoutDirection;
+  /** Relative share of the parent split's main axis; children need not sum to 1. */
+  size?: number;
+  /**
+   * Render this split as a DRAG-RESIZABLE panel group (design-system's
+   * `SplitLayout`, itself an Ark `Splitter`) instead of a plain flex box,
+   * with one panel per child and a resize handle between each pair. N-way by
+   * construction: three children give two handles.
+   *
+   * Opt-in rather than the default, because a `SplitLayout` needs hard panel
+   * sizes and therefore cannot flex-wrap: the non-resizable path keeps the
+   * responsive wrapping some dashboards rely on at narrow widths. A
+   * `direction: 'column'` split additionally needs {@link height}, since a
+   * vertical splitter has no content-driven size to divide.
+   */
+  resizable?: boolean;
+  /** Required for a resizable `column` split: the CSS height to divide. */
+  height?: string;
+  children: LayoutNode[];
+};
+
+/** A leaf that resolves to one entry in the flat `widgets` registry. */
+export type WidgetLayoutNode = {
+  type: 'widget';
+  /** Key into `DashboardSpec['widgets']`. */
+  ref: string;
+  /** Relative share of the parent split's main axis. */
+  size?: number;
+};
+
+export type LayoutNode = SplitLayoutNode | WidgetLayoutNode;
+
+/**
+ * What data source feeds a widget, and how its fields map onto the shape the
+ * component needs — a typed channel-to-field mapping (Vega-Lite style)
+ * rather than an opaque query string. `source` ids are resolved through
+ * whatever {@link DashboardDataSources} table the host app supplies;
+ * `dashboard-kit` itself is agnostic to what backs a source (a mock array, a
+ * live tail, a replay cursor).
+ */
+export type DataBinding = {
+  /** Data-source id, e.g. `"stream:metrics.throughput"`. */
+  source: string;
+  /** Field name mapping: which field of a source record feeds which slot. */
+  fields: Record<string, string>;
+};
+
+/**
+ * Shared-selection keys a widget consumes (`reads`) or produces (`writes`).
+ * Symmetric by design — any widget may read or write any key, no
+ * master/detail hardcoding.
+ */
+export type WidgetInteraction = {
+  reads?: string[];
+  writes?: string[];
+  /**
+   * Per-field AGENT EXPOSURE: which of this widget's interaction keys an
+   * agent (a drive tool, a command bar) may write. **Default-deny**: a key a
+   * human can write through the UI is NOT agent-writable unless it is listed
+   * here.
+   *
+   * This is the manifest's half of the contract; a host app's agent-facing
+   * tools consult {@link collectAgentWritableKeys} and refuse anything
+   * outside it, so the agent surface is a declared, auditable property of
+   * the dashboard rather than "whatever setters happen to be in scope".
+   */
+  agentWritable?: string[];
+};
+
+export type ThresholdSeverity = 'success' | 'warning' | 'critical';
+
+export type ThresholdRule = {
+  op: 'gte' | 'lte' | 'gt' | 'lt' | 'eq';
+  value: number;
+  severity: ThresholdSeverity;
+};
+
+/** One declarative column for a table-rendering widget. */
+export type WidgetTableColumn = {
+  accessorKey: string;
+  header: string;
+  /** How the registry's table adapter should render the cell. */
+  render?: 'text' | 'number' | 'currency' | 'percent' | 'badge' | 'sparkline';
+};
+
+export type WidgetNode = {
+  id: string;
+  /** Component-registry key, e.g. `"panel.stat"` or `"chart.line"`. */
+  component: string;
+  title?: string;
+  /**
+   * Component-specific configuration, passed through to the resolved
+   * component-registry entry. Kept to JSON-serializable shapes (no
+   * functions) so a manifest stays a genuine, inspectable data value —
+   * `columns` for table widgets is the one structured exception.
+   */
+  props?: Record<string, unknown> & { columns?: WidgetTableColumn[] };
+  dataBinding?: DataBinding;
+  interaction?: WidgetInteraction;
+  thresholds?: ThresholdRule[];
+};
+
+export type DashboardSpec = {
+  version: 1;
+  title?: string;
+  layout: LayoutNode;
+  /** Flat registry of widget nodes, referenced by id from `layout`. */
+  widgets: Record<string, WidgetNode>;
+};
+
+/**
+ * Data-source table keyed by `DataBinding['source']` — every source resolves
+ * to an array of plain records; scalar widgets (e.g. a stat tile reading a
+ * gauge) read the last record. A host app owns populating this (from a mock
+ * fixture, a live subscription snapshot, a query result, ...); the engine
+ * only ever reads it.
+ */
+export type DashboardDataSources = Record<string, Record<string, unknown>[]>;

package/src/validate.test.ts

@@ -0,0 +1,257 @@
+import { describe, expect, it } from 'vitest';
+
+import type { DashboardSpec, WidgetNode } from './schema.js';
+import { collectAgentWritableKeys, validateDashboardSpec } from './validate.js';
+
+/**
+ * A minimal, structurally valid spec: one widget placed by a single-widget
+ * layout. Individual tests clone and mutate it to isolate one failure at a
+ * time. Pure logic only — nothing here renders a component (DOM-free, matching
+ * the repo's node-environment test style).
+ */
+// The `widgets.a` intersection records what the fixture guarantees: `widgets`
+// stays an open `Record` (tests add keys like `orphan` to it), while `a` is a
+// known `WidgetNode` rather than the `| undefined` that
+// `noUncheckedIndexedAccess` gives every other lookup.
+function baseSpec(): DashboardSpec & { widgets: { a: WidgetNode } } {
+  return {
+    version: 1,
+    title: 'Sample',
+    layout: { type: 'widget', ref: 'a' },
+    widgets: {
+      a: { id: 'a', component: 'note', props: { text: 'hello' } },
+    },
+  };
+}
+
+describe('validateDashboardSpec — structural', () => {
+  it('accepts a minimal valid spec', () => {
+    const result = validateDashboardSpec(baseSpec());
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.issues).toEqual([]);
+  });
+
+  it('accepts a nested split layout', () => {
+    const spec: DashboardSpec = {
+      version: 1,
+      layout: {
+        type: 'split',
+        direction: 'row',
+        children: [
+          { type: 'widget', ref: 'a' },
+          {
+            type: 'split',
+            direction: 'column',
+            children: [{ type: 'widget', ref: 'b' }],
+          },
+        ],
+      },
+      widgets: {
+        a: { id: 'a', component: 'note' },
+        b: { id: 'b', component: 'stat' },
+      },
+    };
+    expect(validateDashboardSpec(spec).ok).toBe(true);
+  });
+
+  it('rejects a wrong version literal', () => {
+    const spec = { ...baseSpec(), version: 2 } as unknown;
+    const result = validateDashboardSpec(spec);
+    expect(result.ok).toBe(false);
+  });
+
+  it('rejects a malformed layout node (missing type)', () => {
+    const spec = {
+      version: 1,
+      layout: { ref: 'a' },
+      widgets: { a: { id: 'a', component: 'note' } },
+    } as unknown;
+    expect(validateDashboardSpec(spec).ok).toBe(false);
+  });
+
+  it('rejects a bad threshold enum', () => {
+    const spec = baseSpec();
+    spec.widgets.a.thresholds = [
+      // @ts-expect-error — intentionally invalid op for the test
+      { op: 'between', value: 1, severity: 'warning' },
+    ];
+    expect(validateDashboardSpec(spec).ok).toBe(false);
+  });
+});
+
+describe('validateDashboardSpec — referential', () => {
+  it('flags a layout ref with no matching widget', () => {
+    const spec = baseSpec();
+    spec.layout = { type: 'widget', ref: 'missing' };
+    const result = validateDashboardSpec(spec);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.issues.some((i) => i.path === 'layout.ref')).toBe(true);
+      expect(result.issues[0]?.message).toContain('unknown widget');
+    }
+  });
+
+  it('flags an orphaned widget never placed by the layout', () => {
+    const spec = baseSpec();
+    spec.widgets.orphan = { id: 'orphan', component: 'note' };
+    const result = validateDashboardSpec(spec);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.issues.some((i) => i.path === 'widgets.orphan')).toBe(true);
+    }
+  });
+
+  it('flags a widget whose id disagrees with its registry key', () => {
+    const spec = baseSpec();
+    spec.widgets.a.id = 'mismatch';
+    const result = validateDashboardSpec(spec);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.issues.some((i) => i.path === 'widgets.a.id')).toBe(true);
+    }
+  });
+
+  it('flags a resizable column split with no height', () => {
+    const spec: DashboardSpec = {
+      version: 1,
+      layout: {
+        type: 'split',
+        direction: 'column',
+        resizable: true,
+        children: [{ type: 'widget', ref: 'a' }],
+      },
+      widgets: { a: { id: 'a', component: 'note' } },
+    };
+    const result = validateDashboardSpec(spec);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.issues.some((i) => i.path.endsWith('.height'))).toBe(true);
+    }
+  });
+
+  it('accepts a resizable column split that declares a height', () => {
+    const spec: DashboardSpec = {
+      version: 1,
+      layout: {
+        type: 'split',
+        direction: 'column',
+        resizable: true,
+        height: '400px',
+        children: [{ type: 'widget', ref: 'a' }],
+      },
+      widgets: { a: { id: 'a', component: 'note' } },
+    };
+    expect(validateDashboardSpec(spec).ok).toBe(true);
+  });
+
+  it('accepts a resizable ROW split without a height (row divides width)', () => {
+    const spec: DashboardSpec = {
+      version: 1,
+      layout: {
+        type: 'split',
+        direction: 'row',
+        resizable: true,
+        children: [
+          { type: 'widget', ref: 'a' },
+          { type: 'widget', ref: 'b' },
+        ],
+      },
+      widgets: {
+        a: { id: 'a', component: 'note' },
+        b: { id: 'b', component: 'stat' },
+      },
+    };
+    expect(validateDashboardSpec(spec).ok).toBe(true);
+  });
+});
+
+describe('validateDashboardSpec — agentWritable', () => {
+  it('flags an agentWritable key not present in writes', () => {
+    const spec = baseSpec();
+    spec.widgets.a.interaction = {
+      writes: ['highlightedKey'],
+      agentWritable: ['selectedTimeRange'],
+    };
+    const result = validateDashboardSpec(spec);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(
+        result.issues.some(
+          (i) => i.path === 'widgets.a.interaction.agentWritable',
+        ),
+      ).toBe(true);
+    }
+  });
+
+  it('accepts an agentWritable key that is also written', () => {
+    const spec = baseSpec();
+    spec.widgets.a.interaction = {
+      writes: ['highlightedKey'],
+      agentWritable: ['highlightedKey'],
+    };
+    expect(validateDashboardSpec(spec).ok).toBe(true);
+  });
+});
+
+describe('validateDashboardSpec — knownComponents', () => {
+  it('flags a component key outside the provided allow-list', () => {
+    const spec = baseSpec();
+    const result = validateDashboardSpec(spec, {
+      knownComponents: ['stat', 'table'],
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.issues.some((i) => i.path === 'widgets.a.component')).toBe(
+        true,
+      );
+    }
+  });
+
+  it('passes when every component key is known', () => {
+    const spec = baseSpec();
+    expect(validateDashboardSpec(spec, { knownComponents: ['note'] }).ok).toBe(
+      true,
+    );
+  });
+});
+
+describe('collectAgentWritableKeys', () => {
+  it('returns an empty set by default (default-deny)', () => {
+    expect(collectAgentWritableKeys(baseSpec()).size).toBe(0);
+  });
+
+  it('unions agentWritable keys across every widget', () => {
+    const spec: DashboardSpec = {
+      version: 1,
+      layout: {
+        type: 'split',
+        direction: 'row',
+        children: [
+          { type: 'widget', ref: 'a' },
+          { type: 'widget', ref: 'b' },
+        ],
+      },
+      widgets: {
+        a: {
+          id: 'a',
+          component: 'table',
+          interaction: {
+            writes: ['highlightedKey'],
+            agentWritable: ['highlightedKey'],
+          },
+        },
+        b: {
+          id: 'b',
+          component: 'note',
+          interaction: {
+            writes: ['selectedTimeRange'],
+            agentWritable: ['selectedTimeRange'],
+          },
+        },
+      },
+    };
+    expect(collectAgentWritableKeys(spec)).toEqual(
+      new Set(['highlightedKey', 'selectedTimeRange']),
+    );
+  });
+});

package/src/validate.ts

@@ -0,0 +1,233 @@
+/**
+ * Manifest validation — the gate that must land before any "an agent or
+ * command bar submits a manifest patch" feature can trust a `DashboardSpec`.
+ *
+ * Two layers, because zod alone can't catch the interesting failures:
+ *
+ *   1. STRUCTURAL — `dashboardSpecSchema` below. Shape, enums, required
+ *      fields, no malformed widget nodes.
+ *   2. REFERENTIAL — {@link validateDashboardSpec}'s extra passes. Every
+ *      `layout` leaf must name a widget that exists; every widget must be
+ *      reachable from the layout; a resizable `column` split must carry a
+ *      `height`; an `agentWritable` key must actually be writable. These are
+ *      the mistakes an agent-authored patch actually makes, and none of them
+ *      are expressible as a type.
+ *
+ * `zod` deliberately does NOT validate `component` against a registry here:
+ * `schema.ts` is the data contract and a registry is one possible resolution
+ * of it. The renderer degrades gracefully on an unknown component key (it
+ * renders an `UnknownWidget` marker), and coupling the two would make the
+ * schema un-shareable. {@link validateDashboardSpec} takes an optional set of
+ * known component keys for callers who DO want that checked.
+ */
+
+import { z } from 'zod';
+
+import type { DashboardSpec } from './schema.js';
+
+const layoutDirection = z.enum(['row', 'column']);
+
+const widgetLayoutNode = z.object({
+  type: z.literal('widget'),
+  ref: z.string().min(1),
+  size: z.number().positive().optional(),
+});
+
+/**
+ * Recursive by `z.lazy` — a split's children are layout nodes, which may be
+ * splits.
+ */
+const layoutNode: z.ZodType<unknown> = z.lazy(() =>
+  z.union([widgetLayoutNode, splitLayoutNode]),
+);
+
+const splitLayoutNode = z.object({
+  type: z.literal('split'),
+  direction: layoutDirection,
+  size: z.number().positive().optional(),
+  resizable: z.boolean().optional(),
+  height: z.string().min(1).optional(),
+  children: z.array(layoutNode).min(1),
+});
+
+const dataBinding = z.object({
+  source: z.string().min(1),
+  fields: z.record(z.string(), z.string()),
+});
+
+const widgetInteraction = z.object({
+  reads: z.array(z.string().min(1)).optional(),
+  writes: z.array(z.string().min(1)).optional(),
+  agentWritable: z.array(z.string().min(1)).optional(),
+});
+
+const thresholdRule = z.object({
+  op: z.enum(['gte', 'lte', 'gt', 'lt', 'eq']),
+  value: z.number(),
+  severity: z.enum(['success', 'warning', 'critical']),
+});
+
+const widgetTableColumn = z.object({
+  accessorKey: z.string().min(1),
+  header: z.string(),
+  render: z
+    .enum(['text', 'number', 'currency', 'percent', 'badge', 'sparkline'])
+    .optional(),
+});
+
+const widgetNode = z.object({
+  id: z.string().min(1),
+  component: z.string().min(1),
+  title: z.string().optional(),
+  // `props` stays open (it's per-component config) EXCEPT `columns`, which is
+  // structured enough — and mistyped often enough — to be worth checking.
+  props: z
+    .looseObject({ columns: z.array(widgetTableColumn).optional() })
+    .optional(),
+  dataBinding: dataBinding.optional(),
+  interaction: widgetInteraction.optional(),
+  thresholds: z.array(thresholdRule).optional(),
+});
+
+export const dashboardSpecSchema = z.object({
+  version: z.literal(1),
+  title: z.string().optional(),
+  layout: layoutNode,
+  widgets: z.record(z.string(), widgetNode),
+});
+
+export type ManifestIssue = {
+  /** Dotted path into the spec, e.g. `widgets.exposure.component`. */
+  path: string;
+  message: string;
+};
+
+export type ManifestValidation =
+  | { ok: true; spec: DashboardSpec; issues: [] }
+  | { ok: false; issues: ManifestIssue[] };
+
+type RawLayoutNode = {
+  type?: string;
+  ref?: string;
+  direction?: string;
+  resizable?: boolean;
+  height?: string;
+  children?: RawLayoutNode[];
+};
+
+function walkLayout(
+  node: RawLayoutNode,
+  path: string,
+  visit: (node: RawLayoutNode, path: string) => void,
+): void {
+  visit(node, path);
+  node.children?.forEach((child, index) =>
+    walkLayout(child, `${path}.children[${index}]`, visit),
+  );
+}
+
+export type ValidateOptions = {
+  /**
+   * When supplied, every widget's `component` must be one of these keys.
+   * Pass `Object.keys(registry)` to catch a typo'd or hallucinated component
+   * name before it renders as an `UnknownWidget` placeholder.
+   */
+  knownComponents?: Iterable<string>;
+};
+
+/**
+ * Validates a candidate manifest. Never throws — an agent-submitted patch is
+ * untrusted input, and the caller needs the reasons, not a stack trace.
+ */
+export function validateDashboardSpec(
+  candidate: unknown,
+  { knownComponents }: ValidateOptions = {},
+): ManifestValidation {
+  const parsed = dashboardSpecSchema.safeParse(candidate);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      issues: parsed.error.issues.map((issue) => ({
+        path: issue.path.join('.') || '(root)',
+        message: issue.message,
+      })),
+    };
+  }
+
+  const spec = parsed.data as unknown as DashboardSpec;
+  const issues: ManifestIssue[] = [];
+  const known = knownComponents ? new Set(knownComponents) : null;
+
+  // ── Referential pass ────────────────────────────────────────────────────
+  const referenced = new Set<string>();
+  walkLayout(spec.layout as RawLayoutNode, 'layout', (node, path) => {
+    if (node.type === 'widget') {
+      const ref = node.ref as string;
+      referenced.add(ref);
+      if (!(ref in spec.widgets)) {
+        issues.push({
+          path: `${path}.ref`,
+          message: `layout references unknown widget "${ref}" — add it to \`widgets\` or fix the ref`,
+        });
+      }
+      return;
+    }
+    if (node.resizable && node.direction === 'column' && !node.height) {
+      issues.push({
+        path: `${path}.height`,
+        message:
+          'a resizable `column` split needs an explicit `height` — a vertical splitter has no content-driven size to divide',
+      });
+    }
+  });
+
+  for (const [key, widget] of Object.entries(spec.widgets)) {
+    if (widget.id !== key) {
+      issues.push({
+        path: `widgets.${key}.id`,
+        message: `widget id "${widget.id}" does not match its registry key "${key}"`,
+      });
+    }
+    if (!referenced.has(key)) {
+      issues.push({
+        path: `widgets.${key}`,
+        message: `widget "${key}" is never placed by \`layout\` — it will not render`,
+      });
+    }
+    if (known && !known.has(widget.component)) {
+      issues.push({
+        path: `widgets.${key}.component`,
+        message: `unknown component "${widget.component}"`,
+      });
+    }
+    // An agent-writable key that the widget cannot actually write is a policy
+    // that silently does nothing — worth catching at the gate. `writes` is the
+    // set of keys a widget produces; an `agentWritable` key must be one of them.
+    const writes = widget.interaction?.writes ?? [];
+    for (const exposed of widget.interaction?.agentWritable ?? []) {
+      if (!writes.includes(exposed)) {
+        issues.push({
+          path: `widgets.${key}.interaction.agentWritable`,
+          message: `"${exposed}" is marked agent-writable but is not in this widget's \`writes\``,
+        });
+      }
+    }
+  }
+
+  return issues.length > 0
+    ? { ok: false, issues }
+    : { ok: true, spec, issues: [] };
+}
+
+/**
+ * The set of interaction keys an agent is allowed to write, collected across
+ * every widget in the manifest. Default-deny: an empty set means an agent may
+ * read the dashboard but drive nothing.
+ */
+export function collectAgentWritableKeys(spec: DashboardSpec): Set<string> {
+  const keys = new Set<string>();
+  for (const widget of Object.values(spec.widgets)) {
+    for (const key of widget.interaction?.agentWritable ?? []) keys.add(key);
+  }
+  return keys;
+}