@blukavantui/charts-community 0.0.0-stage → 1.2.0

package/src/catalogue-types.ts

@@ -0,0 +1,163 @@
+import type { ChartOptions, ChartCategory, ChartColor, ChartIdentity, ChartDatum } from './types.ts';
+export type CatalogueKind = 'line' | 'radar' | 'bar' | 'pie' | 'doughnut' | 'nightingale' | 'polar' | 'scatter' | 'treemap' | 'sankey' | 'funnel' | 'geo-map' | 'calendar-heatmap';
+export interface ValueSeries extends ChartIdentity {
+    Values: (number | null)[];
+}
+export interface CartesianOptions extends ChartOptions {
+    Categories: ChartCategory[];
+    Series: ValueSeries[];
+    Orientation?: 'Vertical' | 'Horizontal';
+    Stacking?: 'None' | 'Stacked' | 'Percent';
+    LineStyle?: 'Straight' | 'Smooth' | 'Step';
+    ShowArea?: boolean;
+    PolarType?: 'Bar' | 'Line';
+}
+/** Per-axis bounds keep comparisons stable as datasets change. */
+export interface RadarCategory extends ChartCategory { Max?: number }
+export interface RadarOptions extends ChartOptions {
+    Categories: RadarCategory[];
+    Series: ValueSeries[];
+    GridShape?: 'Polygon' | 'Circle';
+    SplitNumber?: number;
+    ShowArea?: boolean;
+    ShowAxisBounds?: boolean;
+}
+export interface Slice extends ChartDatum {
+    RingKey?: string;
+}
+export interface Ring extends ChartIdentity {
+}
+export interface CircularOptions extends ChartOptions {
+    Items: Slice[];
+    Rings?: Ring[];
+    Nested?: boolean;
+    Shape?: 'Full' | 'Half';
+    /** Nested inner levels stay inside; the outermost level uses this position. */
+    LabelPosition?: 'Outside' | 'Inside';
+    InnerRadius?: number;
+    RoseMode?: 'Area' | 'Radius';
+    CenterLabel?: string;
+}
+export interface ScatterPoint extends ChartIdentity {
+    X: number;
+    Y: number;
+    Size?: number;
+    Group?: string;
+}
+export interface ScatterOptions extends ChartOptions {
+    Points: ScatterPoint[];
+    Bubble?: boolean;
+    XLabel?: string;
+    YLabel?: string;
+}
+/** Flat parent keys map directly to OutSystems lists. Branch totals are derived from descendant leaves. */
+export interface TreeNode extends ChartDatum {
+    ParentKey: string | null;
+}
+export interface TreemapOptions extends ChartOptions {
+    Nodes: TreeNode[];
+    Drilldown?: boolean;
+}
+export interface FlowNode extends ChartIdentity {
+}
+export interface FlowLink {
+    Key: string;
+    SourceKey: string;
+    TargetKey: string;
+    Value: number;
+}
+export interface SankeyOptions extends ChartOptions {
+    Nodes: FlowNode[];
+    Links: FlowLink[];
+    Orientation?: 'Horizontal' | 'Vertical';
+    NodeAlign?: 'Justify' | 'Left' | 'Right';
+}
+export interface FunnelOptions extends ChartOptions {
+    Items: Slice[];
+    Sort?: 'Input' | 'Descending' | 'Ascending';
+    ShowConversion?: boolean;
+}
+export interface GeoRegion extends ChartDatum {
+}
+export interface GeoLocation extends ChartIdentity {
+    Longitude: number;
+    Latitude: number;
+    Value: number;
+}
+export interface GeoFeature {
+    type: 'Feature';
+    properties: {
+        name: string;
+        label?: string;
+        [key: string]: unknown;
+    };
+    geometry: {
+        type: 'Polygon' | 'MultiPolygon';
+        coordinates: number[][][] | number[][][][];
+    };
+}
+export interface GeoJSON {
+    type: 'FeatureCollection';
+    features: GeoFeature[];
+}
+export interface GeoMapOptions extends ChartOptions {
+    Map?: 'World' | 'US' | 'Custom';
+    GeoJSON?: GeoJSON;
+    /** Custom geometry resource, mutually exclusive with GeoJSON. */
+    MapURL?: string;
+    /** US defaults to Mainland; Full includes all geometry in the bundled asset. */
+    MapView?: 'Mainland' | 'Full';
+    Regions: GeoRegion[];
+    Locations: GeoLocation[];
+    MapMode?: 'Regions' | 'Locations' | 'Combined';
+    Roam?: boolean;
+    ColorScale?: ChartColor | 'Automatic';
+}
+/** Date-only ISO strings avoid time-zone shifts in OutSystems Date values. */
+export interface CalendarDay extends ChartDatum { Date: string }
+export interface CalendarHeatmapOptions extends ChartOptions {
+    Items: CalendarDay[];
+    RangeStart: string;
+    RangeEnd: string;
+    FirstDay?: 'Monday' | 'Sunday';
+    ColorScale?: ChartColor | 'Automatic';
+    ShowMonthLabels?: boolean;
+    ShowDayLabels?: boolean;
+}
+export interface OptionsByKind {
+    'calendar-heatmap': CalendarHeatmapOptions;
+    line: CartesianOptions;
+    radar: RadarOptions;
+    bar: CartesianOptions;
+    polar: CartesianOptions;
+    pie: CircularOptions;
+    doughnut: CircularOptions;
+    nightingale: CircularOptions;
+    scatter: ScatterOptions;
+    treemap: TreemapOptions;
+    sankey: SankeyOptions;
+    funnel: FunnelOptions;
+    'geo-map': GeoMapOptions;
+}
+export type CatalogueOptions = OptionsByKind[CatalogueKind];
+/** Stable scalar payload suitable for JSON serialization or a native OutSystems structure. */
+export interface ChartPoint {
+    Key: string;
+    Label: string;
+    Value: number | null;
+    SeriesKey?: string;
+    CategoryKey?: string;
+    SeriesName?: string;
+    RingKey?: string;
+    Date?: string;
+    ParentKey?: string | null;
+    X?: number;
+    Y?: number;
+    Size?: number;
+    Group?: string;
+    SourceKey?: string;
+    TargetKey?: string;
+    Longitude?: number;
+    Latitude?: number;
+    PointType?: 'Region' | 'Location' | 'Node' | 'Link' | 'Series';
+}

package/src/chart-state.ts

@@ -0,0 +1,35 @@
+import type { ChartOptions, MixedChartOptions, HeatmapOptions } from './types.ts';
+import type { CatalogueKind, CatalogueOptions, ChartPoint } from './catalogue-types.ts';
+import { cataloguePoints, validateCatalogue } from './catalogue-model.ts';
+import { validateMixed, validateHeatmap } from './validation.ts';
+import { mixedPoint, heatmapPoint } from './model.ts';
+export type RuntimeKind = CatalogueKind | 'mixed' | 'heatmap';
+export type RuntimeOptions = CatalogueOptions | MixedChartOptions | HeatmapOptions;
+export function validateChart(kind:RuntimeKind,o:RuntimeOptions) { if(kind==='mixed') validateMixed(o as MixedChartOptions); else if(kind==='heatmap') validateHeatmap(o as HeatmapOptions); else validateCatalogue(kind,o as CatalogueOptions); }
+export function chartPoints(kind:RuntimeKind,o:RuntimeOptions): ChartPoint[] {
+  if(kind==='mixed') { const c=o as MixedChartOptions; return c.Series.flatMap((s,si)=>c.Categories.map((cat,ci)=>({...mixedPoint(c,ci,si)!,Label:cat.Label,CategoryKey:cat.Key}))); }
+  if(kind==='heatmap') return (o as HeatmapOptions).Cells.map((_,i)=>{const p=heatmapPoint(o as HeatmapOptions,i)!;return {...p,Label:`${p.YLabel}, ${p.XLabel}`};});
+  return cataloguePoints(kind,o as CatalogueOptions);
+}
+export function pointIdentity(kind:RuntimeKind,p:ChartPoint) { return JSON.stringify([kind,p.Key,p.SeriesKey||'',p.CategoryKey||'',p.RingKey||'',p.PointType||'']); }
+export function prepareUpdate<O extends RuntimeOptions>(kind:RuntimeKind,current:O,patch:Partial<O>) {
+  const next = {...current,...structuredClone(patch)};
+  // Validate data before deriving selection, so malformed records cannot reach point lookup.
+  validateChart(kind,{...next,SelectedKey:null});
+  const missing = next.SelectedKey != null && !chartPoints(kind,next).some(p=>p.Key===next.SelectedKey);
+  const cleared = missing && (!Object.hasOwn(patch,'SelectedKey') || patch.SelectedKey === current.SelectedKey);
+  if(cleared) next.SelectedKey=null;
+  validateChart(kind,next);
+  return {next,cleared};
+}
+/** Resolve ECharts targets from actual rendered data; display labels never identify a point. */
+export function highlightTargets(config:any,key:string) {
+  const targets:{seriesIndex:number;dataIndex:number;dataType?:string}[]=[];
+  (config?.series||[]).forEach((s:any,seriesIndex:number)=>{
+    if(s.type==='treemap') { let index=1; const visit=(nodes:any[])=>nodes.forEach(n=>{const dataIndex=index++;if(n.id===key)targets.push({seriesIndex,dataIndex});visit(n.children||[]);});visit(s.data||[]); }
+    else (s.data||[]).forEach((d:any,dataIndex:number)=>{if(d?.point?.Key===key)targets.push({seriesIndex,dataIndex,...(s.type==='sankey'?{dataType:'node'}:{})});});
+    (s.links||[]).forEach((d:any,dataIndex:number)=>{if(d?.point?.Key===key)targets.push({seriesIndex,dataIndex,dataType:'edge'});});
+  });
+  return targets;
+}
+export function message(o:ChartOptions,key:string,fallback:string) {return o.Messages?.[key]??fallback;}

package/src/charts.css

@@ -0,0 +1,135 @@
+.blu-chart { width:100%; min-width:0; color:var(--bluui-text,#182230); background:var(--bluui-surface,#fff); font:13px/1.5 var(--blu-font-family,Inter,system-ui,sans-serif); }
+.blu-chart [hidden] { display:none!important; }
+.blu-chart__heading { display:flex; align-items:flex-start; justify-content:space-between; gap:16px; padding:18px 16px 12px; }
+.blu-chart__heading>div:first-child { min-width:0; }
+.blu-chart__heading h3 { margin:0; color:inherit; font-size:16px; font-weight:650; letter-spacing:-.3px; overflow-wrap:anywhere; }
+.blu-chart__heading p { margin:5px 0 0; font-size:11px; color:var(--bluui-text-muted,#667085); line-height:1.6; overflow-wrap:anywhere; }
+.blu-chart__export { display:flex; gap:5px; flex-shrink:0; margin-left:auto; }
+.blu-chart__export :is(select,button) { font:inherit; font-size:11px; border:1px solid var(--bluui-border,#ddd); color:inherit; border-radius:6px; background:var(--bluui-surface,#fff); min-height:34px; padding:6px 8px; cursor:pointer; }
+.blu-chart__export button:disabled { opacity:.5; cursor:default; }
+.blu-chart__stage { position:relative; min-width:0; }
+.blu-chart__plot { width:100%; min-width:0; }
+.blu-chart__state { position:absolute; inset:0; display:grid; place-items:center; background:var(--bluui-surface-muted,#f8f8fa); color:var(--bluui-text-muted,#667085); padding:20px; text-align:center; }
+.blu-chart__state--loading {grid-template-rows:minmax(0,1fr) auto;gap:14px;place-items:stretch;background:var(--bluui-surface,#fff);padding:16px}
+.blu-chart__skeleton {display:flex;flex-direction:column;gap:24px;min-width:0;min-height:0}
+.blu-chart__skeleton-key {display:flex;gap:16px;align-items:center;flex-wrap:wrap}
+.blu-chart__skeleton-plot {flex:1;min-height:0}
+.blu-chart__skeleton-plot>div {height:100%}
+.blu-chart__state-message {font-size:12px}
+.blu-chart__data { margin:12px 16px 0; border-top:1px solid var(--bluui-border,#ddd); font-size:11px; }
+.blu-chart__data summary { cursor:pointer; padding:12px 0; color:var(--bluui-text-muted,#667085); }
+.blu-chart__data--compact { margin-top:0; border-top:0; }
+.blu-chart__data--compact summary { padding:6px 0; }
+.blu-chart__table { overflow:auto; max-height:320px; }
+.blu-chart__table table { width:100%; border-collapse:collapse; white-space:nowrap; font-size:11px; font-variant-numeric:tabular-nums; }
+.blu-chart__table caption { text-align:left; color:var(--bluui-text-muted,#667085); padding:8px; }
+.blu-chart__table th,.blu-chart__table td { padding:8px; border-bottom:1px solid var(--bluui-border,#ddd); text-align:right; }
+.blu-chart__table th:first-child { text-align:left; }
+.blu-chart__table button { font:inherit; color:var(--bluui-primary,#6557e8); background:transparent; border:0; border-radius:3px; padding:5px; cursor:pointer; }
+.blu-chart__table button[aria-pressed=true] { background:var(--bluui-selected,#eeeaff); text-decoration:underline; text-decoration-thickness:2px; text-underline-offset:3px; font-weight:700; }
+.blu-chart :is(button,select,summary,[tabindex]):focus-visible { outline:2px solid var(--bluui-primary,#6557e8); outline-offset:2px; }
+.blu-chart__status { font-size:11px; color:var(--bluui-text-muted,#667085); margin:0 16px; }
+.blu-chart__status:not(:empty) { padding:8px 0; }
+@media(max-width:640px) { .blu-chart__heading { flex-wrap:wrap; padding-inline:12px; }.blu-chart__export { margin-left:0; }.blu-chart__data { margin-inline:12px; } }
+
+.blu-chart__navigation {display:flex;flex-wrap:wrap;gap:6px;padding:8px 16px}
+.blu-chart__navigation button {min-width:32px;min-height:32px;padding:5px 9px;font:inherit;font-size:12px;color:var(--bluui-text);background:var(--bluui-surface);border:1px solid var(--bluui-control-border);border-radius:5px;cursor:pointer}
+.blu-chart__stage[tabindex]:focus-visible {outline-offset:-3px}
+
+
+.blu-chart__state-announcement { position:absolute; width:1px; height:1px; overflow:hidden; clip-path:inset(50%); white-space:nowrap; }
+.blu-chart__patterns {display:flex;align-items:center;gap:8px;font-size:12px;padding:6px 0 12px;cursor:pointer}
+.blu-chart__patterns input {width:24px;height:24px;margin:0;accent-color:var(--bluui-color-primary-solid)}
+
+.blu-chart__missing-note {margin:8px 12px;color:var(--bluui-text-muted);font-size:12px;line-height:1.5}
+
+/* BEGIN GENERATED SHARED CHECKBOX — scripts/build-checkbox-styles.mjs */
+/* One checkbox design, emitted into each owning Block. Keep native input/tree/grid semantics. */
+.blu-chart .blu-chart__patterns input[type="checkbox"] {
+  -webkit-appearance:none;
+  appearance:none;
+  box-sizing:border-box;
+  position:relative;
+  display:inline-block;
+  flex:0 0 22px;
+  width:22px;
+  height:22px;
+  min-width:22px;
+  min-height:22px;
+  margin:0;
+  padding:0;
+  border:1.5px solid var(--bluui-control-border,#7b8799);
+  border-radius:6px;
+  background-color:var(--bluui-surface,#fff);
+  background-image:none;
+  box-shadow:0 1px 2px rgb(15 23 42 / 6%);
+  vertical-align:middle;
+  cursor:pointer;
+  opacity:1;
+  filter:none;
+  transition:background-color 120ms ease,border-color 120ms ease,box-shadow 120ms ease;
+}
+.blu-chart .blu-chart__patterns input[type="checkbox"]::after { content:none; }
+.blu-chart .blu-chart__patterns input[type="checkbox"]:checked,
+.blu-chart .blu-chart__patterns input[type="checkbox"]:indeterminate {
+  border-color:var(--bluui-color-primary-solid,#4f46e5);
+  background-color:var(--bluui-color-primary-solid,#4f46e5);
+}
+.blu-chart .blu-chart__patterns input[type="checkbox"]:checked::after,
+.blu-chart .blu-chart__patterns input[type="checkbox"]:indeterminate::after {
+  content:"";
+  box-sizing:content-box;
+  position:absolute;
+  inset:auto;
+  width:10px;
+  height:6px;
+  left:4px;
+  top:5px;
+  border:solid var(--bluui-color-primary-contrast,#fff);
+  border-width:0 0 2px 2px;
+  border-radius:0;
+  background:none;
+  -webkit-mask:none;
+  mask:none;
+  transform:rotate(-45deg);
+  pointer-events:none;
+}
+.blu-chart .blu-chart__patterns input[type="checkbox"]:indeterminate::after {
+  height:0;
+  top:8px;
+  border-width:0 0 2px;
+  transform:none;
+}
+.blu-chart .blu-chart__patterns input[type="checkbox"]:hover:not(:disabled) {
+  border-color:var(--bluui-color-primary-solid,#4f46e5);
+  box-shadow:0 0 0 3px var(--bluui-color-primary-soft,#eef2ff);
+}
+.blu-chart .blu-chart__patterns input[type="checkbox"]:focus-visible {
+  outline:2px solid var(--bluui-color-primary-solid,#4f46e5);
+  outline-offset:3px;
+}
+.blu-chart .blu-chart__patterns input[type="checkbox"]:disabled {
+  border-color:var(--bluui-border-strong,#b8c4d4);
+  background-color:var(--bluui-surface-muted,#f7f8fb);
+  box-shadow:none;
+  cursor:not-allowed;
+}
+.blu-chart .blu-chart__patterns input[type="checkbox"]:disabled:checked,
+.blu-chart .blu-chart__patterns input[type="checkbox"]:disabled:indeterminate {
+  border-color:var(--bluui-text-muted,#5c6b80);
+  background-color:var(--bluui-text-muted,#5c6b80);
+}
+@media (prefers-reduced-motion:reduce) {
+  .blu-chart .blu-chart__patterns input[type="checkbox"] { transition:none; }
+}
+.blu-chart .blu-chart__patterns input[type="checkbox"]::before { content:none; }
+@media (forced-colors:active) {
+  .blu-chart .blu-chart__patterns input[type="checkbox"],
+  .blu-chart .blu-chart__patterns input[type="checkbox"]:checked,
+  .blu-chart .blu-chart__patterns input[type="checkbox"]:indeterminate,
+  .blu-chart .blu-chart__patterns input[type="checkbox"]:disabled,
+  .blu-chart .blu-chart__patterns input[type="checkbox"]:disabled:checked,
+  .blu-chart .blu-chart__patterns input[type="checkbox"]:disabled:indeterminate { -webkit-appearance:checkbox; appearance:auto; background:revert; border:revert; box-shadow:none; forced-color-adjust:auto; }
+  .blu-chart .blu-chart__patterns input[type="checkbox"]:checked::after, .blu-chart .blu-chart__patterns input[type="checkbox"]:indeterminate::after { content:none; }
+}
+/* END GENERATED SHARED CHECKBOX */

package/src/colors.ts

@@ -0,0 +1,277 @@
+import type { ComponentColor, ChartColor } from './types.ts';
+
+// Automatic series colors use vivid hues; renderers still enforce contrast.
+export function automaticPalette(dark: boolean): string[] {
+  return dark
+    ? ['#a16aff', '#00cfff', '#ff2b91', '#ff8a00', '#36e377', '#e13dff', '#4285ff', '#ff4056']
+    : ['#7020ff', '#0094ff', '#ff006e', '#ff6a00', '#00b94f', '#c000ff', '#004fff', '#ff1738'];
+}
+
+// Snapshot of the main website's canonical ComponentColor catalogue.
+// Resolve the shared CSS tokens at render time so appearance changes stay in sync.
+export const componentColors = ["Default", "Primary", "Secondary", "Success", "Processing", "Warning", "Error", "Danger", "Magenta", "Red", "Volcano", "Orange", "Gold", "Lime", "Green", "Cyan", "Blue", "GeekBlue", "Purple"] as const satisfies readonly ComponentColor[];
+const fallback = {
+  "Default": [
+    [
+      "#f5f5f5",
+      "#000000",
+      "#1d1d1d"
+    ],
+    [
+      "#272727",
+      "rgba(255, 255, 255, 0.95)",
+      "#dfdfdf"
+    ]
+  ],
+  "Primary": [
+    [
+      "#eef2ff",
+      "#4f46e5",
+      "#4338ca"
+    ],
+    [
+      "#282445",
+      "#8070ed",
+      "#b6acff"
+    ]
+  ],
+  "Secondary": [
+    [
+      "#e2e8f0",
+      "#475569",
+      "#334155"
+    ],
+    [
+      "#2b3240",
+      "#526077",
+      "#d6dce5"
+    ]
+  ],
+  "Success": [
+    [
+      "#f6ffed",
+      "#52c41a",
+      "#2d6c0e"
+    ],
+    [
+      "#162312",
+      "#49aa19",
+      "#73be4e"
+    ]
+  ],
+  "Processing": [
+    [
+      "#e6f4ff",
+      "#2681ff",
+      "#1054b5"
+    ],
+    [
+      "#111a2c",
+      "#145ec6",
+      "#78a7eb"
+    ]
+  ],
+  "Warning": [
+    [
+      "#fffbe6",
+      "#faad14",
+      "#7d560a"
+    ],
+    [
+      "#2b2111",
+      "#d89614",
+      "#dda535"
+    ]
+  ],
+  "Error": [
+    [
+      "#fff2f0",
+      "#ff4d4f",
+      "#a33133"
+    ],
+    [
+      "#2c1618",
+      "#dc4446",
+      "#ea8d8e"
+    ]
+  ],
+  "Danger": [
+    [
+      "#fff2f0",
+      "#ff4d4f",
+      "#a33133"
+    ],
+    [
+      "#2c1618",
+      "#dc4446",
+      "#ea8d8e"
+    ]
+  ],
+  "Magenta": [
+    [
+      "#fff0f6",
+      "#ed409e",
+      "#a9196d"
+    ],
+    [
+      "#291321",
+      "#cf3a8c",
+      "#e984b9"
+    ]
+  ],
+  "Red": [
+    [
+      "#fff1f0",
+      "#e4202a",
+      "#b4111e"
+    ],
+    [
+      "#2a1215",
+      "#cd1f28",
+      "#f08485"
+    ]
+  ],
+  "Volcano": [
+    [
+      "#fff2e8",
+      "#fa541c",
+      "#aa2d0a"
+    ],
+    [
+      "#2b1611",
+      "#d84a1b",
+      "#ed8e68"
+    ]
+  ],
+  "Orange": [
+    [
+      "#fff7e6",
+      "#fa8c16",
+      "#904905"
+    ],
+    [
+      "#2b1d11",
+      "#d87a16",
+      "#e89b3e"
+    ]
+  ],
+  "Gold": [
+    [
+      "#fffbe6",
+      "#faad14",
+      "#835404"
+    ],
+    [
+      "#2b2111",
+      "#d89614",
+      "#e8b339"
+    ]
+  ],
+  "Lime": [
+    [
+      "#fcffe6",
+      "#a0d911",
+      "#486803"
+    ],
+    [
+      "#1f2611",
+      "#8bbb11",
+      "#a9d134"
+    ]
+  ],
+  "Green": [
+    [
+      "#f6ffed",
+      "#52c41a",
+      "#276d09"
+    ],
+    [
+      "#162312",
+      "#49aa19",
+      "#6bbf3b"
+    ]
+  ],
+  "Cyan": [
+    [
+      "#e6fffb",
+      "#13c2c2",
+      "#06686c"
+    ],
+    [
+      "#112123",
+      "#13a8a8",
+      "#33bcb7"
+    ]
+  ],
+  "Blue": [
+    [
+      "#e6f4ff",
+      "#2681ff",
+      "#0851c8"
+    ],
+    [
+      "#111a2c",
+      "#145ec6",
+      "#6fa8ee"
+    ]
+  ],
+  "GeekBlue": [
+    [
+      "#f0f5ff",
+      "#2f54eb",
+      "#1d39c4"
+    ],
+    [
+      "#131629",
+      "#2b4acb",
+      "#89a0ea"
+    ]
+  ],
+  "Purple": [
+    [
+      "#f9f0ff",
+      "#722ed1",
+      "#531dab"
+    ],
+    [
+      "#1a1325",
+      "#642ab5",
+      "#b593df"
+    ]
+  ]
+};
+export const isComponentColor = (value: unknown): value is ComponentColor => typeof value === 'string' && (componentColors as readonly string[]).includes(value);
+export const isChartColor = (value: unknown): value is ChartColor => isComponentColor(value) || (typeof value === 'string' && /^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i.test(value));
+export function componentPalette(name: ComponentColor, dark: boolean, read: (token: string) => string = () => '') {
+  const shades = fallback[name][dark ? 1 : 0];
+  const token = name.toLowerCase();
+  return { soft: read(`--bluui-color-${token}-soft`).trim() || shades[0], solid: read(`--bluui-color-${token}-solid`).trim() || shades[1], text: read(`--bluui-color-${token}-text`).trim() || shades[2] };
+}
+export function resolveChartColor(color: ChartColor | undefined, automatic: string, dark: boolean, read?: (token: string) => string) {
+  return isComponentColor(color) ? componentPalette(color, dark, read).solid : color || automatic;
+}
+
+function rgbChannels(color: string): number[] {
+  if (color.startsWith('rgb')) return color.match(/[\d.]+/g)!.slice(0, 3).map(Number);
+  const raw = color.slice(1);
+  const hex = raw.length < 5 ? raw.slice(0, 3).split('').map(c => c + c).join('') : raw.slice(0, 6);
+  return [0, 2, 4].map(i => parseInt(hex.slice(i, i + 2), 16));
+}
+
+/** Match the linear RGB interpolation used by continuous ECharts color scales. */
+export function interpolateColor(colors: string[], position: number): string {
+  const offset = Math.max(0, Math.min(1, position)) * (colors.length - 1);
+  const index = Math.min(Math.floor(offset), colors.length - 2), fraction = offset - index;
+  const start = rgbChannels(colors[index]), end = rgbChannels(colors[index + 1]);
+  return `rgb(${start.map((v, i) => Math.round(v + (end[i] - v) * fraction)).join(',')})`;
+}
+
+/** Pick dark or white text with at least 4.5:1 contrast against an opaque mark. */
+export function contrastText(color: string): string {
+  const linear = rgbChannels(color).map(c => { const n = c / 255; return n <= .04045 ? n / 12.92 : ((n + .055) / 1.055) ** 2.4; });
+  const luminance = linear[0] * .2126 + linear[1] * .7152 + linear[2] * .0722;
+  // Prefer our ink tone when it passes; use black in the narrow mid-tone range.
+  if ((luminance + .05) / .0656 >= 4.5) return '#182230';
+  if (1.05 / (luminance + .05) >= 4.5) return '#fff';
+  return '#000';
+}

package/src/community.ts

@@ -0,0 +1,11 @@
+export type * from './types.ts';
+export type * from './catalogue-types.ts';
+export { createLineChart } from './line.ts';
+export { createBarChart } from './bar.ts';
+export { createPieChart } from './pie.ts';
+export { createDoughnutChart } from './doughnut.ts';
+export { createScatterChart } from './scatter.ts';
+export { createRadarChart } from './radar.ts';
+export { createHeatmap } from './heatmap.ts';
+export { createSparkline } from './sparkline.ts';
+export type { BluSparklinePoint, SparklineOptions, SparklineEvents, SparklineInstance } from './sparkline.ts';

package/src/doughnut.ts

@@ -0,0 +1,12 @@
+import { buildOption } from './builders/doughnut.ts';
+import { use } from 'echarts/core';
+import { PieChart } from 'echarts/charts';
+import { createCatalogueChart } from './catalogue-runtime.ts';
+import type { OptionsByKind, ChartPoint } from './catalogue-types.ts';
+import type { ChartEvents } from './types.ts';
+export type { OptionsByKind, ChartPoint } from './catalogue-types.ts';
+export type DoughnutChartOptions = OptionsByKind['doughnut'];
+export function createDoughnutChart(host: HTMLElement, options: DoughnutChartOptions, events: ChartEvents<ChartPoint> = {}) {
+  use([PieChart]);
+  return createCatalogueChart(host, 'doughnut', options, events, buildOption);
+}