@colixsystems/widget-sdk 0.246.0 → 0.248.0

package/dist/chart-tokens.js

@@ -0,0 +1,131 @@
+// The colours and corners `<Chart>` paints with, resolved from the theme's
+// `chart` scope and falling back to the theme's own colours. Platform-free,
+// so both hosts draw one chart from the same values.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { CONTRACT, isHexColor, mixHex } from "./contract.js";
+import { normaliseThemeComponents } from "./theme-components.js";
+
+export const CHART_SERIES_TOKENS = Object.freeze(["series1", "series2", "series3", "series4", "series5", "series6"]);
+
+// Distinct hues first, so two series rarely share a family.
+const PALETTE_ROLES = Object.freeze(["primary", "warning", "secondary", "danger", "info", "success"]);
+// How far a seventh-and-later series is lightened toward the surface.
+const REPEAT_TINT = 0.45;
+
+function themeColors(theme) {
+  return { ...DEFAULT_THEME_TOKENS.colors, ...((theme && theme.colors) || {}) };
+}
+
+/** The six series colours an unthemed chart uses: the theme's own, deduplicated. */
+function defaultPalette(colors) {
+  const seen = new Set();
+  const palette = [];
+  for (const role of PALETTE_ROLES) {
+    const colour = colors[role];
+    const key = typeof colour === "string" ? colour.toLowerCase() : "";
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    palette.push(colour);
+  }
+  for (let i = 0; palette.length < CHART_SERIES_TOKENS.length; i += 1) {
+    palette.push(mixHex(colors.primary, i % 2 ? colors.surface : colors.onSurface, 0.3 + 0.15 * Math.floor(i / 2)));
+  }
+  return palette;
+}
+
+/**
+ * Resolve one chart's look: the `chart` scope first, then the theme.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @returns {{ palette: string[], axisColor: string, gridColor: string, barRadius: number, surface: string, fontFamily: string, fontSize: number }}
+ */
+export function resolveChartTokens(theme) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const colors = themeColors(base);
+  const radii = base.radii || DEFAULT_THEME_TOKENS.radii;
+  const typography = base.typography || DEFAULT_THEME_TOKENS.typography;
+  const sizes = typography.sizes || DEFAULT_THEME_TOKENS.typography.sizes;
+  const scope = normaliseThemeComponents(base.components).chart || {};
+  const fallback = defaultPalette(colors);
+  return {
+    palette: CHART_SERIES_TOKENS.map((token, i) => scope[token] ?? fallback[i]),
+    axisColor: scope.axisColor ?? colors.onSurfaceMuted,
+    gridColor: scope.gridColor ?? colors.border,
+    barRadius: scope.barRadius ?? radii.sm,
+    surface: colors.surface,
+    fontFamily: typography.fontFamily || DEFAULT_THEME_TOKENS.typography.fontFamily,
+    fontSize: sizes.xs || DEFAULT_THEME_TOKENS.typography.sizes.xs,
+  };
+}
+
+const RGB = /^rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*(?:,\s*[\d.]+%?\s*)?\)$/i;
+
+// A `#rrggbb` for a hex or rgb() colour, so it can be mixed; else null.
+function mixable(colour) {
+  if (isHexColor(colour)) return colour;
+  const rgb = typeof colour === "string" ? RGB.exec(colour.trim()) : null;
+  if (!rgb) return null;
+  return `#${rgb.slice(1, 4).map((n) => Math.min(255, Number(n)).toString(16).padStart(2, "0")).join("")}`;
+}
+
+/**
+ * How series (or donut slice) `index` is painted: its palette colour, a
+ * seventh and later one lighter. A colour that cannot be mixed (a named or
+ * hsl() colour) repeats at a lower opacity instead.
+ *
+ * @returns {{ color: string, opacity: number }}
+ */
+export function chartSeriesPaint(tokens, index) {
+  const palette = tokens.palette;
+  const colour = palette[index % palette.length];
+  const round = Math.floor(index / palette.length);
+  if (round === 0) return { color: colour, opacity: 1 };
+  const tint = Math.min(0.8, REPEAT_TINT * round);
+  const hex = mixable(colour);
+  return hex ? { color: mixHex(hex, tokens.surface, tint), opacity: 1 } : { color: colour, opacity: 1 - tint };
+}
+
+/** The colour of series (or donut slice) `index`; see `chartSeriesPaint`. */
+export function chartSeriesColor(tokens, index) {
+  return chartSeriesPaint(tokens, index).color;
+}
+
+/**
+ * The colours `<Chart>` paints with, for a chart a widget draws itself (a
+ * scatter plot, a timeline): `series(i)` and `seriesOpacity(i)` for the i-th
+ * series' marks, `axis` for labels and the axis line, `grid` for gridlines.
+ * Pass it `useTheme()`, so a hand-drawn chart follows Design > Components >
+ * Charts exactly as `<Chart>` does.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ */
+export function chartColors(theme) {
+  const tokens = resolveChartTokens(theme);
+  return {
+    palette: tokens.palette.slice(),
+    axis: tokens.axisColor,
+    grid: tokens.gridColor,
+    series: (index) => chartSeriesPaint(tokens, index).color,
+    seriesOpacity: (index) => chartSeriesPaint(tokens, index).opacity,
+  };
+}
+
+/**
+ * What each `chart` token resolves to while unset, keyed by token name, so
+ * the Studio previews the colour each control would replace.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ */
+export function chartScopeDefaults(theme) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const components = { ...(base.components || {}) };
+  delete components.chart;
+  const unset = resolveChartTokens({ ...base, components });
+  const out = {};
+  for (const token of Object.keys(CONTRACT.themeComponents.chart.tokens)) {
+    const series = CHART_SERIES_TOKENS.indexOf(token);
+    out[token] = series === -1 ? unset[token] : unset.palette[series];
+  }
+  return out;
+}

package/dist/chart-view.js

@@ -0,0 +1,262 @@
+// The ONE implementation behind the `<Chart>` SDK primitive. The platform
+// bindings (`chart.js` / `chart.native.js`) differ only in where the
+// primitives and the SVG elements come from, so the hosts cannot drift.
+//
+// Every dashboard widget drew its own chart, each with its own colours, axes
+// and empty state. This one reads the theme's `chart` scope.
+
+import React from "react";
+import { useHostLocale, useHostTheme, useHostSharedText } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { CONTRACT } from "./contract.js";
+import { textRoleStyle } from "./text-roles.js";
+import { resolveChartTokens, chartSeriesPaint } from "./chart-tokens.js";
+import {
+  normaliseChartType,
+  chartHeight,
+  normaliseChartData,
+  isChartEmpty,
+  cartesianLayout,
+  donutLayout,
+  barPath,
+  chartSummary,
+  formatChartValue,
+} from "./chart-logic.js";
+
+const h = React.createElement;
+const NO_RESULTS_FALLBACK = CONTRACT.sharedTranslationKeys.no_results.en;
+const AREA_OPACITY = 0.18;
+const LINE_WIDTH = 2;
+const DOT_RADIUS = 3;
+const SWATCH_SIZE = 10;
+const HIDDEN = { "aria-hidden": true, importantForAccessibility: "no-hide-descendants" };
+
+/**
+ * Bind the shared chart to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Svg: any, G: any, Path: any, Line: any, Circle: any, SvgText: any, Skeleton: any, EmptyState: any}} rn
+ */
+export function makeChart(rn) {
+  const { View, Text, Svg, G, Path, Line, Circle, SvgText, Skeleton, EmptyState } = rn;
+
+  function Legend({ items, theme, testID }) {
+    const typography = theme.typography || DEFAULT_THEME_TOKENS.typography;
+    const colors = theme.colors || DEFAULT_THEME_TOKENS.colors;
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    const label = textRoleStyle("caption", typography, colors);
+    return h(
+      View,
+      {
+        style: { flexDirection: "row", flexWrap: "wrap", columnGap: spacing.md, rowGap: spacing.xs, marginTop: spacing.sm },
+        testID: testID ? `${testID}-legend` : undefined,
+      },
+      items.map((item) =>
+        h(
+          View,
+          { key: item.key, style: { flexDirection: "row", alignItems: "center", gap: spacing.xs, minWidth: 0 } },
+          h(View, {
+            style: {
+              width: SWATCH_SIZE,
+              height: SWATCH_SIZE,
+              borderRadius: SWATCH_SIZE / 2,
+              backgroundColor: item.paint.color,
+              opacity: item.paint.opacity,
+            },
+          }),
+          h(Text, { style: label, numberOfLines: 1 }, item.text),
+        ),
+      ),
+    );
+  }
+
+  function axisText(label, i, tokens, prefix) {
+    return h(
+      SvgText,
+      {
+        key: `${prefix}-${i}`,
+        x: label.x,
+        y: label.y,
+        fill: tokens.axisColor,
+        fontSize: tokens.fontSize,
+        fontFamily: tokens.fontFamily,
+        textAnchor: label.anchor,
+      },
+      label.text,
+    );
+  }
+
+  function CartesianMarks({ kind, width, height, model, tokens, valueFormat, locale, paintOf }) {
+    const layout = cartesianLayout({ type: kind, width, height, model, fontSize: tokens.fontSize, valueFormat, locale });
+    const grid = layout.gridLines.map((line, i) =>
+      line.y === undefined
+        ? h(Line, { key: `grid-${i}`, x1: line.x, x2: line.x, y1: line.y1, y2: line.y2, stroke: tokens.gridColor, strokeWidth: 1 })
+        : h(Line, { key: `grid-${i}`, x1: line.x1, x2: line.x2, y1: line.y, y2: line.y, stroke: tokens.gridColor, strokeWidth: 1 }),
+    );
+    const base = layout.baseline;
+    const axis = !base
+      ? null
+      : base.y === undefined
+        ? h(Line, { x1: base.x, x2: base.x, y1: base.y1, y2: base.y2, stroke: tokens.axisColor, strokeWidth: 1 })
+        : h(Line, { x1: base.x1, x2: base.x2, y1: base.y, y2: base.y, stroke: tokens.axisColor, strokeWidth: 1 });
+    return h(
+      G,
+      null,
+      kind === "sparkline" ? null : grid,
+      layout.areas.map((area) =>
+        h(Path, {
+          key: `area-${area.seriesIndex}`,
+          d: area.d,
+          fill: paintOf(area.seriesIndex).color,
+          fillOpacity: AREA_OPACITY * paintOf(area.seriesIndex).opacity,
+        }),
+      ),
+      layout.bars.map((bar) =>
+        h(Path, {
+          key: `bar-${bar.seriesIndex}-${bar.index}`,
+          d: barPath(bar.rect, tokens.barRadius, bar.edge),
+          fill: paintOf(bar.seriesIndex).color,
+          fillOpacity: paintOf(bar.seriesIndex).opacity,
+        }),
+      ),
+      axis,
+      layout.lines.map((line) =>
+        h(Path, {
+          key: `line-${line.seriesIndex}`,
+          d: line.d,
+          fill: "none",
+          stroke: paintOf(line.seriesIndex).color,
+          strokeOpacity: paintOf(line.seriesIndex).opacity,
+          strokeWidth: LINE_WIDTH,
+          strokeLinejoin: "round",
+          strokeLinecap: "round",
+        }),
+      ),
+      layout.dots.map((dot, i) =>
+        h(Circle, {
+          key: `dot-${i}`,
+          cx: dot.cx,
+          cy: dot.cy,
+          r: DOT_RADIUS,
+          fill: paintOf(dot.seriesIndex).color,
+          fillOpacity: paintOf(dot.seriesIndex).opacity,
+        }),
+      ),
+      layout.tickLabels.map((label, i) => axisText(label, i, tokens, "tick")),
+      layout.categoryLabels.map((label, i) => axisText(label, i, tokens, "label")),
+    );
+  }
+
+  function DonutMarks({ width, height, model, tokens, valueFormat, locale, paintOf }) {
+    const layout = donutLayout({ width, height, model });
+    return h(
+      G,
+      null,
+      layout.slices.map((slice) =>
+        h(Path, {
+          key: `slice-${slice.index}`,
+          d: slice.d,
+          fill: paintOf(slice.index).color,
+          fillOpacity: paintOf(slice.index).opacity,
+          fillRule: "evenodd",
+        }),
+      ),
+      h(
+        SvgText,
+        {
+          x: layout.cx,
+          y: layout.cy + tokens.fontSize / 3,
+          fill: tokens.axisColor,
+          fontSize: tokens.fontSize + 2,
+          fontWeight: "600",
+          fontFamily: tokens.fontFamily,
+          textAnchor: "middle",
+        },
+        formatChartValue(layout.total, valueFormat, locale),
+      ),
+    );
+  }
+
+  function Chart(props) {
+    const {
+      type,
+      data,
+      series,
+      valueFormat,
+      height,
+      loading,
+      emptyTitle,
+      emptyMessage,
+      accessibilityLabel,
+      moreText,
+      theme: explicitTheme,
+      style,
+      testID,
+    } = props;
+    const hostTheme = useHostTheme();
+    // A host drawing outside a widget context passes its own theme.
+    const theme = explicitTheme || hostTheme || DEFAULT_THEME_TOKENS;
+    const noResults = useHostSharedText("no_results", NO_RESULTS_FALLBACK);
+    const locale = useHostLocale();
+    const [width, setWidth] = React.useState(0);
+    const kind = normaliseChartType(type);
+    const plotHeight = chartHeight(kind, height);
+    const model = React.useMemo(() => normaliseChartData(data, series), [data, series]);
+
+    if (loading) {
+      return h(Skeleton, { shape: "block", height: plotHeight, theme: explicitTheme, style, testID });
+    }
+    if (isChartEmpty(model, kind)) {
+      return h(EmptyState, { title: emptyTitle || noResults, message: emptyMessage, style, testID });
+    }
+
+    const tokens = resolveChartTokens(theme);
+    const paintOf = (index) => {
+      const own = kind === "donut" ? undefined : model.series[index] && model.series[index].color;
+      return own ? { color: own, opacity: 1 } : chartSeriesPaint(tokens, index);
+    };
+    const onLayout = (event) => {
+      const next = Math.floor(event.nativeEvent.layout.width);
+      if (next !== width) setWidth(next);
+    };
+    const marks =
+      width <= 0
+        ? null
+        : h(
+            Svg,
+            { width, height: plotHeight },
+            kind === "donut"
+              ? h(DonutMarks, { width, height: plotHeight, model, tokens, valueFormat, locale, paintOf })
+              : h(CartesianMarks, { kind, width, height: plotHeight, model, tokens, valueFormat, locale, paintOf }),
+          );
+    const legendItems =
+      kind === "donut"
+        ? donutLayout({ width: 1, height: 1, model }).slices.map((slice) => ({
+            key: `slice-${slice.index}`,
+            paint: paintOf(slice.index),
+            text: `${model.labels[slice.index]} ${formatChartValue(model.series[0].values[slice.index], valueFormat, locale)}`,
+          }))
+        : model.series.length > 1 && kind !== "sparkline"
+          ? model.series.map((s, i) => ({ key: s.key, paint: paintOf(i), text: s.label }))
+          : null;
+
+    return h(
+      View,
+      {
+        accessible: true,
+        accessibilityRole: "image",
+        accessibilityLabel: chartSummary({ type: kind, model, valueFormat, lead: accessibilityLabel, locale, moreText }),
+        style: [{ width: "100%" }, style],
+        testID,
+      },
+      h(
+        View,
+        { ...HIDDEN, onLayout, style: { width: "100%", height: plotHeight }, testID: testID ? `${testID}-plot` : undefined },
+        marks,
+      ),
+      legendItems ? h(Legend, { items: legendItems, theme, testID }) : null,
+    );
+  }
+  Chart.displayName = "Chart";
+
+  return { Chart };
+}

package/dist/chart.js

@@ -0,0 +1,21 @@
+// `<Chart>` (web). Binds ./chart-view.js to react-native-web and the host's
+// react-native-svg; see ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import Svg, { G, Path, Line, Circle, Text as SvgText } from "react-native-svg";
+import { Skeleton } from "./loading.js";
+import { EmptyState } from "./list.js";
+import { makeChart } from "./chart-view.js";
+
+export const { Chart } = makeChart({
+  View: ReactNative.View,
+  Text: ReactNative.Text,
+  Svg,
+  G,
+  Path,
+  Line,
+  Circle,
+  SvgText,
+  Skeleton,
+  EmptyState,
+});

package/dist/chart.native.js

@@ -0,0 +1,10 @@
+// `<Chart>` (native). Binds ./chart-view.js to React Native and
+// react-native-svg; only the imports differ from ./chart.js.
+
+import { View, Text } from "react-native";
+import Svg, { G, Path, Line, Circle, Text as SvgText } from "react-native-svg";
+import { Skeleton } from "./loading.native.js";
+import { EmptyState } from "./list.native.js";
+import { makeChart } from "./chart-view.js";
+
+export const { Chart } = makeChart({ View, Text, Svg, G, Path, Line, Circle, SvgText, Skeleton, EmptyState });