@humanforest/charts 0.1.0

package/LICENSE

@@ -0,0 +1,67 @@
+Forest Design System — Licence
+Copyright (c) 2026 HumanForest Ltd. All rights reserved.
+
+This software is published openly so that people building Forest products can install it
+without access to its source repository. It is not open-source software.
+
+
+1. GRANT
+
+You may install, use, copy and modify this software, and incorporate it into applications,
+prototypes, documents and presentations, for the purpose of building or operating Forest
+products, services and communications.
+
+This grant is free of charge and requires no separate agreement. It runs to anyone who
+obtains the software from a public registry.
+
+
+2. RESERVED
+
+All rights not granted above are reserved. In particular, you may not:
+
+  (a) redistribute this software, modified or unmodified, as a design system, component
+      library, template or theme of your own;
+
+  (b) use the HumanForest and Forest names, logos, wordmarks, sub-brand marks or any
+      confusingly similar mark. Nothing here grants any trademark right. The brand marks
+      included in these packages are provided to render Forest's own products correctly,
+      not as artwork you may adopt;
+
+  (c) represent your product as being made, endorsed or approved by HumanForest.
+
+
+3. THIRD-PARTY MATERIAL
+
+Parts of these packages are not HumanForest's to license, and the grant in section 1 does
+not extend to them. Each keeps its own terms:
+
+  TYPEFACES — Mohr and GT Haptik are licensed to HumanForest by their foundries and are NOT
+  sublicensed to you. No font binary is included in any published package. The stylesheets
+  reference https://assets.forest.bike/fonts/, which serves them to those entitled to use
+  them. If you are not covered by Forest's licences, substitute your own faces. JetBrains
+  Mono is licensed under the SIL Open Font License 1.1 and may be used under those terms.
+
+  GLYPH OUTLINES — packages/tokens ships `glyphs/glyphs.json`, letterforms of the above
+  typefaces outlined as vector paths so sub-brand lockups can be composed at runtime. It is
+  covered by the same foundry terms as the typefaces themselves, not by section 1.
+
+  DEVICE ARTWORK — packages/frames ships device renders from Wikimedia Commons under the
+  Creative Commons Attribution-ShareAlike 4.0 International licence
+  (https://creativecommons.org/licenses/by-sa/4.0/). They are unmodified. Attribution is a
+  condition of that licence: see ATTRIBUTION.md in that package, and keep it with the art
+  wherever the art travels. Works derived from the artwork must themselves be CC BY-SA 4.0.
+
+  DEPENDENCIES — third-party packages installed alongside these keep their own licences.
+
+
+4. NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+
+
+Questions about use beyond this grant: design@forest.bike

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@humanforest/charts",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./useChartPalette": "./src/useChartPalette.ts",
+    "./presets": "./src/presets.ts",
+    "./fromCategories": "./src/fromCategories.ts",
+    "./forestTooltip": "./src/forestTooltip.ts",
+    "./useChartRepaintKey": "./src/useChartRepaintKey.ts"
+  },
+  "peerDependencies": {
+    "vue": "^3.5",
+    "@unovis/vue": "^1.6.7",
+    "@nuxt/ui": "^4"
+  },
+  "devDependencies": {
+    "@unovis/ts": "^1.6.7",
+    "vue": "^3.5.22"
+  },
+  "dependencies": {
+    "@humanforest/tokens": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "SEE LICENSE IN LICENSE"
+}

package/src/FBoroughShape.vue

@@ -0,0 +1,52 @@
+<script setup lang="ts">
+// A single London borough as a styleable graphic — a glyph, not a chart. Where FLondonMap fills
+// shapes from data, this just hands you one shape, framed to itself, filled with currentColor. So
+// it colours like an icon: `class="text-primary"`, size with a width, add a border in CSS.
+//
+// Deliberately does one thing. No data, no ramp, no labels, no wards, no selection — the moment a
+// caller wants any of those they want FLondonMap. Keeping this presentational is the whole point.
+import { computed } from 'vue';
+import { LONDON_BOROUGHS, indexAreas } from './londonAreas';
+
+const props = withDefaults(
+  defineProps<{
+    /** Which borough: an ONS code (E09…) or a name, matched case-insensitively. */
+    borough: string;
+    /** Breathing room around the shape, as a fraction of its longer side. */
+    pad?: number;
+    /**
+     * Assistive text. With it the graphic is announced as an image; without it it is decorative and
+     * hidden from the accessibility tree — the same call an icon makes.
+     */
+    label?: string;
+  }>(),
+  { pad: 0.04 },
+);
+
+// Boroughs only — the ward set is loaded on demand elsewhere, and a glyph has no reason to pull it.
+const area = computed(() => indexAreas(LONDON_BOROUGHS.areas).get(props.borough.toLowerCase()));
+
+// Framed to the shape's own bounds, from the stored box — no path parsing. An unknown borough draws
+// nothing rather than a stray full-London frame.
+const viewBox = computed(() => {
+  const a = area.value;
+  if (!a) return undefined;
+  const p = Math.max(a.w, a.h) * props.pad;
+  return `${a.x - p} ${a.y - p} ${a.w + p * 2} ${a.h + p * 2}`;
+});
+</script>
+
+<template>
+  <svg
+    v-if="area"
+    :viewBox="viewBox"
+    xmlns="http://www.w3.org/2000/svg"
+    :role="label ? 'img' : undefined"
+    :aria-label="label"
+    :aria-hidden="label ? undefined : 'true'"
+  >
+    <!-- currentColor so a text-* class paints the fill; non-scaling-stroke keeps any border the
+         caller adds one hairline whatever the rendered size. -->
+    <path :d="area.d" fill="currentColor" vector-effect="non-scaling-stroke" />
+  </svg>
+</template>

package/src/FCalendarGrid.vue

@@ -0,0 +1,332 @@
+<script setup lang="ts" generic="D extends Record<string, unknown>">
+// Days as cells: weeks are columns, weekdays are rows. A year of ride volume, or a year of one
+// station's daily state. Colour resolution is useCellScale's; this component owns the calendar.
+//
+// The grid is built from the date window, not from the data, so a day with no datum is a real empty
+// cell in the right place rather than a missing column. Days are bucketed by local calendar date —
+// a timestamp is floored to its day before lookup, so two events on one day land together.
+import { computed, ref } from 'vue';
+import type { BulletLegendItemInterface } from '@unovis/ts';
+import { useCellScale, CELL_EMPTY_COLOR, type SequentialRamp } from './useCellScale';
+import { CELL_SIZES, orElse, type CellSize } from './cellSize';
+import FCellLegend from './FCellLegend.vue';
+
+const props = withDefaults(
+  defineProps<{
+    data: D[];
+    /** The day a datum belongs to. Any Date-parseable value. */
+    date: (d: D) => Date | number | string;
+    mode?: 'state' | 'intensity';
+    states?: Record<string, BulletLegendItemInterface>;
+    state?: (d: D) => string | null | undefined;
+    value?: (d: D) => number | null | undefined;
+    ramp?: SequentialRamp;
+    /** Intensity domain. Two grids compared side by side must both set it. */
+    domain?: [number, number];
+    steps?: number;
+    /** Window bounds. Default: the first and last dates present in the data. */
+    start?: Date;
+    end?: Date;
+    /** 0 = weeks start Sunday (default), 1 = Monday. */
+    weekStart?: 0 | 1;
+    /** Size step. Sets the cell dimensions, and whether labels, legend and tooltips default on:
+     *  xs and sm are too small to carry chrome, so it defaults off there. Any explicit prop wins. */
+    size?: CellSize;
+    /** Forces the size step's chrome decision either way — labels, legend and tooltips together.
+     *  `monthLabels`, `weekdayLabels` and `legend` still win over it individually. */
+    chrome?: boolean;
+    cellSize?: number;
+    cellGap?: number;
+    radius?: number;
+    monthLabels?: boolean;
+    /** Rule along the month boundary. It steps day by day, so a month opening midweek is cut where
+     *  it actually opens rather than at the column edge. */
+    monthSeparators?: boolean;
+    weekdayLabels?: boolean;
+    legend?: boolean;
+    /** Hover and focus text. Given one, cells become focusable buttons and get the house bubble.
+     *  Suppressed at xs and sm, where the target is too small to hit reliably. */
+    tooltip?: (d: D | undefined, date: Date) => string;
+    ariaLabel?: string;
+  }>(),
+  {
+    mode: 'intensity',
+    weekStart: 0,
+    size: 'md',
+    monthSeparators: false,
+    steps: 5,
+    /* Vue casts an ABSENT Boolean-typed prop to false, so without these the size step could never
+       switch chrome on: `orElse` would read that false as a deliberate "off" at every size. An
+       explicit undefined default is what keeps "not passed" distinguishable from "passed false". */
+    monthLabels: undefined,
+    weekdayLabels: undefined,
+    legend: undefined,
+    chrome: undefined,
+  },
+);
+
+// Three tiers, narrowest first: an individual prop beats `chrome`, which beats the size step.
+const spec = computed(() => CELL_SIZES[props.size]);
+const cellSize = computed(() => orElse(props.cellSize, spec.value.cell));
+const cellGap = computed(() => orElse(props.cellGap, spec.value.gap));
+const radius = computed(() => orElse(props.radius, spec.value.radius));
+const showChrome = computed(() => orElse(props.chrome, spec.value.chrome));
+const showMonthLabels = computed(() => orElse(props.monthLabels, showChrome.value));
+const showWeekdayLabels = computed(() => orElse(props.weekdayLabels, showChrome.value));
+const showLegend = computed(() => orElse(props.legend, showChrome.value));
+const interactive = computed(() => !!props.tooltip && showChrome.value);
+
+/** Local midnight — the calendar day is what a reader means, not the UTC instant. */
+const floorDay = (v: Date | number | string): Date => {
+  const d = new Date(v);
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate());
+};
+const keyOf = (d: Date) => `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}`;
+
+// Last datum wins for a day. Summing would silently change the reading into something the caller
+// never asked for; duplicates are the caller's to resolve.
+const byDay = computed(() => {
+  const m = new Map<string, D>();
+  for (const d of props.data) m.set(keyOf(floorDay(props.date(d))), d);
+  return m;
+});
+
+const bounds = computed<[Date, Date]>(() => {
+  if (props.start && props.end) return [floorDay(props.start), floorDay(props.end)];
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (const d of props.data) {
+    const t = floorDay(props.date(d)).getTime();
+    if (t < lo) lo = t;
+    if (t > hi) hi = t;
+  }
+  const today = floorDay(new Date());
+  const start = props.start ?? (Number.isFinite(lo) ? new Date(lo) : today);
+  const end = props.end ?? (Number.isFinite(hi) ? new Date(hi) : today);
+  return [floorDay(start), floorDay(end)];
+});
+
+/** Days back to the week boundary, so column 0 is a full week and rows line up with weekdays. */
+const leadingOffset = (d: Date) => (d.getDay() - props.weekStart + 7) % 7;
+
+const weeks = computed<{ date: Date; inRange: boolean }[][]>(() => {
+  const [start, end] = bounds.value;
+  const cursor = new Date(start);
+  cursor.setDate(cursor.getDate() - leadingOffset(start));
+  const out: { date: Date; inRange: boolean }[][] = [];
+  while (cursor <= end) {
+    const week: { date: Date; inRange: boolean }[] = [];
+    for (let i = 0; i < 7; i++) {
+      const day = new Date(cursor);
+      week.push({ date: day, inRange: day >= start && day <= end });
+      // setDate, not +86400000: a clocks-back day is 25 hours, so adding a fixed day and
+      // re-flooring lands on the same midnight and the walk never terminates.
+      cursor.setDate(cursor.getDate() + 1);
+    }
+    out.push(week);
+  }
+  return out;
+});
+
+const scale = useCellScale<D>({
+  mode: 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: props.value,
+  state: props.state,
+});
+
+const datumFor = (d: Date) => byDay.value.get(keyOf(d));
+const fillFor = (cell: { date: Date; inRange: boolean }) =>
+  cell.inRange ? scale.colorOf(datumFor(cell.date) ?? null) : 'transparent';
+
+const WEEKDAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+/** Mon, Wed, Fri only — labelling all seven crowds an 11px row. */
+const weekdayRows = computed(() =>
+  Array.from({ length: 7 }, (_, r) => {
+    const dayIndex = (r + props.weekStart) % 7;
+    return [1, 3, 5].includes(dayIndex) ? WEEKDAYS[dayIndex] : '';
+  }),
+);
+
+const monthLabel = (d: Date) => d.toLocaleDateString('en-GB', { month: 'short' });
+
+const pitch = computed(() => cellSize.value + cellGap.value);
+const gridWidth = computed(() => weeks.value.length * pitch.value - cellGap.value);
+const gridHeight = computed(() => 7 * pitch.value - cellGap.value);
+
+// Where each month opens, in grid coordinates. One source for both the label and the rule: the
+// label used to be placed on the week whose FIRST day fell in the new month, which puts it up to
+// six days late whenever a month opens midweek.
+const monthStarts = computed(() => {
+  const out: { wi: number; di: number; label: string; first: boolean }[] = [];
+  let prevMonth: number | null = null;
+  weeks.value.forEach((week, wi) => {
+    week.forEach((cell, di) => {
+      if (!cell.inRange) return;
+      const m = cell.date.getMonth();
+      if (prevMonth === null) out.push({ wi, di, label: monthLabel(cell.date), first: true });
+      else if (m !== prevMonth) out.push({ wi, di, label: monthLabel(cell.date), first: false });
+      prevMonth = m;
+    });
+  });
+  return out;
+});
+
+// The boundary between two months, as one continuous path each.
+//
+// Time runs down a column then into the next, so a month that opens midweek does NOT split its
+// column into left and right: the days above the opening row in every LATER column already belong
+// to the new month. The frontier is therefore a Z — down the right edge of the opening column to
+// the opening row, one column left, then down to the bottom — not a per-cell outline. A month
+// opening on the week-start row degenerates to a single straight vertical.
+//
+// Coordinates land on gap midpoints (w * pitch - cellGap/2), so the rule sits centred between two
+// cells rather than against either one, and one path per boundary welds its own corners.
+const monthPaths = computed(() => {
+  if (!props.monthSeparators) return '';
+  const half = cellGap.value / 2;
+  return monthStarts.value
+    .filter((m) => !m.first)
+    .map(({ wi, di }) => {
+      const xLeft = wi * pitch.value - half;
+      if (di === 0) return `M${xLeft},0V${gridHeight.value}`;
+      const xRight = (wi + 1) * pitch.value - half;
+      const yCut = di * pitch.value - half;
+      return `M${xRight},0V${yCut}H${xLeft}V${gridHeight.value}`;
+    })
+    .join(' ');
+});
+
+const dateLabel = (d: Date) => d.toLocaleDateString('en-GB', { day: 'numeric', month: 'short', year: 'numeric' });
+const labelFor = (cell: { date: Date }) => props.tooltip?.(datumFor(cell.date), cell.date) ?? '';
+
+const gridLabel = computed(() => {
+  const [start, end] = bounds.value;
+  return props.ariaLabel ?? `Daily values from ${dateLabel(start)} to ${dateLabel(end)}`;
+});
+
+// One UTooltip for the grid, re-anchored to the hovered cell through `reference`. A year is 371
+// cells; a tooltip root per cell would be 371 of them, so the anchor moves instead.
+//
+// `tipOpen` owns visibility; the text and the anchor are left alone on close. Clearing them
+// together with the flag emptied the bubble mid-exit-animation and dropped the anchor back to the
+// trigger, so leaving a segment flashed a blank pill at the container's centre for ~80ms.
+//
+// Anchored to the cell, not the pointer: a keyboard focus has no cursor to follow, and a bubble
+// that tracks the pointer inside an 11px target only jitters.
+const tip = ref<{ text: string; el: Element | null }>({ text: '', el: null });
+const tipOpen = ref(false);
+const showTip = (event: Event, text: string) => {
+  tip.value = { text, el: event.currentTarget as Element };
+  tipOpen.value = true;
+};
+const hideTip = () => {
+  tipOpen.value = false;
+};
+
+const hasEmpty = computed(() =>
+  weeks.value.some((w) => w.some((c) => c.inRange && scale.isEmpty(datumFor(c.date) ?? null))),
+);
+</script>
+
+<template>
+  <div class="flex w-full flex-col gap-3">
+    <div class="overflow-x-auto">
+      <div class="flex" :style="{ gap: `${cellGap}px` }">
+        <!-- Weekday gutter. justify-end pins the rows to the grid's bottom, so they line up
+             whether or not a month-label row sits above. -->
+        <div
+          v-if="showWeekdayLabels"
+          class="flex shrink-0 flex-col justify-end"
+          :style="{ gap: `${cellGap}px` }"
+        >
+          <span
+            v-for="(w, r) in weekdayRows"
+            :key="r"
+            class="type-caption flex items-center text-dimmed"
+            :style="{ height: `${cellSize}px`, lineHeight: `${cellSize}px` }"
+          >{{ w }}</span>
+        </div>
+
+        <div class="flex flex-col" :style="{ gap: `${cellGap}px` }">
+          <!-- Labels sit in their own row, positioned by column rather than living inside one, so
+               a long month name cannot widen its week and shove the cells apart. -->
+          <div
+            v-if="showMonthLabels"
+            class="relative h-5"
+            :style="{ width: `${gridWidth}px` }"
+            aria-hidden="true"
+          >
+            <span
+              v-for="m in monthStarts"
+              :key="`${m.wi}-${m.label}`"
+              class="type-caption absolute top-0 whitespace-nowrap text-dimmed"
+              :style="{ left: `${m.wi * pitch}px` }"
+            >{{ m.label }}</span>
+          </div>
+
+          <UTooltip :text="tip.text" :reference="tip.el" :open="tipOpen">
+          <div class="relative" :role="interactive ? 'group' : 'img'" :aria-label="gridLabel">
+            <div class="flex" :style="{ gap: `${cellGap}px` }">
+              <div v-for="(week, wi) in weeks" :key="wi" class="flex flex-col" :style="{ gap: `${cellGap}px` }">
+                <component
+                  :is="interactive && cell.inRange ? 'button' : 'div'"
+                  v-for="(cell, di) in week"
+                  :key="di"
+                  :type="interactive && cell.inRange ? 'button' : undefined"
+                  class="transition-[filter] duration-150 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--ui-primary)]"
+                  :class="interactive && cell.inRange ? 'cursor-pointer hover:brightness-110' : ''"
+                  :style="{
+                    width: `${cellSize}px`,
+                    height: `${cellSize}px`,
+                    borderRadius: `${radius}px`,
+                    background: fillFor(cell),
+                  }"
+                  :aria-label="interactive && cell.inRange ? labelFor(cell) : undefined"
+                  :aria-hidden="interactive && cell.inRange ? undefined : 'true'"
+                  @mouseenter="interactive && cell.inRange && showTip($event, labelFor(cell))"
+                  @mouseleave="hideTip"
+                  @focus="interactive && cell.inRange && showTip($event, labelFor(cell))"
+                  @blur="hideTip"
+                />
+              </div>
+            </div>
+
+            <!-- One path for every boundary, over the cells. pointer-events none so it never takes
+                 a hover from the cell beneath; crispEdges so a 1px rule stays 1px off-integer.
+                 Dimmed text rather than a border token: the border tokens sit around 1.5:1 on the
+                 page and vanish between saturated cells. -->
+
+            <svg
+              v-if="monthSeparators"
+              class="pointer-events-none absolute left-0 top-0 overflow-visible"
+              :width="gridWidth"
+              :height="gridHeight"
+              aria-hidden="true"
+            >
+              <path
+                :d="monthPaths"
+                fill="none"
+                stroke-width="1"
+                shape-rendering="crispEdges"
+                style="stroke: var(--ui-text-dimmed)"
+              />
+            </svg>
+          </div>
+          </UTooltip>
+        </div>
+      </div>
+    </div>
+
+    <FCellLegend
+      v-if="showLegend"
+      :legend="scale.legend.value"
+      :show-empty="hasEmpty"
+      :empty-color="CELL_EMPTY_COLOR"
+    />
+  </div>
+</template>

package/src/FCellLegend.vue

@@ -0,0 +1,54 @@
+<script setup lang="ts">
+// The legend both cell components share. Two shapes from one contract: named entries for state
+// mode, an unnamed Less → More ramp for intensity.
+//
+// The empty swatch appears only when the data actually has a gap. A legend that always advertised
+// "no data" would teach readers to look for a category that is usually absent.
+import type { CellLegend } from './useCellScale';
+
+withDefaults(
+  defineProps<{
+    legend: CellLegend;
+    showEmpty?: boolean;
+    emptyColor?: string;
+  }>(),
+  { showEmpty: false, emptyColor: 'var(--ui-bg-accented)' },
+);
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center gap-x-4 gap-y-2">
+    <template v-if="legend.mode === 'state'">
+      <span v-for="e in legend.entries" :key="e.key" class="flex items-center gap-1.5">
+        <span
+          class="size-2.5 rounded-full"
+          :style="{ background: e.swatch }"
+          aria-hidden="true"
+        />
+        <span class="type-caption text-default">{{ e.name }}</span>
+      </span>
+    </template>
+
+    <span v-else class="flex items-center gap-1.5">
+      <span class="type-caption text-dimmed">{{ legend.bounds?.[0] }}</span>
+      <span class="flex gap-0.5" aria-hidden="true">
+        <span
+          v-for="e in legend.entries"
+          :key="e.key"
+          class="size-2.5 rounded-[2px]"
+          :style="{ background: e.swatch }"
+        />
+      </span>
+      <span class="type-caption text-dimmed">{{ legend.bounds?.[1] }}</span>
+    </span>
+
+    <span v-if="showEmpty" class="flex items-center gap-1.5">
+      <span
+        class="size-2.5 rounded-[2px] ring-1 ring-[var(--ui-border)] ring-inset"
+        :style="{ background: emptyColor }"
+        aria-hidden="true"
+      />
+      <span class="type-caption text-dimmed">No data</span>
+    </span>
+  </div>
+</template>