@taylorwong/ichartjs 2.0.12 → 2.0.14

package/src/spec.mjs

@@ -60,6 +60,40 @@ function dependencyErrors(rows) {
   return errors;
 }
 
+function isIsoDate(value) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/.test(value)) return false;
+  return !Number.isNaN(Date.parse(value));
+}
+
+function projectRowErrors(type, rows) {
+  const errors = [], ids = new Map(), requiresId = ['gantt', 'timeline', 'milestone'].includes(type);
+  rows.forEach((row, index) => {
+    const path = `data.values[${index}]`;
+    if (!row || typeof row !== 'object' || Array.isArray(row)) {
+      errors.push({ code: 'INVALID_PROJECT_ROW', path, message: `${type} rows must be objects.`, suggestion: 'Provide one JSON object per project record.' });
+      return;
+    }
+    if (requiresId && (typeof row.id !== 'string' || !row.id.trim())) errors.push({ code: 'MISSING_RECORD_ID', path: `${path}.id`, message: `${type} rows require a stable string id.`, suggestion: 'Add a unique id to every project record so edits and lineage remain stable.' });
+    if (typeof row.id === 'string' && row.id.trim()) {
+      if (ids.has(row.id)) errors.push({ code: 'DUPLICATE_RECORD_ID', path: `${path}.id`, message: `Record id ${row.id} is duplicated.`, suggestion: 'Use a unique stable id for every project record.' });
+      ids.set(row.id, index);
+    }
+    if (type === 'gantt') {
+      for (const key of ['start', 'end']) {
+        if (!isIsoDate(row[key])) errors.push({ code: 'MISSING_REQUIRED_DATE', path: `${path}.${key}`, message: `Gantt rows require a valid ISO ${key} date.`, suggestion: `Use ${key}: "2026-09-14" or an explicit ISO timestamp.` });
+      }
+      if (isIsoDate(row.start) && isIsoDate(row.end) && Date.parse(row.end) < Date.parse(row.start)) errors.push({ code: 'INVALID_INTERVAL', path, message: 'Gantt end must not precede start.', suggestion: 'Set end to the same day or a later ISO date.' });
+    } else if (['timeline', 'milestone'].includes(type)) {
+      if (!isIsoDate(row.date)) errors.push({ code: 'MISSING_REQUIRED_DATE', path: `${path}.date`, message: `${type} rows require a valid ISO date.`, suggestion: 'Use date: "2026-09-14" or an explicit ISO timestamp.' });
+      if (typeof (row.title ?? row.name ?? row.label) !== 'string' || !(row.title ?? row.name ?? row.label).trim()) errors.push({ code: 'MISSING_RECORD_LABEL', path: `${path}.title`, message: `${type} rows require a title, name, or label.`, suggestion: 'Add a human-readable title for the project record.' });
+    } else if (type === 'burndown') {
+      if (!isIsoDate(row.date)) errors.push({ code: 'MISSING_REQUIRED_DATE', path: `${path}.date`, message: 'burndown rows require a valid ISO date.', suggestion: 'Use date: "2026-09-14" or an explicit ISO timestamp.' });
+      if (!Number.isFinite(Number(row.remaining)) || Number(row.remaining) < 0) errors.push({ code: 'INVALID_REMAINING', path: `${path}.remaining`, message: 'Burndown remaining must be a non-negative finite number.', suggestion: 'Provide remaining: 0 or a positive numeric value.' });
+    }
+  });
+  return errors;
+}
+
 const encodingChannels = {
   line: ['x', 'y'], area: ['x', 'y'], bar: ['x', 'y'], column: ['x', 'y'], scatter: ['x', 'y'],
   pie: ['category', 'value'], funnel: ['category', 'value'], gauge: ['value'], heatmap: ['x', 'y', 'color'], radar: [],
@@ -188,10 +222,18 @@ export function validateSpec(input = {}) {
     const diagramValidation = validateDiagram(diagramInput);
     diagramValidation.errors.forEach(error => errors.push({ ...error, path: error.path || 'diagram' }));
   }
-  if (['gantt', 'timeline', 'milestone'].includes(spec.type)) {
+  if (['gantt', 'timeline', 'milestone', 'burndown'].includes(spec.type)) {
     const rows = spec.data.values, dateKey = spec.type === 'gantt' ? 'start/end' : 'date';
-    if (!rows.some(row => row.start || row.end || row.date)) errors.push({ code: 'INVALID_INTERVALS', path: 'data.values', message: `${spec.type} rows require ${dateKey} dates.`, suggestion: 'Add ISO date values to each row.' });
-    rows.forEach((row, index) => { const values = spec.type === 'gantt' ? [row.start, row.end] : [row.date]; if (values.some(value => value != null && Number.isNaN(Date.parse(value)))) errors.push({ code: 'INVALID_DATE', path: `data.values[${index}]`, message: `${spec.type} contains an invalid date.`, suggestion: 'Use an ISO-8601 date such as 2026-09-14.' }); });
+    if (!rows.some(row => row && (row.start || row.end || row.date))) errors.push({ code: 'INVALID_INTERVALS', path: 'data.values', message: `${spec.type} rows require ${dateKey} dates.`, suggestion: 'Add ISO date values to each row.' });
+    errors.push(...projectRowErrors(spec.type, rows));
+    if (spec.type === 'burndown') {
+      const seenDates = new Set(), validDates = rows.map(row => row?.date).filter(isIsoDate);
+      validDates.forEach((date, index) => {
+        if (seenDates.has(date)) warnings.push({ code: 'DUPLICATE_DATE', severity: 'warning', path: 'data.values', message: `Burndown contains duplicate date ${date}; input order is preserved.`, suggestion: 'Aggregate duplicate dates before rendering for one sample per day.' });
+        seenDates.add(date);
+        if (index && Date.parse(date) < Date.parse(validDates[index - 1])) warnings.push({ code: 'OUT_OF_ORDER_DATE', severity: 'warning', path: 'data.values', message: 'Burndown dates are not sorted; input order is preserved.', suggestion: 'Sort samples by date before creating the chart.' });
+      });
+    }
   }
   if (spec.type === 'gantt') errors.push(...dependencyErrors(spec.data.values));
   const rows = Array.isArray(spec.data?.values) ? spec.data.values : [];

package/types/consumer-fixture.ts

@@ -0,0 +1,35 @@
+import {
+  ChartValidationError,
+  Chart,
+  ChartSpec,
+  createChart,
+  getCapabilities,
+  getBusinessSchema,
+  type ChartEvent,
+  type EditCommand,
+  type LinkedFilters
+} from '@taylorwong/ichartjs';
+
+declare const spec: ChartSpec;
+declare const command: EditCommand;
+declare const filters: LinkedFilters;
+
+const chart: Chart = createChart({ ...spec, type: spec.type || 'line', data: [{ id: 'row-1', name: 'A', value: 1 }] });
+const listener = (event: ChartEvent) => event.chart.getState().revision;
+chart.on('render', listener).off('render', listener);
+chart.update({ labels: { enabled: true } }).setData([{ id: 'row-2', name: 'B', value: 2 }]);
+chart.setLinkedFilters(filters).setLinkedSelection(['row-2']);
+chart.getDiagramNodes();
+chart.getDiagramEdges();
+chart.getClipboard();
+chart.export({ type: 'json', as: 'object' });
+chart.export({ type: 'svg', as: 'string' });
+chart.export({ type: 'png', as: 'dataurl' });
+chart.export({ type: 'jpeg', as: 'blob' });
+chart.previewEdit(command);
+chart.validateData();
+getCapabilities().contractVersion;
+getBusinessSchema('mindmap-edge');
+try { chart.update({ width: 0 }); } catch (error) { if (!(error instanceof ChartValidationError)) throw error; }
+chart.destroy();
+chart.destroy();

package/types/index.d.ts

@@ -21,10 +21,11 @@ export interface PreferencesStorage { getItem(key: string): string | null; setIt
 export interface StyleRecommendation { version: '1.0'; preset: Exclude<ThemePreset, 'auto'>; mode: ThemeMode; resolvedMode: Exclude<ThemeMode, 'auto'>; palette: Exclude<ThemePalette, 'auto'>; reasons: string[]; warnings: Diagnostic[]; userOverride: boolean; }
 export interface ResolvedTheme extends ThemeConfig { name: string; resolvedMode: Exclude<ThemeMode, 'auto'>; background: string; surface: string; text: string; muted: string; axis: string; grid: string; border: string; focus: string; selection: string; colors: string[]; palettes: Record<string, unknown>; status: Record<string, string>; typography: Record<string, { size: number; weight: number; lineHeight: number; font: string }>; layout: Record<string, unknown>; marks: Record<string, unknown>; reasons: string[]; warnings: Diagnostic[]; }
 export interface Diagnostic { code: string; path?: string; message: string; expected?: unknown; suggestion?: string; [key: string]: unknown; }
+export class ChartValidationError extends Error { name: 'ChartValidationError'; code: 'CHART_VALIDATION_FAILED'; operation: string; details: Diagnostic[]; errors: Diagnostic[]; path?: string; expected?: unknown; received?: unknown; suggestion?: string; toJSON(): Record<string, unknown>; }
 export interface DataFieldInfo { name: string; type: 'quantitative' | 'temporal' | 'category' | 'unknown'; role: 'identifier' | 'measure' | 'temporal-dimension' | 'dimension'; unit: string | null; cardinality: number; validCount: number; nullCount: number; min?: number; max?: number; temporalMin?: string; temporalMax?: string; }
 export interface DataInspection { version: '1.0'; rows: number; fields: DataFieldInfo[]; dimensions: string[]; measures: string[]; temporalFields: string[]; missingValueCount: number; warnings: Diagnostic[]; }
 export interface ChartCapability { type: ChartType; family: string; intents: string[]; required: string[]; optional: string[]; dataShapes: string[]; interactions: string[]; features: Record<string, 'supported' | 'not-applicable' | 'degraded'>; renderers: Array<'canvas' | 'svg'>; exports: string[]; limits: Record<string, number>; }
-export interface RuntimeCapabilities { version: '2.0'; contractVersion: '1.0'; chartTypes: ChartType[]; charts: Record<ChartType, ChartCapability>; intents: string[]; locale?: { default: string; recommended: string[]; appliesTo: string[]; inputDates: string }; renderers: Array<'canvas' | 'svg'>; interactions: string[]; exports: Array<'png' | 'svg' | 'json' | 'jpeg'>; styleSystem: { modes: ThemeMode[]; presets: ThemePreset[]; palettes: ThemePalette[]; switchable: boolean; automatic: boolean; [key: string]: unknown }; preferences?: { version: '1.0'; scopes: string[]; persistence: string[]; fields: string[]; agentAdjustable: boolean; interactiveSettingsUI: boolean; precedence: string[]; schema: PreferenceCapabilities }; headless: { preview?: boolean; json: boolean; svg: boolean; png: boolean | string }; export: { types: string[]; mime: Record<string, string>; browser: Record<string, boolean>; headless: Record<string, string | boolean>; methods: string[]; options: Record<string, unknown>; branding: Record<string, unknown> }; branding: { defaultEnabled: boolean; signature: string; options: Record<string, unknown> }; [key: string]: unknown; }
+export interface RuntimeCapabilities { version: '2.0'; contractVersion: '1.1'; chartTypes: ChartType[]; charts: Record<ChartType, ChartCapability>; intents: string[]; locale?: { default: string; recommended: string[]; appliesTo: string[]; inputDates: string }; renderers: Array<'canvas' | 'svg'>; interactions: string[]; exports: Array<'png' | 'svg' | 'json' | 'jpeg'>; styleSystem: { modes: ThemeMode[]; presets: ThemePreset[]; palettes: ThemePalette[]; switchable: boolean; automatic: boolean; [key: string]: unknown }; preferences?: { version: '1.0'; scopes: string[]; persistence: string[]; fields: string[]; agentAdjustable: boolean; interactiveSettingsUI: boolean; precedence: string[]; schema: PreferenceCapabilities }; headless: { preview?: boolean; json: boolean; svg: boolean; png: boolean | string }; export: { types: string[]; mime: Record<string, string>; browser: Record<string, boolean>; headless: Record<string, string | boolean>; methods: string[]; options: Record<string, unknown>; branding: Record<string, unknown> }; branding: { defaultEnabled: boolean; signature: string; options: Record<string, unknown> }; [key: string]: unknown; }
 export interface ChartPlan { version: '1.0'; intent: string; intentKnown?: boolean; intentSuggestions?: string[]; fallbackUsed?: boolean; primary: ChartType; alternatives: ChartType[]; confidence: number; reasons: string[]; requiredFields: string[]; suggestedEncodings: { dimension: string | null; measure: string | null; secondaryMeasure: string | null }; assumptions: string[]; warnings: Diagnostic[]; unsupportedRequests: string[]; nextActions: string[]; capability: ChartCapability; styleRecommendation: StyleRecommendation; data: DataInspection; }
 export interface AxisState { rawDomain: [number, number]; domain: [number, number]; ticks: number[]; step: number | null; policy: 'nice' | 'raw' | 'explicit'; }
 export interface ChartHealth { version: '1.0'; status: 'ready' | 'degraded' | 'empty'; renderable: boolean; issues: string[]; metrics: { warnings: number; suppressedLabels: number; clampedValues: number; renderedMarks: number }; }
@@ -40,6 +41,12 @@ export interface ArchitectureNode extends DiagramNode { layerId?: string; bounda
 export interface MindmapNode extends DiagramNode { parentId?: string; branch?: string; description?: string; }
 export interface DiagramPoint { x: number; y: number; }
 export interface DiagramEdge { id?: string; from: string; to: string; fromPort?: string; toPort?: string; label?: string; relation?: string; routing?: 'straight' | 'orthogonal' | 'curved'; curveTension?: number; waypoints?: DiagramPoint[]; }
+export interface DiagramElement { id?: string; type?: string; dataRef?: Record<string, unknown>; geometry?: Record<string, unknown>; [key: string]: unknown; }
+export interface ChartEvent { chart: Chart; type?: string; target?: DiagramElement | null; datum?: Record<string, unknown>; selectedData?: Array<Record<string, unknown>>; [key: string]: unknown; }
+export type ChartListener = (event: ChartEvent) => void;
+export interface ChartPlugin { name?: string; install?(chart: Chart): void; beforeRender?(chart: Chart, model: Record<string, unknown>): void; afterRender?(chart: Chart, model: Record<string, unknown>): void; destroy?(chart: Chart): void; }
+export interface ClipboardState { nodes: DiagramNode[]; edges: DiagramEdge[]; }
+export interface ChartState { renderer: string; width: number; height: number; dataCount: number; selected: unknown[]; revision: number; history: { undo: number; redo: number }; view: Record<string, unknown> | null; health: ChartHealth; warnings: Diagnostic[]; preferences: ChartPreferences; clipboard: { nodes: number; edges: number }; [key: string]: unknown; }
 export interface DiagramConfig { mode?: 'process' | 'architecture' | 'mindmap'; layout?: 'manual' | 'layered' | 'tree' | 'radial'; routing?: 'straight' | 'orthogonal' | 'curved'; curveTension?: number; grid?: number; snap?: boolean; }
 export interface ArchitectureLayer { id: string; label?: string; }
 export interface ArchitectureBoundary { id: string; label?: string; nodeIds?: string[]; padding?: number; color?: string; }
@@ -87,13 +94,35 @@ export interface Chart {
   downloadSVG(): ReturnType<Chart['download']>;
   downloadJSON(): ReturnType<Chart['download']>;
   destroy(): void;
-  inspectDataSchema(): ReturnType<typeof inspectDataSchema>;
   validateData(): Record<string, unknown>;
   validateEdit(command: EditCommand): Record<string, unknown>;
   previewEdit(command: EditCommand): EditPreview;
   applyEdit(command: EditCommand, options?: { preview?: EditPreview; confirmed?: boolean; approval?: unknown; previewId?: string; expectedRevision?: number; actor?: string; source?: string; reason?: string }): Record<string, unknown>;
   getChangeSet(): Record<string, unknown> | null;
-  getState(): Record<string, unknown> & { axes?: { y?: AxisState; right?: AxisState } | null; health?: ChartHealth; warnings?: Diagnostic[] };
+  getState(): ChartState;
+  on(type: string, listener: ChartListener): this;
+  off(type: string, listener: ChartListener): this;
+  getAccessibleDescription(): string;
+  inspectDataSchema(): Record<string, unknown>;
+  toDataTable(): Array<Record<string, unknown>>;
+  getSelectedData(): Array<Record<string, unknown>>;
+  getElementAt(x: number, y: number): DiagramElement | null;
+  select(target: DiagramElement, options?: { additive?: boolean }): this;
+  selectBox(start: DiagramPoint, end: DiagramPoint): this;
+  getDiagramNodes(): DiagramNode[];
+  getDiagramEdges(): DiagramEdge[];
+  getDiagramGroups(): Array<Record<string, unknown>>;
+  getCollapsedGroupIds(): string[];
+  getClipboard(): ClipboardState;
+  copySelection(): { valid: boolean; clipboard?: ClipboardState; errors?: Diagnostic[] };
+  duplicateSelection(options?: Record<string, unknown>): Record<string, unknown>;
+  pasteSelection(options?: Record<string, unknown>): Record<string, unknown>;
+  connectNodes(connection: DiagramEdge, options?: Record<string, unknown>): Record<string, unknown>;
+  toggleGroupCollapse(groupId: string, options?: Record<string, unknown>): Record<string, unknown>;
+  highlight(target: DiagramElement): this;
+  use(plugin: ChartPlugin): this;
+  /** Advanced JSON-pointer mutation. Prefer update() so the full public contract is explicit. */
+  applyPatch(patches: Array<{ op: 'add' | 'replace' | 'remove'; path: string; value?: unknown }>): this;
   getProjectAnalytics(): ProjectAnalyticsState | null;
   getLinkedState(): LinkedState | null;
   setLinkedFilters(filters: LinkedFilters): this;
@@ -117,6 +146,7 @@ export interface Chart {
 }
 
 export function createChart(spec: ChartSpec): Chart;
+export const iChart: Record<string, unknown> & { version: string; ChartValidationError: typeof ChartValidationError; createChart: typeof createChart };
 export const defaultPreferences: ChartPreferences;
 export function getPreferenceCapabilities(chartType?: ChartType | string | null, options?: { locale?: 'en' | 'zh-CN' | string }): PreferenceCapabilities;
 export function createPreferencesStore(options?: { storage?: 'localStorage' | 'memory' | PreferencesStorage; storageKey?: string; global?: ChartPreferencesPatch; charts?: Record<string, ChartPreferencesPatch> }): PreferencesStore;