@humanforest/nuxt-layer 0.1.0

package/packages/ui/src/kpi/index.ts

@@ -0,0 +1,20 @@
+// Forest's KPI card — one entry, matching ./map.
+//
+//   <FKpi>            one metric: value, optional delta, optional sparkline visual
+//   <FKpiGroup>       a subgrid-aligned row of FKpi, optionally acting as a tablist selector
+//   formatMetric()    Intl-backed value formatting (never pin maximumFractionDigits on compact)
+export { default as FKpi } from './FKpi.vue';
+export { default as FKpiGroup } from './FKpiGroup.vue';
+
+export type { KpiSlot, KpiGroupContext } from './kpi.theme';
+
+export { formatMetric, formatPercent } from './kpiFormat';
+export type { KpiFormat, FormatOpts } from './kpiFormat';
+
+export type { KpiDelta, KpiSentiment, ResolvedDelta } from './kpiDelta';
+
+export {
+  nextKey,
+  isSelected,
+} from './kpiGroupState';
+export type { KpiRegistry } from './kpiGroupState';

package/packages/ui/src/kpi/kpi.theme.ts

@@ -0,0 +1,168 @@
+// Presentation for FKpi. The surface comes from UCard — this recipe owns only what sits inside it.
+//
+// The value's type size is a container query on the tile itself, not a `size` prop. A tile in a
+// narrow column is narrow, and the number should follow the space it has rather than a breakpoint
+// the author guessed at.
+//
+// Row alignment is subgrid: inside a group the tile spans four rows of the group's grid, so labels,
+// values, captions and visuals line up across the row however long any one label runs.
+import type { InjectionKey } from 'vue';
+import { tv } from 'tailwind-variants';
+import type { KpiFormat } from './kpiFormat';
+
+export const kpiTheme = tv({
+  slots: {
+    // The card's own body is display:contents so the four parts can join the group's subgrid, which
+    // means the padding has to live here instead. p-4 is the card's own uniform figure.
+    // Padding rides --forest-card-pad, the same var the card's concentric-radius maths reads: the
+    // rounder the card, the roomier the inset, and a context that steps one steps both (1rem at
+    // rest, 1.25rem in mobile and marketing). A hardcoded p-4 would leave the tile tight inside a
+    // 32px-radius card. The card's own body padding is display:contents here, so this is the only
+    // padding on the tile.
+    //
+    // One explicit minmax(0,1fr) column: without it the implicit column sizes to max-content, and a
+    // chart with an intrinsic width (Unovis defaults to 300px) makes the tile's own grid wider than
+    // the tile, clipping the right end of the graphic.
+    root: 'relative grid grid-cols-[minmax(0,1fr)] grid-rows-[auto_auto_auto_auto] gap-1 p-[var(--forest-card-pad)] @container/kpi',
+    header: 'flex min-w-0 items-center gap-1.5',
+    label: 'type-overline truncate text-muted',
+    hint: 'shrink-0 text-dimmed',
+    body: 'flex flex-wrap items-baseline gap-x-2 gap-y-1',
+    // Face and transform ride the --fx-metric traits, so a context re-points them on the card root
+    // and the figure follows — the same channel the card title uses for --fx-title. tabular-nums is
+    // unconditional: it does what it can on the sans cut and is inert on Mohr, which has no tnum.
+    metric:
+      '[font-family:var(--fx-metric-family)] [text-transform:var(--fx-metric-transform)] font-bold tabular-nums text-2xl leading-none text-highlighted @[14rem]/kpi:text-3xl @[20rem]/kpi:text-4xl',
+    prefix: 'text-muted',
+    suffix: 'text-sm text-muted',
+    // Bare text on the figure's baseline, not a filled chip. A container makes the delta a second
+    // object beside the number: at a comfortable size it competes with the figure it modifies, and
+    // shrunk out of the way it stops being readable. Without one it sizes off the figure — one step
+    // down through the same container query — and the arrow plus the colour carry the meaning.
+    delta: 'inline-flex shrink-0 items-center gap-0.5 font-bold text-xs @[14rem]/kpi:text-sm @[20rem]/kpi:text-base',
+    deltaIcon: 'size-3.5 shrink-0 @[20rem]/kpi:size-4',
+    caption: 'text-xs text-dimmed',
+    // Fit comes from the visualFit variant — a sparkline and a legend want opposite treatments.
+    // Common to both: neither min-h-0 nor overflow-hidden, since both zero this element's
+    // contribution to the subgrid track, collapsing the row so the graphic overflows upward onto
+    // the caption. The tile root already clips, which is what the rounded bottom corners needed.
+    visual: 'mt-2',
+    footer: 'mt-2',
+  },
+  variants: {
+    // Inside a divided row the group draws the borders, so the tile drops its own fill, ring and
+    // radius. Keeping the radius would round each segment's fill inside a joined strip and leave
+    // the selected tile's underline looking detached at both ends; the group's own container
+    // supplies the outer corners.
+    // The tile stays OPAQUE: the group's hairlines are its own 1px grid gaps showing the container
+    // colour through, so a transparent tile would leak that colour across the whole strip.
+    naked: {
+      true: { root: 'forest-kpi-joined bg-default shadow-none ring-0' },
+    },
+    /**
+     * How the `visual` slot meets the card. Two graphics, opposite needs, and the slot used to
+     * carry only the first — which left every other visual undoing it with utilities at the call
+     * site.
+     *
+     * `bleed` (the default) is for a graphic that IS data and nothing else, a sparkline being the
+     * case: it runs through the tile's gutter to both side edges and sits on the bottom edge, which
+     * the tile reaches by zeroing its own bottom padding rather than by a negative margin — a
+     * margin would shrink the grid row and pull the graphic up over the caption.
+     *
+     * `inset` is for a graphic carrying text, FDistributionBar's legend being the case. Text set
+     * against the card's edge reads as a mistake, so the padding stays. It also top-aligns, and
+     * pins the tile's rows to the top with `content-start`: the tile is a subgrid item WITH
+     * padding, so its four tracks are re-sized inside its own content box rather than inheriting
+     * the group's positions. Two tiles then distribute their slack differently — a legend that
+     * wraps in one and not its neighbour leaves the two bars at different heights — and packing
+     * the rows to the top is what makes them agree. Measured: 15.6px apart without it, level with.
+     */
+    visualFit: {
+      bleed: { root: 'pb-0', visual: 'self-end -mx-[var(--forest-card-pad)]' },
+      inset: { root: 'content-start', visual: 'self-start' },
+    },
+    aligned: {
+      true: { root: 'row-span-4 grid-rows-subgrid' },
+    },
+    selectable: {
+      true: {
+        root: 'cursor-pointer text-left transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary',
+      },
+    },
+    // Selected, hover and focus are three separate treatments.
+    selected: {
+      true: { root: 'ring-2 ring-primary', label: 'text-highlighted' },
+    },
+    hovered: {
+      true: { root: 'hover:bg-elevated' },
+    },
+    status: {
+      ok: {},
+      warn: { metric: 'text-warning' },
+      critical: { metric: 'text-error' },
+    },
+    emphasis: {
+      value: {},
+      surface: {},
+    },
+    dimmed: {
+      true: { metric: 'text-muted' },
+    },
+    /** Colour states judgement; the arrow always states direction, so neutral is not a failure. */
+    intent: {
+      success: { delta: 'text-success' },
+      error: { delta: 'text-error' },
+      neutral: { delta: 'text-muted' },
+    },
+    /**
+     * Forces a face, overriding whatever the context's --fx-metric traits say. For the exception:
+     * a hero figure on a web page that wants the expressive cut, or a mobile table of figures that
+     * has to align despite the context. Leave unset and the context decides.
+     */
+    face: {
+      tabular: { metric: '[font-family:var(--font-sans)] [text-transform:none]' },
+      display: { metric: '[font-family:var(--font-display)] [text-transform:uppercase]' },
+    },
+  },
+  compoundVariants: [
+    // An attached strip marks selection with an underline on the shared edge, not a ring: a ring
+    // around one segment of a joined row draws a box that the row's own border already drew, and
+    // the two fight. The bar sits on the same edge the chart hangs off, so the tile reads as the
+    // chart's tab rather than as a card that happens to be highlighted.
+    {
+      naked: true,
+      selected: true,
+      class: {
+        root: 'ring-0 bg-elevated after:absolute after:inset-x-0 after:-bottom-px after:h-0.5 after:bg-primary',
+      },
+    },
+    // Surface-painting reaches for the tinted card variants. There is no red accent, so a critical
+    // tile paints amber and the value's own colour carries the rest.
+    { emphasis: 'surface', status: 'warn', class: { root: 'bg-[var(--forest-card-amber-bg)]' } },
+    { emphasis: 'surface', status: 'critical', class: { root: 'bg-[var(--forest-card-amber-bg)]' } },
+  ],
+  defaultVariants: {
+    status: 'ok',
+    emphasis: 'value',
+  },
+});
+
+export type KpiSlot = keyof ReturnType<typeof kpiTheme>;
+
+export interface KpiGroupContext {
+  register(key: string): void;
+  unregister(key: string): void;
+  select(key: string): void;
+  focusStep(key: string, step: 1 | -1): void;
+  isSelected(key: string): boolean;
+  /** Roving tabindex: exactly one tile in the row is in the tab order. */
+  isFocusable(key: string): boolean;
+  selectable: boolean;
+  multiple: boolean;
+  controls?: string;
+  format?: KpiFormat;
+  precision?: number;
+  naked: boolean;
+}
+
+export const KPI_GROUP_KEY: InjectionKey<KpiGroupContext> = Symbol('forest-kpi-group');

package/packages/ui/src/kpi/kpiDelta.ts

@@ -0,0 +1,82 @@
+// Delta resolution. The arrow carries literal direction; the colour carries judgement, and only
+// when the author has declared which way is better. Default is neutral: a bare number that has
+// gone up is not, on its own, good news.
+//
+// The delta is never derived from a sparkline's own series — it is supplied, with the baseline it
+// was measured against, or it is absent.
+import { formatMetric, formatPercent } from './kpiFormat';
+
+export type KpiSentiment = 'higher-is-better' | 'lower-is-better' | 'neutral';
+
+export interface KpiDelta {
+  value: number;
+  /** `percent` takes a fraction (0.12 = 12%). `pp` and `absolute` take the figure as written. */
+  unit: 'percent' | 'pp' | 'absolute';
+  display?: 'relative' | 'absolute' | 'both' | 'none';
+  /** What the value was compared against. Required — an undisclosed baseline is unreadable. */
+  comparisonLabel: string;
+  previous?: number;
+}
+
+export interface ResolvedDelta {
+  text: string;
+  direction: 'up' | 'down' | 'flat';
+  intent: 'success' | 'error' | 'neutral';
+  /** Visually hidden, and the only place direction is stated in words. */
+  sentence: string;
+  hidden: boolean;
+}
+
+const DEFAULT_LOCALE = 'en-GB';
+
+/** Below this the figure has not moved in any way a reader should act on. */
+const FLAT_EPSILON = 0.0005;
+
+export const resolveDelta = (
+  delta: KpiDelta | undefined,
+  {
+    sentiment = 'neutral',
+    locale = DEFAULT_LOCALE,
+    precision,
+  }: { sentiment?: KpiSentiment; locale?: string; precision?: number } = {},
+): ResolvedDelta | null => {
+  if (!delta) return null;
+
+  const { value, unit, comparisonLabel, previous, display = 'relative' } = delta;
+
+  // A relative change against a zero baseline is undefined, so the absolute figure stands in.
+  const relativeIsMeaningless = previous === 0 && value !== 0;
+  const effectiveUnit = unit === 'percent' && relativeIsMeaningless ? 'absolute' : unit;
+
+  const magnitude = Math.abs(value);
+  const direction = magnitude < FLAT_EPSILON ? 'flat' : value > 0 ? 'up' : 'down';
+
+  const intent: ResolvedDelta['intent'] =
+    direction === 'flat' || sentiment === 'neutral'
+      ? 'neutral'
+      : (direction === 'up') === (sentiment === 'higher-is-better')
+        ? 'success'
+        : 'error';
+
+  const sign = direction === 'up' ? '+' : direction === 'down' ? '-' : '';
+
+  const magnitudeText =
+    effectiveUnit === 'percent'
+      ? formatPercent(magnitude, { locale, precision })
+      : effectiveUnit === 'pp'
+        ? `${formatMetric(magnitude, { locale, precision })}pp`
+        : formatMetric(magnitude, { locale, precision });
+
+  const text = `${sign}${magnitudeText}`;
+
+  const spoken =
+    direction === 'flat' ? 'No change' : direction === 'up' ? `Up ${magnitudeText}` : `Down ${magnitudeText}`;
+
+  return {
+    text,
+    direction,
+    intent,
+    sentence: `${spoken}, versus ${comparisonLabel}.`,
+    hidden: display === 'none',
+  };
+};

package/packages/ui/src/kpi/kpiFormat.ts

@@ -0,0 +1,72 @@
+// Number formatting for KPI tiles. Pure Intl, no Vue — the component renders what this returns.
+//
+// Three Intl behaviours drive the shape of this file. Compact notation rounds halfExpand by
+// default, so 999,999 renders as "1M"; it also flips useGrouping to "min2" behind your back, so a
+// shared options object corrupts the full path; and style:'percent' defaults to zero fraction
+// digits, quietly discarding the precision the caller asked for.
+
+export type KpiFormat = 'full' | 'compact' | ((v: number) => string);
+
+export interface FormatOpts {
+  format?: KpiFormat;
+  precision?: number;
+  locale?: string;
+  noValue?: string;
+}
+
+const DEFAULT_LOCALE = 'en-GB';
+const DEFAULT_NO_VALUE = '—';
+
+/** `roundingMode` is ES2023 and absent from the TypeScript lib this repo compiles against. */
+type NumberFormatOptions = Intl.NumberFormatOptions & { roundingMode?: 'trunc' | 'halfExpand' };
+
+// Compact suffixes are house style, not ICU's: lowercase, with the British "bn"/"tn". ICU's en data
+// returns "K"/"M"/"B"/"T", so the suffix is mapped rather than taken as formatted — the rendered
+// glyph is a design decision and must not move with the runtime's CLDR data. Locales ICU
+// abbreviates some other way ("Mrd." in de-DE) fall through unchanged.
+const COMPACT_SUFFIX: Record<string, string> = { K: 'k', M: 'm', B: 'bn', T: 'tn' };
+
+export const formatMetric = (
+  metric: number | null | undefined,
+  { format = 'full', precision, locale = DEFAULT_LOCALE, noValue = DEFAULT_NO_VALUE }: FormatOpts = {},
+): string => {
+  if (metric === null || metric === undefined || Number.isNaN(metric)) return noValue;
+  if (typeof format === 'function') return format(metric);
+
+  if (format === 'compact') {
+    const opts: NumberFormatOptions = {
+      notation: 'compact',
+      compactDisplay: 'short',
+      roundingMode: 'trunc',
+      // No explicit fraction digits when the caller gave none: Intl's compact default is two
+      // significant digits, which is what renders 1,200 as "1.2k" and 999,999 as "999k". Pinning
+      // maximumFractionDigits here overrides that and gives "999.9k".
+      ...(precision === undefined
+        ? {}
+        : { minimumFractionDigits: precision, maximumFractionDigits: precision }),
+    };
+    return new Intl.NumberFormat(locale, opts)
+      .formatToParts(metric)
+      .map((part) => (part.type === 'compact' ? (COMPACT_SUFFIX[part.value] ?? part.value) : part.value))
+      .join('');
+  }
+
+  // Built fresh rather than shared with the compact branch: compact silently switches grouping to
+  // "min2", so one reused options object would drop the separator from 1,000 on this path.
+  return new Intl.NumberFormat(locale, {
+    ...(precision === undefined
+      ? {}
+      : { minimumFractionDigits: precision, maximumFractionDigits: precision }),
+  }).format(metric);
+};
+
+/** A fraction (0.034) as a percentage string. Precision is explicit because Intl's default is zero. */
+export const formatPercent = (
+  fraction: number,
+  { locale = DEFAULT_LOCALE, precision = 1 }: { locale?: string; precision?: number } = {},
+): string =>
+  new Intl.NumberFormat(locale, {
+    style: 'percent',
+    minimumFractionDigits: 0,
+    maximumFractionDigits: precision,
+  }).format(fraction);

package/packages/ui/src/kpi/kpiGroupState.ts

@@ -0,0 +1,63 @@
+// Selection and focus order for a row of KPI tiles, with no Vue in it so the rules are testable
+// on their own.
+//
+// Registration order — not DOM order — decides arrow-key order. Tiles register on mount, so the
+// two agree, and a v-for that reorders re-registers.
+
+export interface KpiRegistry {
+  register(key: string): void;
+  unregister(key: string): void;
+  keys(): string[];
+}
+
+export const createKpiRegistry = (): KpiRegistry => {
+  const order: string[] = [];
+  return {
+    register(key) {
+      if (!order.includes(key)) order.push(key);
+    },
+    unregister(key) {
+      const i = order.indexOf(key);
+      if (i !== -1) order.splice(i, 1);
+    },
+    keys: () => [...order],
+  };
+};
+
+/** The tile an arrow key moves focus to. Wraps, per the tabs pattern. */
+export const nextKey = (keys: string[], current: string | undefined, step: 1 | -1): string | undefined => {
+  if (!keys.length) return undefined;
+  const i = current === undefined ? -1 : keys.indexOf(current);
+  if (i === -1) return step === 1 ? keys[0] : keys[keys.length - 1];
+  return keys[(i + step + keys.length) % keys.length];
+};
+
+export const isSelected = (current: string | string[] | undefined, key: string): boolean =>
+  Array.isArray(current) ? current.includes(key) : current === key;
+
+/**
+ * Single mode replaces and never empties — a tab row with nothing selected has no panel to show.
+ * Multiple mode toggles, and may empty: an overlay chart with no series is a legible state.
+ */
+export const toggleSelection = (
+  current: string | string[] | undefined,
+  key: string,
+  multiple: boolean,
+): string | string[] => {
+  if (!multiple) return key;
+  const list = Array.isArray(current) ? current : current ? [current] : [];
+  return list.includes(key) ? list.filter((k) => k !== key) : [...list, key];
+};
+
+/** Drops selections naming tiles that are no longer in the row, then falls back. */
+export const resolveInitial = (
+  keys: string[],
+  model: string | string[] | undefined,
+  fallback: string | undefined,
+): string | string[] | undefined => {
+  if (!keys.length) return undefined;
+  if (Array.isArray(model)) return model.filter((k) => keys.includes(k));
+  if (model !== undefined && keys.includes(model)) return model;
+  if (fallback !== undefined && keys.includes(fallback)) return fallback;
+  return keys[0];
+};

package/packages/ui/src/logo/FLogo.vue

@@ -0,0 +1,52 @@
+<script setup lang="ts">
+// The Forest logo, composed live from the primitives in @humanforest/tokens — the same source the generated
+// SVGs use. One component for every variant; theme-adaptive (the square is forest-700, the ink — ring
+// + inner + wordmark — flows from currentColor, so a parent text colour drives light/dark). `size` is
+// the rendered height in px; width follows the variant's aspect ratio.
+import { computed } from 'vue';
+import { MARK, MARK_SIZE, WORDMARK_PATHS, WORDMARK_W, WORDMARK_H, LOCKUP_H, LOCKUP_V, F } from '@humanforest/tokens/logo';
+
+// `clearspace`: bake the exclusion zone into the SVG as transparent margin. true = one f on every
+// side (the brand rule); a number = that many f. `size` stays the logo's own height — the SVG just
+// grows to include the margin, so the logo never shrinks when you turn clear space on.
+const props = withDefaults(defineProps<{ variant?: 'lockup-h' | 'lockup-v' | 'wordmark' | 'mark'; size?: number; clearspace?: boolean | number }>(), {
+  variant: 'lockup-h', size: 64, clearspace: false,
+});
+
+const LAYOUT = {
+  'lockup-h': { vb: LOCKUP_H.vb, mark: LOCKUP_H.mark, word: LOCKUP_H.word },
+  'lockup-v': { vb: LOCKUP_V.vb, mark: LOCKUP_V.mark, word: LOCKUP_V.word },
+  mark: { vb: [MARK_SIZE, MARK_SIZE] as const, mark: [0, 0] as const, word: null },
+  wordmark: { vb: [WORDMARK_W, WORDMARK_H] as const, mark: null, word: [0, 0] as const },
+} as const;
+
+const layout = computed(() => LAYOUT[props.variant]);
+// one f of clear space, in artwork units (F.h ≈ 0.454 × mark height — the same module the diagram uses)
+const pad = computed(() => (props.clearspace === true ? 1 : props.clearspace === false ? 0 : props.clearspace) * F.h);
+const viewBox = computed(() => {
+  const [w, h] = layout.value.vb, p = pad.value;
+  return `${-p} ${-p} ${w + 2 * p} ${h + 2 * p}`;
+});
+// grow the rendered height to include the margins so `size` keeps meaning the logo's own height
+const renderH = computed(() => { const h = layout.value.vb[1]; return props.size * (h + 2 * pad.value) / h; });
+const xf = (t: readonly [number, number] | null) => (t ? `translate(${t[0]} ${t[1]})` : undefined);
+</script>
+
+<template>
+  <svg
+    :viewBox="viewBox" :style="{ height: `${renderH}px`, width: 'auto' }"
+    fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"
+  >
+    <!-- mark: green square + reversing ink ring + white tree + fixed-dark inner -->
+    <g v-if="layout.mark" :transform="xf(layout.mark)">
+      <path :d="MARK.square" fill="var(--color-forest-700)" />
+      <path :d="MARK.ring" fill="currentColor" />
+      <path :d="MARK.tree" fill="white" />
+      <path :d="MARK.inner" fill="var(--color-forest-950)" />
+    </g>
+    <!-- wordmark: the ink, follows the theme via currentColor -->
+    <g v-if="layout.word" :transform="xf(layout.word)">
+      <path v-for="(d, i) in WORDMARK_PATHS" :key="i" :d="d" fill="currentColor" />
+    </g>
+  </svg>
+</template>