pmx-canvas 0.1.26 → 0.1.28

package/src/json-render/charts/tufte-definitions.ts

@@ -0,0 +1,128 @@
+/**
+ * Definitions for the Tufte primitive chart components in ./tufte-components.tsx.
+ *
+ * Kept separate from ./definitions.ts and ./extra-definitions.ts so the
+ * original chart catalogs stay untouched and the merge in ./catalog.ts is the
+ * only contact surface.
+ */
+
+import { z } from 'zod';
+
+export const tufteChartComponentDefinitions = {
+  Sparkline: {
+    props: z.object({
+      title: z.string().nullable(),
+      data: z.array(z.record(z.string(), z.unknown())),
+      valueKey: z.string(),
+      color: z.string().nullable(),
+      fill: z.boolean().nullable(),
+      showEndDot: z.boolean().nullable(),
+      showMinMax: z.boolean().nullable(),
+      showValue: z.boolean().nullable(),
+      height: z.number().nullable(),
+    }),
+    description:
+      'Word-sized sparkline: a single trend line with no axes, grid, or labels. Optional end dot, min/max markers, light area fill, and an inline last value. The canonical Tufte primitive for showing a trajectory in minimal space.',
+    example: {
+      title: 'Latency p95',
+      data: [{ t: 0, ms: 120 }, { t: 1, ms: 138 }, { t: 2, ms: 117 }, { t: 3, ms: 152 }, { t: 4, ms: 109 }],
+      valueKey: 'ms',
+      color: null,
+      fill: true,
+      showEndDot: true,
+      showMinMax: false,
+      showValue: true,
+      height: null,
+    },
+  },
+
+  DotPlot: {
+    props: z.object({
+      title: z.string().nullable(),
+      data: z.array(z.record(z.string(), z.unknown())),
+      labelKey: z.string(),
+      valueKey: z.string(),
+      color: z.string().nullable(),
+      sort: z.enum(['asc', 'desc', 'none']).nullable(),
+      height: z.number().nullable(),
+    }),
+    description:
+      'Cleveland dot plot: categorical labels down the Y axis, one dot per category positioned by value on X. Higher data-ink ratio than a bar chart for ranked comparison. Sorts descending by default.',
+    example: {
+      title: 'Build time by package',
+      data: [
+        { pkg: 'core', seconds: 42 },
+        { pkg: 'client', seconds: 31 },
+        { pkg: 'mcp', seconds: 18 },
+        { pkg: 'cli', seconds: 9 },
+      ],
+      labelKey: 'pkg',
+      valueKey: 'seconds',
+      color: null,
+      sort: 'desc',
+      height: null,
+    },
+  },
+
+  BulletChart: {
+    props: z.object({
+      title: z.string().nullable(),
+      data: z.array(z.record(z.string(), z.unknown())),
+      labelKey: z.string().nullable(),
+      valueKey: z.string(),
+      targetKey: z.string().nullable(),
+      rangesKey: z.string().nullable(),
+      color: z.string().nullable(),
+      height: z.number().nullable(),
+    }),
+    description:
+      "Stephen Few's bullet graph: a measure bar against grayscale qualitative bands with a target tick and per-row scale ticks. Compact KPI-vs-target display. Provide per-row `ranges` (ascending band thresholds) and `target`.",
+    example: {
+      title: 'Quarterly KPIs vs target',
+      data: [
+        { label: 'Revenue', value: 84, target: 90, ranges: [50, 75, 100] },
+        { label: 'NPS', value: 67, target: 60, ranges: [40, 60, 80] },
+        { label: 'Uptime', value: 99, target: 99.9, ranges: [95, 99, 100] },
+      ],
+      labelKey: 'label',
+      valueKey: 'value',
+      targetKey: 'target',
+      rangesKey: 'ranges',
+      color: null,
+      height: null,
+    },
+  },
+
+  Slopegraph: {
+    props: z.object({
+      title: z.string().nullable(),
+      data: z.array(z.record(z.string(), z.unknown())),
+      labelKey: z.string(),
+      beforeKey: z.string(),
+      afterKey: z.string(),
+      beforeLabel: z.string().nullable(),
+      afterLabel: z.string().nullable(),
+      color: z.string().nullable(),
+      colorByDirection: z.boolean().nullable(),
+      height: z.number().nullable(),
+    }),
+    description:
+      "Tufte slopegraph: two value columns (before/after) with a connecting line per category. Lines use one neutral ink by default; set colorByDirection to accent rising lines and mute falling ones. Ideal for paired change across many items.",
+    example: {
+      title: 'Coverage before/after refactor',
+      data: [
+        { module: 'auth', before: 62, after: 81 },
+        { module: 'canvas', before: 74, after: 78 },
+        { module: 'mcp', before: 55, after: 49 },
+      ],
+      labelKey: 'module',
+      beforeKey: 'before',
+      afterKey: 'after',
+      beforeLabel: 'Before',
+      afterLabel: 'After',
+      color: null,
+      colorByDirection: null,
+      height: null,
+    },
+  },
+} as const;

package/src/json-render/directives.ts

@@ -0,0 +1,64 @@
+/**
+ * Custom json-render directives available in PMX Canvas specs.
+ *
+ * Directives let agent specs declare formatting/derivation ($format, $math,
+ * $concat, $count, $truncate, $pluralize, $join) instead of pre-formatting
+ * strings. Registered into the iframe renderer via <JSONUIProvider directives>.
+ */
+import type { DirectiveDefinition } from '@json-render/core';
+import { standardDirectives } from '@json-render/directives';
+
+/**
+ * Directives enabled in the PMX Canvas viewer. `standardDirectives` covers the
+ * seven stateless directives. The $t i18n directive is intentionally omitted —
+ * it is a factory requiring locale config and PMX Canvas has no locale source.
+ */
+export const pmxCanvasDirectives: DirectiveDefinition[] = [...standardDirectives];
+
+/**
+ * The $-prefixed keys the renderer can actually resolve: core built-in bindings
+ * plus the names of the directives registered above. Anything else (e.g. a
+ * hallucinated `$path`) is NOT a valid dynamic expression — to read a value from
+ * state by path the correct binding is `$state`.
+ */
+const KNOWN_DYNAMIC_KEYS = new Set<string>([
+  '$state',
+  '$item',
+  '$index',
+  '$bindState',
+  '$bindItem',
+  '$cond',
+  '$computed',
+  '$template',
+  ...pmxCanvasDirectives.map((directive) => directive.name),
+]);
+
+/**
+ * True when a prop value is a render-time dynamic expression — a directive
+ * (`$format`/`$math`/…) or an existing binding (`$state`/`$item`/`$bindItem`/
+ * `$cond`/`$template`/`$computed`). These objects are resolved inside the
+ * renderer, so the server-side validators must leave them untouched instead of
+ * string-coercing them to `"[object Object]"` or rejecting them as the wrong
+ * primitive type. An object whose only `$`-key is unrecognized (e.g. `$path`)
+ * is NOT dynamic — the renderer has no directive to resolve it.
+ */
+export function isDynamicPropValue(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  return Object.keys(value as Record<string, unknown>).some((key) => KNOWN_DYNAMIC_KEYS.has(key));
+}
+
+/**
+ * Returns the offending key when a prop value looks like a dynamic expression
+ * (it has `$`-prefixed keys) but none of them is a recognized binding or
+ * registered directive — e.g. `{ "$path": "…" }`. Such objects pass a naive
+ * "has a $-key" check yet render as `"[object Object]"` because the renderer has
+ * no directive to resolve them. Returns null for plain values and for genuinely
+ * dynamic expressions.
+ */
+export function findUnknownDirectiveKey(value: unknown): string | null {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return null;
+  const dollarKeys = Object.keys(value as Record<string, unknown>).filter((key) => key.startsWith('$'));
+  if (dollarKeys.length === 0) return null;
+  if (dollarKeys.some((key) => KNOWN_DYNAMIC_KEYS.has(key))) return null;
+  return dollarKeys[0] ?? null;
+}

package/src/json-render/renderer/index.css

@@ -204,12 +204,76 @@ button {
   color: var(--destructive);
 }
 
+.pmx-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  height: 2.25rem;
+  padding: 0.5rem 1rem;
+  border: 1px solid transparent;
+  border-radius: var(--radius);
+  font-size: 0.875rem;
+  font-weight: 500;
+  line-height: 1.25rem;
+  white-space: nowrap;
+  cursor: pointer;
+  transition: background-color 0.15s ease, border-color 0.15s ease, opacity 0.15s ease;
+}
+
+.pmx-button:disabled {
+  pointer-events: none;
+  opacity: 0.5;
+}
+
+.pmx-button--primary {
+  background: var(--primary);
+  color: var(--primary-foreground);
+}
+
+.pmx-button--secondary {
+  background: var(--secondary);
+  color: var(--secondary-foreground);
+}
+
+.pmx-button--destructive,
+.pmx-button--danger {
+  background: var(--destructive);
+  color: var(--destructive-foreground);
+}
+
+.pmx-button--success {
+  background: var(--chart-2);
+  color: var(--primary-foreground);
+}
+
+.pmx-button--outline {
+  border-color: var(--border);
+  background: transparent;
+  color: var(--foreground);
+}
+
+.pmx-button--ghost {
+  background: transparent;
+  color: var(--foreground);
+}
+
+.pmx-button--ghost:hover,
+.pmx-button--outline:hover {
+  background: color-mix(in oklch, var(--foreground) 8%, transparent);
+}
+
 /* -- Chart components -- */
 
 .pmx-chart {
   width: 100%;
   min-width: 280px;
-  overflow-x: auto;
+  /* overflow:visible (not overflow-x:auto) so the chart is NOT its own scroll
+     container. overflow-x:auto makes overflow-y compute to auto too (CSS quirk),
+     which — once a chart fills the viewport — added a second nested scrollbar on
+     top of the iframe document's. Let the single iframe document handle any
+     overflow instead. */
+  overflow: visible;
   padding: 0.5rem 0;
 }
 
@@ -225,6 +289,48 @@ button {
   min-width: 360px;
 }
 
+.pmx-chart--dot-plot,
+.pmx-chart--bullet,
+.pmx-chart--slopegraph {
+  min-width: 320px;
+}
+
+.pmx-chart--sparkline {
+  min-width: 160px;
+  padding: 0.25rem 0;
+}
+
+.pmx-chart__sparkline-row {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.pmx-chart__sparkline-svg {
+  display: block;
+  width: 100%;
+  height: 36px;
+}
+
+.pmx-chart__sparkline-value {
+  font-size: 0.8125rem;
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+.pmx-chart__dot-plot-svg,
+.pmx-chart__bullet-svg,
+.pmx-chart__slopegraph-svg {
+  display: block;
+}
+
+.pmx-chart--dot-plot text,
+.pmx-chart--bullet text,
+.pmx-chart--slopegraph text {
+  font-variant-numeric: tabular-nums;
+}
+
 .pmx-chart__title {
   font-size: 0.875rem;
   font-weight: 600;

package/src/json-render/renderer/index.tsx

@@ -14,6 +14,9 @@ import { shadcnComponents } from '@json-render/shadcn';
 import { catalog } from '../catalog';
 import { chartComponents } from '../charts/components';
 import { extraChartComponents } from '../charts/extra-components';
+import { tufteChartComponents } from '../charts/tufte-components';
+import { pmxCanvasDirectives } from '../directives';
+import { JsonRenderDevtools } from '@json-render/devtools-react';
 
 type BadgeVariant = 'default' | 'secondary' | 'destructive' | 'outline' | 'success' | 'info' | 'warning' | 'error' | 'danger';
 type BadgeProps = {
@@ -36,12 +39,37 @@ function Badge({ props }: { props: BadgeProps }) {
   );
 }
 
+type ButtonVariant = 'primary' | 'secondary' | 'destructive' | 'danger' | 'outline' | 'ghost' | 'success';
+type ButtonProps = {
+  label: string;
+  variant?: ButtonVariant | null;
+  disabled?: boolean | null;
+};
+
+function Button({ props, emit }: { props: ButtonProps; emit: (event: string) => void }) {
+  const resolvedVariant = props.variant ?? 'primary';
+  return (
+    <button
+      type="button"
+      data-slot="button"
+      data-variant={resolvedVariant}
+      className={`pmx-button pmx-button--${resolvedVariant}`}
+      disabled={props.disabled ?? false}
+      onClick={() => emit('press')}
+    >
+      {props.label}
+    </button>
+  );
+}
+
 const { registry } = defineRegistry(catalog as never, {
   components: {
     ...shadcnComponents,
     Badge,
+    Button,
     ...chartComponents,
     ...extraChartComponents,
+    ...tufteChartComponents,
   } as never,
 });
 
@@ -50,6 +78,7 @@ declare global {
     __PMX_CANVAS_JSON_RENDER_SPEC__?: Spec & { state?: Record<string, unknown> };
     __PMX_CANVAS_JSON_RENDER_THEME__?: string;
     __PMX_CANVAS_JSON_RENDER_DISPLAY__?: string;
+    __PMX_CANVAS_JSON_RENDER_DEVTOOLS__?: boolean;
   }
 }
 
@@ -95,8 +124,12 @@ function App() {
       <JSONUIProvider
         registry={registry}
         initialState={spec.state ?? undefined}
+        directives={pmxCanvasDirectives}
       >
         <Renderer spec={spec} registry={registry} loading={false} />
+        {window.__PMX_CANVAS_JSON_RENDER_DEVTOOLS__ ? (
+          <JsonRenderDevtools position="right" />
+        ) : null}
       </JSONUIProvider>
     </div>
   );