@humanforest/charts 0.1.0

package/src/useChartPalette.ts

@@ -0,0 +1,61 @@
+// Chart palette helpers for Unovis. Returns `categories` maps whose colours are
+// var(--dataviz-*) STRINGS, not hexes — CSS resolves them, so dark mode flips charts with zero JS
+// and the engine stays the only place values live. Engine hex imports are allowed in chart pages
+// ONLY for CVD-simulation demos (simulateCvd needs real hexes).
+import type { BulletLegendItemInterface } from '@unovis/ts';
+import { DATAVIZ, DATAVIZ_PAIRS, DATAVIZ_CATEGORICAL, DATAVIZ_SEQUENTIAL, DATAVIZ_DIVERGING } from './engine';
+
+type Categories = Record<string, BulletLegendItemInterface>;
+export interface SeriesDef { key: string; name: string }
+
+// Each accessor is named after the palette it returns, matching the tier names on the docs page.
+// There is deliberately NO generic `categorical()` — the generic name used to return the VIVID set,
+// which meant the one palette that is not colour-blind-safe owned the most authoritative-sounding name.
+const SAFE = Object.keys(DATAVIZ.light); // 1..6 — brand-led CVD-safe, consumed by index
+const VIVID = DATAVIZ_CATEGORICAL.names; // green, amber, red, … (first 6 = the curated 6)
+const PAIRS = Object.keys(DATAVIZ_PAIRS.light); // forest-deep, forest-soft, warm-deep, … (family-grouped)
+
+export const safeVar = (i: number) => `var(--dataviz-categorical-safe-${SAFE[i % SAFE.length]})`;
+export const vividVar = (i: number) => `var(--dataviz-categorical-vivid-${VIVID[i % VIVID.length]})`;
+export const pairsVar = (i: number) => `var(--dataviz-categorical-pairs-${PAIRS[i % PAIRS.length]})`;
+
+/** The three categorical sets, named. Only for callers that choose a set at runtime. */
+export type CategoricalPalette = 'cvdSafe' | 'vivid' | 'pairs';
+const CATEGORICAL_VARS: Record<CategoricalPalette, (i: number) => string> = {
+  cvdSafe: safeVar,
+  vivid: vividVar,
+  pairs: pairsVar,
+};
+export const categoricalVar = (p: CategoricalPalette, i: number) => CATEGORICAL_VARS[p](i);
+export const sequentialVar = (name: keyof typeof DATAVIZ_SEQUENTIAL, i: number) => `var(--dataviz-sequential-${name}-${i})`;
+const kebab = (s: string) => s.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+export const divergingVar = (name: keyof typeof DATAVIZ_DIVERGING, i: number) => `var(--dataviz-diverging-${kebab(name)}-${i})`;
+
+const build = (series: SeriesDef[], color: (i: number) => string): Categories =>
+  Object.fromEntries(series.map((s, i) => [s.key, { name: s.name, color: color(i) }]));
+
+export function useChartPalette() {
+  return {
+    /** The 6-colour brand-led CVD-safe set — what the Unovis adapter already ships on --vis-color0..5.
+     *  The default: colour alone separates the series, so it needs no second channel. */
+    cvdSafe: (series: SeriesDef[]) => build(series, safeVar),
+    /** Vivid categorical (palette order). ≤6 where you can; 7–12 are label-only.
+     *  NOT CVD-safe — the caller MUST add a second channel (legend, direct labels, dash or marker). */
+    vivid: (series: SeriesDef[]) => build(series, vividVar),
+    /** Brand pairs — 3 brand hues × deep/soft, family-grouped. Brand-forward work: decks, marketing.
+     *  NOT CVD-safe — the caller MUST add a second channel (legend, direct labels, dash or marker). */
+    pairs: (series: SeriesDef[]) => build(series, pairsVar),
+    /** One of the three sets, chosen at runtime. For the docs' palette picker — production code
+     *  should name the set it means, so the CVD contract above is visible at the call site. */
+    byName: (p: CategoricalPalette, series: SeriesDef[]) =>
+      build(series, (i) => categoricalVar(p, i)),
+    /** n evenly-spaced stops from a sequential ramp (low → high). */
+    sequential: (name: keyof typeof DATAVIZ_SEQUENTIAL, n: number) => {
+      const len = DATAVIZ_SEQUENTIAL[name].length;
+      return Array.from({ length: n }, (_, i) => sequentialVar(name, Math.round((i * (len - 1)) / Math.max(n - 1, 1))));
+    },
+    /** All 9 stops of a diverging ramp (low → centre → high). */
+    diverging: (name: keyof typeof DATAVIZ_DIVERGING) =>
+      DATAVIZ_DIVERGING[name].map((_, i) => divergingVar(name, i)),
+  };
+}

package/src/useChartRepaintKey.ts

@@ -0,0 +1,22 @@
+import { computed, toValue, type ComputedRef, type MaybeRefOrGetter } from 'vue';
+
+/**
+ * Remount key for Unovis charts whose series colours change identity at runtime.
+ *
+ * The bug it works around: Unovis caches series colours on mount — Bar, Donut and Bubble keep
+ * painting the colours they mounted with even after `categories` hands them new ones (Line
+ * re-reads and repaints without help, which is why the trap is easy to miss). Bind the returned
+ * key as `:key` on the chart component so a flip of any signal remounts it:
+ *
+ * ```ts
+ * const chartKey = useChartRepaintKey(mode, vision, chartSet);
+ * // <VisSingleContainer :key="chartKey" …>
+ * ```
+ *
+ * Signals are passed in as refs or getters — colour mode, CVD simulation, palette choice —
+ * rather than read from an app composable, so the package carries no app internals; the docs
+ * app passes its own colour-mode ref.
+ */
+export function useChartRepaintKey(...signals: MaybeRefOrGetter<unknown>[]): ComputedRef<string> {
+  return computed(() => signals.map((s) => String(toValue(s))).join('-'));
+}

package/src/useThemeVersion.ts

@@ -0,0 +1,17 @@
+// Frame-owned repaint signal: bumps when the documentElement's class or data-theme attribute
+// changes (i.e. on a colour-mode flip). Unovis Bar/Donut/Bubble cache resolved colours on mount,
+// so a var(--dataviz-*) colour does NOT repaint them when dark mode lands — remounting on this
+// signal is the workaround, owned by the frame instead of every call site.
+import { onScopeDispose, ref, type Ref } from 'vue';
+
+export function useThemeVersion(): Ref<number> {
+  const version = ref(0);
+  if (typeof window === 'undefined' || typeof MutationObserver === 'undefined') return version;
+  const observer = new MutationObserver(() => { version.value++; });
+  observer.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ['class', 'data-theme'],
+  });
+  onScopeDispose(() => observer.disconnect());
+  return version;
+}