@blukavantui/charts-community 0.0.0-stage → 1.2.0

package/src/types.ts

@@ -0,0 +1,104 @@
+/** Shared Web chart contracts; native inputs are normalized by the private adapter. */
+export type ComponentColor = 'Default' | 'Primary' | 'Secondary' | 'Success' | 'Processing' | 'Warning' | 'Error' | 'Danger' | 'Magenta' | 'Red' | 'Volcano' | 'Orange' | 'Gold' | 'Lime' | 'Green' | 'Cyan' | 'Blue' | 'GeekBlue' | 'Purple';
+export type ChartColor = ComponentColor | `#${string}`;
+export type ChartFormat = 'png' | 'svg';
+export type ValueFormat = 'Currency' | 'Number' | 'Percent';
+export type LegendStyle = 'Standard' | 'ValueList' | 'Compact' | 'SummaryCards';
+export type LegendPosition = 'Top' | 'Left' | 'Right' | 'Bottom';
+export interface ChartIdentity { Key: string; Label: string; Color?: ChartColor }
+export interface ChartDatum extends ChartIdentity { Value: number | null }
+export interface ChartCategory extends ChartIdentity {}
+export interface ChartOptions {
+  Title?: string;
+  Description?: string;
+  /** Plot height in pixels, excluding title, toolbar and data table. */
+  Height?: number;
+  ValueFormat?: ValueFormat;
+  CurrencyCode?: string;
+  Locale?: string;
+  UseCustomPrecision?: boolean;
+  /** Display precision only; the data alternative retains the original values. */
+  DecimalPlaces?: number;
+  AccessibleLabel?: string;
+  ExtendedClass?: string;
+  /** Change to reset map/treemap view state. */
+  ResetKey?: string;
+  /** Plain-text replacements for shared controls and announcements. */
+  Messages?: Record<string, string>;
+  ShowHeader?: boolean;
+  ShowToolbar?: boolean;
+  ShowLegend?: boolean;
+  LegendStyle?: LegendStyle;
+  LegendPosition?: LegendPosition;
+  LegendShowValues?: boolean;
+  /** Percentages only appear for meaningful partitions, separately for each nested ring. */
+  LegendShowPercentages?: boolean;
+  ShowTooltip?: boolean;
+  ShowLabels?: boolean;
+  ShowDataTable?: boolean;
+  /** Optional fill textures. Off by default; exact-value data remains available. */
+  ShowPatterns?: boolean;
+  EnableSelection?: boolean;
+  EnableAnimation?: boolean;
+  IsLoading?: boolean;
+  EmptyMessage?: string;
+  SelectedKey?: string | null;
+  ExportFootnote?: string;
+}
+export interface MixedSeries {
+  Key: string;
+  Name: string;
+  Type: 'Bar' | 'Line';
+  /** One value per category. null means missing; zero is a real value. */
+  Values: (number | null)[];
+  /** Shared BluKavant ComponentColor or a custom hex color. */
+  Color?: ChartColor;
+  IsDashed?: boolean;
+}
+export interface MixedChartOptions extends ChartOptions {
+  Categories: ChartCategory[];
+  Series: MixedSeries[];
+  BarLayout?: 'Stacked' | 'Grouped';
+  SmoothLines?: boolean;
+}
+export interface HeatmapCell {
+  Key: string;
+  XKey: string;
+  YKey: string;
+  Value: number | null;
+}
+export interface HeatmapOptions extends ChartOptions {
+  XCategories: ChartCategory[];
+  YCategories: ChartCategory[];
+  Cells: HeatmapCell[];
+  ColorScale?: ComponentColor | 'Automatic' | 'Teal' | 'Diverging';
+  MinValue?: number;
+  MaxValue?: number;
+}
+export interface MixedPoint {
+  Key: string; CategoryLabel: string; SeriesKey: string; SeriesName: string; Value: number | null;
+}
+export interface HeatmapPoint extends HeatmapCell { XLabel: string; YLabel: string }
+export interface ChartEvents<Point> {
+  PointClick?: (point: Point, origin?: 'Chart' | 'Table') => void;
+  SelectionChange?: (selection: { Key: string | null; Reason?: 'User' | 'DataChanged' }) => void;
+  Ready?: () => void;
+  StateChange?: (state: { State: 'Loading' | 'Ready' | 'Empty' | 'Error'; Revision: number }) => void;
+  PatternsChange?: (state: { ShowPatterns: boolean }) => void;
+  ExportStarted?: (result: { Format: ChartFormat; FileName: string; RequestId: string }) => void;
+  /** @deprecated Use ExportStarted. Completion means download initiated, not file saved. */
+  ExportComplete?: (result: { Format: ChartFormat; FileName: string }) => void;
+  Error?: (error: { Message: string; Code?: string; RequestId?: string }) => void;
+}
+export interface ChartInstance<Options> {
+  update(options: Partial<Options>): void;
+  resize(): void;
+  /** Silent application-controlled selection. Does not emit SelectionChange. */
+  setSelection(key: string | null): void;
+  /** Transient emphasis, useful for Grid row hover/click. */
+  highlight(key: string | null): void;
+  /** PNG defaults to 2× the plot resolution. Initiates a browser download. */
+  download(format?: ChartFormat, filename?: string, requestId?: string): Promise<void>;
+  /** Idempotent. Releases observers, events and the ECharts instance. */
+  destroy(): void;
+}

package/src/validation.ts

@@ -0,0 +1,75 @@
+import type { ChartCategory, ChartOptions, MixedChartOptions, HeatmapOptions } from './types.ts';
+import { isChartColor, isComponentColor } from './colors.ts';
+import { boundedList, boundedText, safeNumber, limits } from './limits.ts';
+
+export function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+export function categories(items: ChartCategory[], name: string) {
+  boundedList(items, name);
+  const keys = new Set<string>();
+  for (const item of items) {
+    assert(item && boundedText(item.Key) && item.Key.length > 0 && boundedText(item.Label), `${name} require a non-empty Key and a Label within the text limit.`);
+    assert(!keys.has(item.Key), `${name} contain a duplicate key: ${item.Key}.`);
+    keys.add(item.Key);
+  }
+  return keys;
+}
+export function value(value: unknown) { return value === null || safeNumber(value); }
+export function base(options: ChartOptions) {
+  assert(options.Height === undefined || (Number.isFinite(options.Height) && options.Height >= 160 && options.Height <= 1000), 'Height must be between 160 and 1000 pixels.');
+  assert(options.ValueFormat === undefined || ['Currency', 'Number', 'Percent'].includes(options.ValueFormat), 'Invalid ValueFormat.');
+  for (const key of ['UseCustomPrecision','ShowHeader', 'ShowToolbar', 'ShowLegend', 'LegendShowValues', 'LegendShowPercentages', 'ShowTooltip', 'ShowLabels', 'ShowDataTable', 'ShowPatterns', 'EnableSelection', 'EnableAnimation', 'IsLoading'] as const) {
+    assert(options[key] === undefined || typeof options[key] === 'boolean', `${key} must be a boolean.`);
+  }
+  for (const key of ['AccessibleLabel','ExtendedClass','ResetKey','Title', 'Description', 'EmptyMessage', 'ExportFootnote', 'Locale', 'CurrencyCode'] as const) {
+    assert(options[key] === undefined || boundedText(options[key]), `${key} must be text within the text limit.`);
+  }
+  assert(options.LegendStyle === undefined || ['Standard', 'ValueList', 'Compact', 'SummaryCards'].includes(options.LegendStyle), 'Invalid LegendStyle.');
+  assert(options.LegendPosition === undefined || ['Top', 'Left', 'Right', 'Bottom'].includes(options.LegendPosition), 'Invalid LegendPosition.');
+  assert(options.DecimalPlaces === undefined || Number.isInteger(options.DecimalPlaces) && options.DecimalPlaces >= 0 && options.DecimalPlaces <= 12, 'DecimalPlaces must be an integer from 0 to 12.');
+  assert(options.Messages === undefined || !!options.Messages && typeof options.Messages === 'object' && !Array.isArray(options.Messages) && Object.keys(options.Messages).length <= 100 && Object.values(options.Messages).every(boundedText), 'Messages must contain plain text translations.');
+  new Intl.NumberFormat(options.Locale || 'en-US', options.ValueFormat === 'Currency' ? {style:'currency',currency:options.CurrencyCode || 'USD'} : {});
+}
+export function validateMixed(options: MixedChartOptions) {
+  base(options);
+  const keys = categories(options.Categories, 'Categories');
+  assert(options.SelectedKey == null || keys.has(options.SelectedKey), 'SelectedKey must match a category.');
+  assert(options.BarLayout === undefined || ['Stacked', 'Grouped'].includes(options.BarLayout), 'Invalid BarLayout.');
+  assert(options.SmoothLines === undefined || typeof options.SmoothLines === 'boolean', 'SmoothLines must be a boolean.');
+  boundedList(options.Series, 'Series');
+  assert(options.Categories.length * options.Series.length <= limits.observations, 'Too many chart observations. Aggregate the data first.');
+  const seriesKeys = new Set<string>();
+  for (const series of options.Series) {
+    assert(series && boundedText(series.Key) && series.Key.length && !seriesKeys.has(series.Key), 'Each series needs a unique, non-empty Key.');
+    seriesKeys.add(series.Key);
+    assert(boundedText(series.Name) && ['Bar', 'Line'].includes(series.Type), 'Each series needs a Name and a Bar or Line Type.');
+    assert(Array.isArray(series.Values) && series.Values.length === options.Categories.length, `${series.Key}: Values must match the category count.`);
+    assert(series.Values.every(value), `${series.Key}: Values must be finite numbers or null.`);
+    assert(series.Color === undefined || isChartColor(series.Color), 'Series Color must be a ComponentColor or hex color.');
+    assert(series.IsDashed === undefined || typeof series.IsDashed === 'boolean', 'IsDashed must be a boolean.');
+  }
+}
+export function validateHeatmap(options: HeatmapOptions) {
+  base(options);
+  const x = categories(options.XCategories, 'XCategories'), y = categories(options.YCategories, 'YCategories');
+  boundedList(options.Cells, 'Cells');
+  assert(x.size * y.size <= limits.observations, 'Too many heatmap positions. Aggregate the data first.');
+  const keys = new Set<string>(), positions = new Set<string>();
+  for (const cell of options.Cells) {
+    assert(cell && typeof cell.Key === 'string' && cell.Key.length && !keys.has(cell.Key), 'Each cell needs a unique, non-empty Key.');
+    assert(x.has(cell.XKey) && y.has(cell.YKey), `${cell.Key}: XKey and YKey must match category keys.`);
+    const position = JSON.stringify([cell.XKey, cell.YKey]);
+    assert(!positions.has(position), 'Only one cell may occupy each X/Y position.');
+    assert(value(cell.Value), `${cell.Key}: Value must be a finite number or null.`);
+    positions.add(position); keys.add(cell.Key);
+  }
+  assert(options.SelectedKey == null || keys.has(options.SelectedKey), 'SelectedKey must match a cell.');
+  assert(options.ColorScale === undefined || (isComponentColor(options.ColorScale) || ['Automatic', 'Teal', 'Diverging'].includes(options.ColorScale)), 'Invalid ColorScale.');
+  assert(options.MinValue === undefined || Number.isFinite(options.MinValue), 'MinValue must be finite.');
+  assert(options.MaxValue === undefined || Number.isFinite(options.MaxValue), 'MaxValue must be finite.');
+  assert(options.MinValue === undefined || options.MaxValue === undefined || options.MinValue < options.MaxValue, 'MinValue must be less than MaxValue.');
+}
+export function escapeText(text: string): string {
+  return text.replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[char]!));
+}

package/src/web-motion-sparkline.ts

@@ -0,0 +1,37 @@
+/** Local opt-in adapter. The compact SVG runtime and its ordinary defaults stay intact. */
+import { createSparkline, type SparklineOptions, type SparklineEvents } from './sparkline.ts';
+import { validateSparkline } from './sparkline-validation.ts';
+import type { ChartPresentation } from './catalogue-runtime.ts';
+export function createMotionSparkline(host: HTMLElement, options: SparklineOptions, events: SparklineEvents, policy: ChartPresentation) {
+  let requested = structuredClone(options), dead = false, paused = false;
+  const effective = () => {
+    if(policy.enabled?.()===false)return {...requested};
+    const animation=requested.Animation??(requested.AnimateGlow===false?'Off':'Once');
+    return {...requested,Animation:policy.mode(host)!=='full'||(animation==='Once'&&policy.timing?.().duration===0)?'Off':animation} as SparklineOptions;
+  };
+  function finiteTiming() {
+    if(policy.enabled?.()===false||effective().Animation!=='Once')return; // Continuous glow keeps its own cadence and Pause control.
+    const timing=policy.timing?.();
+    for(const element of instance.element.querySelectorAll('animateMotion')){
+      if(timing?.duration!==undefined)element.setAttribute('dur',timing.duration/1000+'s');
+      const curve=timing?.curve?.match(/^cubic-bezier\((.+)\)$/)?.[1];
+      if(curve){element.setAttribute('calcMode','spline');element.setAttribute('keyTimes','0;1');element.setAttribute('keySplines',curve.split(',').map(v=>Math.max(0,Math.min(1,Number(v)))).join(' '));}
+      else if(timing?.curve==='linear')element.setAttribute('calcMode','linear');
+    }
+  }
+  const instance = createSparkline(host, effective(), events), update = instance.update, destroy = instance.destroy;
+  const pauseState = (event: Event) => { if (!(event.target instanceof Element) || !event.target.closest('.blu-sparkline__pause')) return; const svg = instance.element.querySelector('svg'); if (svg?.animationsPaused) paused = svg.animationsPaused(); };
+  // Preserve the user's Pause choice across scope changes and recreated SVGs.
+  instance.element.addEventListener('click', pauseState);
+  const restorePause = () => { const svg = instance.element.querySelector('svg'); if (paused && svg?.animationsPaused && !svg.animationsPaused()) instance.element.querySelector<HTMLButtonElement>('.blu-sparkline__pause')?.click(); };
+  finiteTiming();
+  const stop = policy.subscribe(host, () => { update(effective()); finiteTiming(); restorePause(); });
+  instance.update = patch => {
+    if (dead) throw Error('Component is destroyed.');
+    const next = { ...requested, ...structuredClone(patch) }; validateSparkline(next);
+    if (patch.Animation !== undefined && patch.Animation !== requested.Animation) paused = false;
+    requested = next; update(effective()); finiteTiming(); restorePause();
+  };
+  instance.destroy = () => { if (dead) return; dead = true; stop(); instance.element.removeEventListener('click', pauseState); destroy(); };
+  return instance;
+}