create-imagine 0.1.0

package/templates/blank/src/core/manifest.ts

@@ -0,0 +1,134 @@
+export type ProjectId = string;
+export type FigureId = string;
+
+export type FigureSize =
+  | { unit: 'px'; width: number; height: number }
+  | { unit: 'mm'; width: number; height: number; dpi: number };
+
+export type FigureControl =
+  | { kind: 'text'; key: string; label?: string; multiline?: boolean; placeholder?: string }
+  | { kind: 'number'; key: string; label?: string; min?: number; max?: number; step?: number }
+  | { kind: 'boolean'; key: string; label?: string }
+  | { kind: 'select'; key: string; label?: string; options: Array<{ label: string; value: string }> };
+
+export type FigureVariant = {
+  id: string;
+  title?: string;
+  props?: Record<string, unknown>;
+  controls?: FigureControl[];
+  size?: FigureSize;
+  background?: 'white' | 'transparent';
+};
+
+export type FigureManifestItem = {
+  id: FigureId;
+  title: string;
+  moduleKey: string;
+  size: FigureSize;
+  variants: FigureVariant[];
+  controls?: FigureControl[];
+};
+
+export type ProjectExample = {
+  figureId: FigureId;
+  variantId: string;
+  src: string;
+  caption?: string;
+};
+
+export type ProjectDefinition = {
+  id: ProjectId;
+  title: string;
+  description?: string;
+  examples?: ProjectExample[];
+  figures: FigureManifestItem[];
+};
+
+export type PropsFileV1 = {
+  version: 1;
+  overrides: Record<FigureId, Record<string, Record<string, unknown>>>;
+};
+
+export const PROJECT_ID_RE = /^[a-zA-Z0-9_-]+$/;
+
+export function emptyPropsFile(): PropsFileV1 {
+  return { version: 1, overrides: {} };
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+export function validatePropsFileV1(file: unknown): PropsFileV1 {
+  if (!isPlainObject(file)) throw new Error('props file must be an object');
+  if (file.version !== 1) throw new Error('props file version must be 1');
+  if (!isPlainObject(file.overrides)) throw new Error('props file overrides must be an object');
+  return file as PropsFileV1;
+}
+
+function validateSize(size: FigureSize, label: string) {
+  if (size.unit === 'px') {
+    if (size.width <= 0 || size.height <= 0) throw new Error(`${label} size must be positive`);
+    return;
+  }
+  if (size.width <= 0 || size.height <= 0 || size.dpi <= 0) throw new Error(`${label} mm/dpi size must be positive`);
+}
+
+function validateControls(controls: FigureControl[], label: string) {
+  for (const c of controls) {
+    if (!c.key.trim()) throw new Error(`${label} control key must be non-empty`);
+    if (c.kind === 'select') {
+      if (!c.options.length) throw new Error(`${label} select control options must be non-empty`);
+      for (const opt of c.options) {
+        if (!opt.label.trim()) throw new Error(`${label} select option label must be non-empty`);
+        if (!opt.value.trim()) throw new Error(`${label} select option value must be non-empty`);
+      }
+    }
+  }
+}
+
+export function validateFigures(figures: FigureManifestItem[]): void {
+  const seenFigureIds = new Set<string>();
+
+  for (const fig of figures) {
+    if (!fig.id.trim()) throw new Error('Figure id must be non-empty');
+    if (seenFigureIds.has(fig.id)) throw new Error(`Duplicate figure id: ${fig.id}`);
+    seenFigureIds.add(fig.id);
+
+    if (!fig.title.trim()) throw new Error(`Figure ${fig.id} title must be non-empty`);
+    if (!fig.moduleKey.trim()) throw new Error(`Figure ${fig.id} moduleKey must be non-empty`);
+    validateSize(fig.size, `Figure ${fig.id}`);
+    if (fig.controls?.length) validateControls(fig.controls, `Figure ${fig.id}`);
+
+    if (!fig.variants.length) throw new Error(`Figure ${fig.id} must have at least one variant`);
+    const seenVariantIds = new Set<string>();
+    for (const v of fig.variants) {
+      if (!v.id.trim()) throw new Error(`Figure ${fig.id} variant id must be non-empty`);
+      if (seenVariantIds.has(v.id)) throw new Error(`Figure ${fig.id} has duplicate variant id: ${v.id}`);
+      seenVariantIds.add(v.id);
+
+      if (v.size) validateSize(v.size, `Figure ${fig.id}/${v.id}`);
+      if (v.controls?.length) validateControls(v.controls, `Figure ${fig.id}/${v.id}`);
+    }
+  }
+}
+
+export function validateProject(project: ProjectDefinition): void {
+  if (!project.id.trim()) throw new Error('Project id must be non-empty');
+  if (!PROJECT_ID_RE.test(project.id)) throw new Error(`Project id contains invalid characters: ${project.id}`);
+  if (!project.title.trim()) throw new Error(`Project ${project.id} title must be non-empty`);
+
+  validateFigures(project.figures);
+
+  if (project.examples?.length) {
+    const byId = new Map(project.figures.map((f) => [f.id, f]));
+    for (const ex of project.examples) {
+      if (!ex.src.trim()) throw new Error(`Project ${project.id} example src must be non-empty`);
+      const fig = byId.get(ex.figureId);
+      if (!fig) throw new Error(`Project ${project.id} example references unknown figureId: ${ex.figureId}`);
+      const v = fig.variants.find((vv) => vv.id === ex.variantId);
+      if (!v) throw new Error(`Project ${project.id} example references unknown variantId: ${ex.figureId}/${ex.variantId}`);
+    }
+  }
+}
+

package/templates/blank/src/core/props.ts

@@ -0,0 +1,7 @@
+export function mergeProps(
+  defaults: Record<string, unknown> | undefined,
+  overrides: Record<string, unknown> | undefined
+): Record<string, unknown> {
+  return { ...(defaults ?? {}), ...(overrides ?? {}) };
+}
+

package/templates/blank/src/framework/Figure.tsx

@@ -0,0 +1,34 @@
+import type { ReactNode } from 'react';
+import { theme } from './theme';
+
+export type FigureProps = {
+  width: number;
+  height: number;
+  background?: 'white' | 'transparent';
+  viewBox?: string;
+  children: ReactNode;
+  title?: string;
+};
+
+export function Figure({ width, height, background = 'white', viewBox, children, title }: FigureProps) {
+  const vb = viewBox ?? `0 0 ${width} ${height}`;
+
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={width}
+      height={height}
+      viewBox={vb}
+      role="img"
+      aria-label={title}
+      style={{
+        fontFamily: theme.fontFamily,
+        color: theme.colors.text
+      }}
+    >
+      {background === 'white' ? <rect x={0} y={0} width={width} height={height} fill={theme.colors.bg} /> : null}
+      {children}
+    </svg>
+  );
+}
+

package/templates/blank/src/framework/__tests__/sizing.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { mmToPx, pxToMm, resolveSize, MM_PER_INCH } from '../sizing';
+
+describe('sizing', () => {
+  it('converts mm to px at dpi (25.4mm = 1in)', () => {
+    expect(mmToPx(MM_PER_INCH, 100)).toBe(100);
+    expect(mmToPx(MM_PER_INCH / 2, 200)).toBe(100);
+  });
+
+  it('converts px to mm at dpi', () => {
+    expect(pxToMm(300, 300)).toBeCloseTo(MM_PER_INCH, 6);
+  });
+
+  it('resolves px sizes', () => {
+    const r = resolveSize({ unit: 'px', width: 640, height: 480 });
+    expect(r.width).toBe(640);
+    expect(r.height).toBe(480);
+    expect(r.mm).toBeUndefined();
+  });
+
+  it('resolves mm+dpi sizes', () => {
+    const r = resolveSize({ unit: 'mm', width: MM_PER_INCH, height: MM_PER_INCH, dpi: 150 });
+    expect(r.width).toBe(150);
+    expect(r.height).toBe(150);
+    expect(r.mm?.width).toBe(MM_PER_INCH);
+    expect(r.dpi).toBe(150);
+  });
+});
+

package/templates/blank/src/framework/charts/Axes.tsx

@@ -0,0 +1,103 @@
+import type { ReactNode } from 'react';
+import type { ScaleLinear } from 'd3-scale';
+import { theme } from '../theme';
+
+export type TickFormatter = (value: number) => string;
+
+function defaultFormat(value: number) {
+  return String(value);
+}
+
+export function AxisBottom({
+  x,
+  y,
+  scale,
+  tickCount = 5,
+  tickFormat = defaultFormat,
+  label
+}: {
+  x: number;
+  y: number;
+  scale: ScaleLinear<number, number>;
+  tickCount?: number;
+  tickFormat?: TickFormatter;
+  label?: ReactNode;
+}) {
+  const ticks = scale.ticks(tickCount);
+  const [d0, d1] = scale.domain();
+  const x0 = scale(d0);
+  const x1 = scale(d1);
+
+  return (
+    <g transform={`translate(${x}, ${y})`}>
+      <line x1={x0} y1={0} x2={x1} y2={0} stroke={theme.colors.axis} strokeWidth={theme.strokes.normal} />
+      {ticks.map((t) => {
+        const px = scale(t);
+        return (
+          <g key={t} transform={`translate(${px}, 0)`}>
+            <line y2={6} stroke={theme.colors.axis} strokeWidth={theme.strokes.thin} />
+            <text y={18} fontSize={11} fill={theme.colors.text} textAnchor="middle">
+              {tickFormat(t)}
+            </text>
+          </g>
+        );
+      })}
+      {label ? (
+        <text x={(x0 + x1) / 2} y={36} fontSize={12} fill={theme.colors.text} textAnchor="middle">
+          {label}
+        </text>
+      ) : null}
+    </g>
+  );
+}
+
+export function AxisLeft({
+  x,
+  y,
+  scale,
+  tickCount = 5,
+  tickFormat = defaultFormat,
+  label
+}: {
+  x: number;
+  y: number;
+  scale: ScaleLinear<number, number>;
+  tickCount?: number;
+  tickFormat?: TickFormatter;
+  label?: ReactNode;
+}) {
+  const ticks = scale.ticks(tickCount);
+  const [d0, d1] = scale.domain();
+  const y0 = scale(d0);
+  const y1 = scale(d1);
+
+  return (
+    <g transform={`translate(${x}, ${y})`}>
+      <line x1={0} y1={y0} x2={0} y2={y1} stroke={theme.colors.axis} strokeWidth={theme.strokes.normal} />
+      {ticks.map((t) => {
+        const py = scale(t);
+        return (
+          <g key={t} transform={`translate(0, ${py})`}>
+            <line x2={-6} stroke={theme.colors.axis} strokeWidth={theme.strokes.thin} />
+            <text x={-10} y={4} fontSize={11} fill={theme.colors.text} textAnchor="end">
+              {tickFormat(t)}
+            </text>
+          </g>
+        );
+      })}
+      {label ? (
+        <text
+          x={-42}
+          y={(y0 + y1) / 2}
+          fontSize={12}
+          fill={theme.colors.text}
+          textAnchor="middle"
+          transform={`rotate(-90, ${-42}, ${(y0 + y1) / 2})`}
+        >
+          {label}
+        </text>
+      ) : null}
+    </g>
+  );
+}
+

package/templates/blank/src/framework/charts/GridLines.tsx

@@ -0,0 +1,59 @@
+import type { ScaleLinear } from 'd3-scale';
+import { theme } from '../theme';
+
+export function GridLines({
+  x,
+  y,
+  width,
+  height,
+  xScale,
+  yScale,
+  xTicks = 5,
+  yTicks = 5
+}: {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  xScale: ScaleLinear<number, number>;
+  yScale: ScaleLinear<number, number>;
+  xTicks?: number;
+  yTicks?: number;
+}) {
+  const xt = xScale.ticks(xTicks);
+  const yt = yScale.ticks(yTicks);
+
+  return (
+    <g transform={`translate(${x}, ${y})`} opacity={0.9}>
+      {xt.map((t) => {
+        const px = xScale(t);
+        return (
+          <line
+            key={`x-${t}`}
+            x1={px}
+            y1={0}
+            x2={px}
+            y2={height}
+            stroke={theme.colors.grid}
+            strokeWidth={theme.strokes.thin}
+          />
+        );
+      })}
+      {yt.map((t) => {
+        const py = yScale(t);
+        return (
+          <line
+            key={`y-${t}`}
+            x1={0}
+            y1={py}
+            x2={width}
+            y2={py}
+            stroke={theme.colors.grid}
+            strokeWidth={theme.strokes.thin}
+          />
+        );
+      })}
+    </g>
+  );
+}
+

package/templates/blank/src/framework/charts/Legend.tsx

@@ -0,0 +1,31 @@
+import { theme } from '../theme';
+
+export type LegendItem = { label: string; color: string };
+
+export function Legend({
+  x,
+  y,
+  items,
+  fontSize = 12,
+  rowGap = 6
+}: {
+  x: number;
+  y: number;
+  items: LegendItem[];
+  fontSize?: number;
+  rowGap?: number;
+}) {
+  return (
+    <g transform={`translate(${x}, ${y})`}>
+      {items.map((it, i) => (
+        <g key={it.label} transform={`translate(0, ${i * (fontSize + rowGap)})`}>
+          <rect x={0} y={-fontSize + 3} width={12} height={12} fill={it.color} rx={2} />
+          <text x={18} y={0} fontSize={fontSize} fill={theme.colors.text} dominantBaseline="middle">
+            {it.label}
+          </text>
+        </g>
+      ))}
+    </g>
+  );
+}
+

package/templates/blank/src/framework/charts/Series.tsx

@@ -0,0 +1,50 @@
+import type { ScaleLinear } from 'd3-scale';
+import { line as d3Line, curveMonotoneX } from 'd3-shape';
+import type { Point } from './scales';
+import { theme } from '../theme';
+
+export function LineSeries({
+  xScale,
+  yScale,
+  data,
+  stroke = theme.colors.blue,
+  strokeWidth = theme.strokes.thick
+}: {
+  xScale: ScaleLinear<number, number>;
+  yScale: ScaleLinear<number, number>;
+  data: Point[];
+  stroke?: string;
+  strokeWidth?: number;
+}) {
+  const d = d3Line<Point>()
+    .x((p) => xScale(p.x))
+    .y((p) => yScale(p.y))
+    .curve(curveMonotoneX)(data);
+
+  if (!d) return null;
+
+  return <path d={d} fill="none" stroke={stroke} strokeWidth={strokeWidth} />;
+}
+
+export function ScatterSeries({
+  xScale,
+  yScale,
+  data,
+  r = 3,
+  fill = theme.colors.teal
+}: {
+  xScale: ScaleLinear<number, number>;
+  yScale: ScaleLinear<number, number>;
+  data: Point[];
+  r?: number;
+  fill?: string;
+}) {
+  return (
+    <g>
+      {data.map((p, idx) => (
+        <circle key={idx} cx={xScale(p.x)} cy={yScale(p.y)} r={r} fill={fill} />
+      ))}
+    </g>
+  );
+}
+

package/templates/blank/src/framework/charts/scales.ts

@@ -0,0 +1,19 @@
+import { extent } from 'd3-array';
+import { scaleLinear } from 'd3-scale';
+
+export type Point = { x: number; y: number };
+
+export function extentX(points: Point[]): [number, number] {
+  const ex = extent(points, (d) => d.x);
+  return [ex[0] ?? 0, ex[1] ?? 1];
+}
+
+export function extentY(points: Point[]): [number, number] {
+  const ex = extent(points, (d) => d.y);
+  return [ex[0] ?? 0, ex[1] ?? 1];
+}
+
+export function linearScale(domain: [number, number], range: [number, number]) {
+  return scaleLinear(domain, range);
+}
+

package/templates/blank/src/framework/diagrams/primitives.tsx

@@ -0,0 +1,134 @@
+import { useId } from 'react';
+import { theme } from '../theme';
+
+function safeId(id: string) {
+  return id.replace(/[^a-zA-Z0-9_-]/g, '-');
+}
+
+export function Label({
+  x,
+  y,
+  text,
+  fontSize = 13,
+  fill = theme.colors.text,
+  anchor = 'start'
+}: {
+  x: number;
+  y: number;
+  text: string;
+  fontSize?: number;
+  fill?: string;
+  anchor?: 'start' | 'middle' | 'end';
+}) {
+  return (
+    <text x={x} y={y} fontSize={fontSize} fill={fill} textAnchor={anchor} dominantBaseline="middle">
+      {text}
+    </text>
+  );
+}
+
+export function Box({
+  x,
+  y,
+  width,
+  height,
+  rx = theme.radii.md,
+  fill = theme.colors.panel,
+  stroke = theme.colors.axis,
+  strokeWidth = theme.strokes.normal,
+  label
+}: {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  rx?: number;
+  fill?: string;
+  stroke?: string;
+  strokeWidth?: number;
+  label?: string;
+}) {
+  return (
+    <g>
+      <rect x={x} y={y} width={width} height={height} rx={rx} fill={fill} stroke={stroke} strokeWidth={strokeWidth} />
+      {label ? (
+        <text
+          x={x + width / 2}
+          y={y + height / 2}
+          fontSize={13}
+          fill={theme.colors.text}
+          textAnchor="middle"
+          dominantBaseline="middle"
+        >
+          {label}
+        </text>
+      ) : null}
+    </g>
+  );
+}
+
+export function Arrow({
+  x1,
+  y1,
+  x2,
+  y2,
+  stroke = theme.colors.axis,
+  strokeWidth = theme.strokes.thick
+}: {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  stroke?: string;
+  strokeWidth?: number;
+}) {
+  const rid = safeId(useId());
+  const markerId = `im-arrow-${rid}`;
+
+  return (
+    <g>
+      <defs>
+        <marker id={markerId} markerWidth={10} markerHeight={10} refX={9} refY={5} orient="auto">
+          <path d="M 0 0 L 10 5 L 0 10 z" fill={stroke} />
+        </marker>
+      </defs>
+      <line
+        x1={x1}
+        y1={y1}
+        x2={x2}
+        y2={y2}
+        stroke={stroke}
+        strokeWidth={strokeWidth}
+        markerEnd={`url(#${markerId})`}
+      />
+    </g>
+  );
+}
+
+export function Callout({
+  x,
+  y,
+  width,
+  height,
+  text,
+  fill = '#FEF3C7',
+  stroke = '#F59E0B'
+}: {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  text: string;
+  fill?: string;
+  stroke?: string;
+}) {
+  return (
+    <g>
+      <rect x={x} y={y} width={width} height={height} rx={theme.radii.sm} fill={fill} stroke={stroke} />
+      <text x={x + theme.spacing.sm} y={y + height / 2} fontSize={12} fill={theme.colors.text} dominantBaseline="middle">
+        {text}
+      </text>
+    </g>
+  );
+}
+

package/templates/blank/src/framework/layout/PanelGrid.tsx

@@ -0,0 +1,60 @@
+import { Children } from 'react';
+import { theme } from '../theme';
+
+const alphabet = 'abcdefghijklmnopqrstuvwxyz';
+
+function panelLabel(i: number) {
+  return alphabet[i] ? `${alphabet[i]})` : `${i + 1})`;
+}
+
+export function PanelGrid({
+  x,
+  y,
+  width,
+  height,
+  rows,
+  cols,
+  gap = theme.spacing.lg,
+  margin = theme.spacing.lg,
+  showLabels = true,
+  children
+}: {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  rows: number;
+  cols: number;
+  gap?: number;
+  margin?: number;
+  showLabels?: boolean;
+  children: React.ReactNode;
+}) {
+  const items = Children.toArray(children);
+  const innerW = width - 2 * margin - (cols - 1) * gap;
+  const innerH = height - 2 * margin - (rows - 1) * gap;
+  const cellW = innerW / cols;
+  const cellH = innerH / rows;
+
+  return (
+    <g transform={`translate(${x}, ${y})`}>
+      {items.map((child, i) => {
+        const row = Math.floor(i / cols);
+        const col = i % cols;
+        const cx = margin + col * (cellW + gap);
+        const cy = margin + row * (cellH + gap);
+        return (
+          <g key={i} transform={`translate(${cx}, ${cy})`}>
+            {showLabels ? (
+              <text x={0} y={-8} fontSize={12} fill={theme.colors.subtleText} fontWeight={600}>
+                {panelLabel(i)}
+              </text>
+            ) : null}
+            <g>{child}</g>
+          </g>
+        );
+      })}
+    </g>
+  );
+}
+

package/templates/blank/src/framework/math/MathSvg.tsx

@@ -0,0 +1,35 @@
+import { useEffect, useRef } from 'react';
+import { loadMathJax, trackMathTask } from './mathjax';
+
+export function MathSvg({
+  tex,
+  x,
+  y,
+  scale = 1
+}: {
+  tex: string;
+  x: number;
+  y: number;
+  scale?: number;
+}) {
+  const ref = useRef<SVGGElement | null>(null);
+
+  useEffect(() => {
+    const run = async () => {
+      await loadMathJax();
+      if (!ref.current) return;
+
+      const node = await window.MathJax?.tex2svgPromise?.(tex, { display: true });
+      if (!node || !ref.current) return;
+
+      const el = (node as any).querySelector?.('svg') ?? node;
+      ref.current.replaceChildren(el as any);
+      ref.current.setAttribute('data-imagine-math', 'done');
+    };
+
+    const p = run();
+    trackMathTask(p);
+  }, [tex]);
+
+  return <g ref={ref} data-imagine-math="pending" transform={`translate(${x}, ${y}) scale(${scale})`} />;
+}