@humanforest/charts 0.3.7 → 0.4.0

package/src/rovingFocus.ts

@@ -0,0 +1,26 @@
+// Roving focus for the cell components: a track or a grid is one Tab stop, and the keys move it.
+// Cells are one flat run in reading order; the component maps an index back to its element.
+
+/**
+ * The index focus moves to for a key, or null when the key is not a move. ArrowLeft and ArrowRight
+ * step by `across`, ArrowUp and ArrowDown by `down` (0 leaves them to the page), and Home and End
+ * jump to `first` and `last`. A step that would leave the run stays put. A modified key is never a
+ * move, so browser shortcuts such as Cmd+ArrowLeft keep working.
+ */
+export function rovingIndex(
+  event: Pick<KeyboardEvent, 'key' | 'altKey' | 'ctrlKey' | 'metaKey'>,
+  index: number,
+  first: number,
+  last: number,
+  across = 1,
+  down = 0,
+): number | null {
+  if (event.altKey || event.ctrlKey || event.metaKey) return null;
+  if (event.key === 'Home') return first;
+  if (event.key === 'End') return last;
+  const steps: Record<string, number> = { ArrowRight: across, ArrowLeft: -across, ArrowDown: down, ArrowUp: -down };
+  const step = steps[event.key];
+  if (!step) return null;
+  const next = index + step;
+  return next < first || next > last ? index : next;
+}

package/src/snapTooltip.ts

@@ -13,9 +13,11 @@
 // Two anchors, matching how the two frames are read:
 //   crosshair — the crosshair line's x, panel held at the top of the plot. It steps as the
 //               crosshair snaps between rows and holds still in between, which is the whole point.
-//   mark      — the centroid of the hovered shape, panel just outside it on the side with room.
-//               Sampled along the outline rather than taken from the box, so an arc anchors at its
-//               own mid-angle instead of at the corner of a box it never touches.
+//   mark      — the centroid of the hovered shape, panel on the side away from the frame's centre
+//               with its near edge 12px from the centroid, then held 8px inside the viewport, so it
+//               overlaps the outer half of any mark wider than 24px. The centroid is sampled along
+//               the outline rather than taken from the box, so an arc anchors at its own mid-angle
+//               instead of at the corner of a box it never touches.
 import { onBeforeUnmount, onMounted, type Ref } from 'vue';
 import { Crosshair } from '@unovis/ts';
 
@@ -36,10 +38,11 @@ export function nextTipId(): string {
 
 const clamp = (v: number, lo: number, hi: number): number => Math.min(Math.max(v, lo), hi);
 
-/** Centre of a shape, in viewport coordinates. Paths are sampled along their outline and averaged:
- *  for a donut arc that lands at mid-angle, mid-radius — the middle of the visible band — where the
- *  box centre would land in the hole, or outside the wedge entirely on a small segment. Anything
- *  without a length (rects) falls back to its box, which for those IS the mark. */
+/** Centre of a shape, in viewport coordinates. Every SVGGeometryElement, rects included, is sampled
+ *  along its outline and averaged: for a donut arc that lands at mid-angle, mid-radius — the middle
+ *  of the visible band — where the box centre would land in the hole, or outside the wedge entirely
+ *  on a small segment. An element with no outline to measure (a group, text), a zero length or no
+ *  screen matrix falls back to its box. */
 export function shapeCentre(el: SVGGraphicsElement): { x: number; y: number } {
   const path = el as SVGPathElement;
   if (typeof path.getTotalLength === 'function') {
@@ -102,7 +105,6 @@ export function useTooltipSnap(
   // Guards the observer against our own writes, which would otherwise re-enter it forever.
   let writing = false;
   let observer: MutationObserver | undefined;
-  let frame = 0;
 
   function onPointerMove(e: Event): void {
     const t = e.target;
@@ -146,13 +148,14 @@ export function useTooltipSnap(
     writing = false;
   }
 
+  // The panel is looked up each time the pointer enters the chart, the only time it can show.
+  // VisTooltip creates it after mount, a remount (a theme or palette change) replaces it, and a
+  // frame without a tooltip has none. A panel replaced while the pointer is inside is picked up on
+  // the next entry.
   function attach(): void {
+    observer?.disconnect();
     const tip = document.querySelector<HTMLElement>(`[data-forest-tip="${tipId}"]`);
-    if (!tip) {
-      // VisTooltip creates its element on its own schedule; wait for it rather than racing mount.
-      frame = requestAnimationFrame(attach);
-      return;
-    }
+    if (!tip) return;
     observer = new MutationObserver(() => {
       if (!writing) reposition(tip);
     });
@@ -161,12 +164,12 @@ export function useTooltipSnap(
 
   onMounted(() => {
     root.value?.addEventListener('pointermove', onPointerMove, { capture: true });
-    attach();
+    root.value?.addEventListener('pointerenter', attach);
   });
 
   onBeforeUnmount(() => {
-    cancelAnimationFrame(frame);
     observer?.disconnect();
     root.value?.removeEventListener('pointermove', onPointerMove, { capture: true });
+    root.value?.removeEventListener('pointerenter', attach);
   });
 }

package/src/sparklineDomain.ts

@@ -83,3 +83,12 @@ export function sparklineEndpoint(
   }
   return null;
 }
+
+/**
+ * A reading's y on the line marks: its height above the frame's floor, or undefined when there is no
+ * reading to draw, so the line breaks there. Undefined, not null: Unovis' line tests each point with
+ * the global isFinite, which passes a null and plots it at zero.
+ */
+export function sparklineY(v: number | null | undefined, floor: number): number | undefined {
+  return drawable(v) ? v - floor : undefined;
+}

package/src/useCellScale.ts

@@ -29,7 +29,7 @@ export interface CellLegend {
 }
 
 export interface CellScaleOptions<D> {
-  mode: 'state' | 'intensity';
+  mode: MaybeRef<'state' | 'intensity'>;
   /** State mode. Same shape as `categories` elsewhere, so useChartPalette output feeds it as-is. */
   states?: MaybeRef<Record<string, BulletLegendItemInterface> | undefined>;
   /** Intensity mode. */
@@ -105,7 +105,7 @@ export function useCellScale<D>(options: CellScaleOptions<D>): CellScale<D> {
 
   const isEmpty = (d: D | null | undefined): boolean => {
     if (d === null || d === undefined) return true;
-    if (options.mode === 'intensity') {
+    if (unref(options.mode) === 'intensity') {
       const v = options.value?.(d);
       return typeof v !== 'number' || !Number.isFinite(v);
     }
@@ -115,7 +115,7 @@ export function useCellScale<D>(options: CellScaleOptions<D>): CellScale<D> {
 
   const resolve = (d: D | null | undefined): string => {
     if (isEmpty(d)) return CELL_EMPTY_COLOR;
-    if (options.mode === 'intensity') {
+    if (unref(options.mode) === 'intensity') {
       const [lo, hi] = domain.value;
       const v = options.value!(d as D) as number;
       const stops = swatches.value;
@@ -134,7 +134,7 @@ export function useCellScale<D>(options: CellScaleOptions<D>): CellScale<D> {
   };
 
   const legend = computed<CellLegend>(() => {
-    if (options.mode === 'intensity') {
+    if (unref(options.mode) === 'intensity') {
       return {
         mode: 'intensity',
         entries: swatches.value.map((swatch, i) => ({ key: String(i), swatch })),
@@ -156,3 +156,29 @@ export function useCellScale<D>(options: CellScaleOptions<D>): CellScale<D> {
 
   return { colorOf: resolve, isEmpty, legend, domain, swatches };
 }
+
+/** The colour props FStatusTrack and FCalendarGrid share. */
+export interface CellScaleProps<D> {
+  data: readonly D[];
+  mode: 'state' | 'intensity';
+  states?: Record<string, BulletLegendItemInterface>;
+  state?: (d: D) => string | null | undefined;
+  value?: (d: D) => number | null | undefined;
+  ramp?: SequentialRamp;
+  domain?: [number, number];
+  steps: number;
+}
+
+/** useCellScale over a component's colour props, every one read live, the accessors included. */
+export function useCellScaleProps<D>(props: CellScaleProps<D>): CellScale<D> {
+  return useCellScale<D>({
+    mode: computed(() => props.mode),
+    states: computed(() => props.states),
+    ramp: computed(() => props.ramp ?? ('forest' as SequentialRamp)),
+    domain: computed(() => props.domain),
+    steps: computed(() => props.steps),
+    data: computed(() => props.data),
+    value: (d) => props.value?.(d),
+    state: (d) => props.state?.(d),
+  });
+}

package/src/useChartPalette.ts

@@ -12,7 +12,7 @@ export interface SeriesDef { key: string; name: string }
 // 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 VIVID = DATAVIZ_CATEGORICAL.names; // green, amber, sky, … (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]})`;
@@ -37,13 +37,15 @@ const build = (series: SeriesDef[], color: (i: number) => string): Categories =>
 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. */
+     *  The default: the six stay separable on colour alone under all three simulated dichromacies,
+     *  and a second cue (direct labels, dash or marker) covers what the simulation cannot, such as a
+     *  photocopy or a projector. A legend keyed by colour is not that cue. */
     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). */
+     *  NOT CVD-safe — the caller MUST add a second channel (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). */
+     *  NOT CVD-safe — the caller MUST add a second channel (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. */