@humanforest/ui 0.1.2 → 0.1.3

package/src/contexts/marketing-theme.ts

@@ -23,7 +23,7 @@
  * Button: keycap voice — rounder (lg), 2px edge, deeper lip with a bigger hover lift (rest −3px,
  * hover −5px; web md is −2/−3). Labels stay GT Haptik: Mohr is for headlines — the italic-Mohr
  * button label is the MOBILE voice, not marketing's. The base classes below re-voice the
- * edge/lip-bearing rungs (keycap, pad, framed, gloss, subtle, outline — they read --btn-edge /
+ * edge/lip-bearing rungs (keycap, pad, framed, subtle, outline — they read --btn-edge /
  * --btn-y*); the flat rungs (solid, soft, ghost, link) read neither and share the restrained web
  * rendering — bold delivery rides on the keycap/lg prop default (CONTEXTS-SPEC.md §6).
  *

package/src/filter/FFilterChip.vue

@@ -10,6 +10,7 @@
 // where the is/is-any-of promotion lives.
 import { computed, onMounted, ref, shallowRef } from 'vue';
 import { CalendarDate } from '@internationalized/date';
+import type { DateRange, DateValue } from 'reka-ui';
 import { filterTheme, type FilterSlot } from './filter.theme';
 import { OPERATOR_LABEL, operatorsFor, type FilterSchema, type Operator } from './filterSchema';
 import { isComplete, summariseClause, type Clause, type RelativeUnit } from './filterClause';
@@ -149,18 +150,35 @@ const onDateOpen = (open: boolean) => {
   if (open) dateKey.value += 1;
 };
 
-const onRangePicked = (range: { start?: CalendarDate; end?: CalendarDate } | undefined) => {
-  if (!range?.start || !range.end) return;
+/*
+  ⚠ THESE HANDLERS TAKE WHAT UCalendar EMITS, NOT WHAT THIS COMPONENT WANTS. They used to be typed
+  as the narrow shape the body reads — `{ start?: CalendarDate; end?: CalendarDate }` — which is a
+  SUBSET of the emitted `DateRange | null`, and a handler cannot be narrower than its emit. It type-
+  checked in this repo (nothing here typechecks packages/ui) and failed in every consumer's own
+  `vue-tsc`, against source they cannot edit.
+
+  So the parameter is the emitted type and the narrowing is explicit. `instanceof` rather than a
+  cast: the calendar can hand back a CalendarDateTime or a ZonedDateTime, and calendarToIso is only
+  correct for a plain date.
+*/
+const asCalendarDate = (value: unknown): CalendarDate | null =>
+  value instanceof CalendarDate ? value : null;
+
+const onRangePicked = (range: DateRange | null | undefined) => {
+  const start = asCalendarDate(range?.start);
+  const end = asCalendarDate(range?.end);
+  if (!start || !end) return;
   emit('update', {
-    value: [calendarToIso(range.start), calendarToIso(range.end)] as [string | null, string | null],
+    value: [calendarToIso(start), calendarToIso(end)] as [string | null, string | null],
   });
   dateOpen.value = false;
 };
 
 /** A single date is complete the moment it is picked, so the calendar closes behind it. */
-const onDatePicked = (picked: CalendarDate | undefined) => {
-  if (!picked) return;
-  emit('update', { value: calendarToIso(picked) });
+const onDatePicked = (picked: DateValue | DateValue[] | DateRange | null | undefined) => {
+  const date = asCalendarDate(picked);
+  if (!date) return;
+  emit('update', { value: calendarToIso(date) });
   dateOpen.value = false;
 };
 

package/src/kpi/FKpi.vue

@@ -9,7 +9,7 @@
 // registers itself, spans four subgrid rows, and may become a tab or a toggle.
 import { computed, inject, onBeforeUnmount, onMounted, useId, useSlots } from 'vue';
 import { kpiTheme, KPI_GROUP_KEY, type KpiSlot } from './kpi.theme';
-import { formatMetric, type KpiFormat } from './kpiFormat';
+import { formatMetric, joinCaption, type KpiFormat } from './kpiFormat';
 import { resolveDelta, type KpiDelta, type KpiSentiment } from './kpiDelta';
 
 const props = withDefaults(
@@ -117,16 +117,6 @@ const delta = computed(() =>
   }),
 );
 
-// Period first, then the baseline it was measured against — "last 7 days · vs previous 7 days".
-// The other order reads as one repeated phrase.
-const captionParts = computed(() =>
-  [
-    props.period,
-    props.delta ? `vs ${props.delta.comparisonLabel}` : undefined,
-    props.partial ? 'Period in progress' : undefined,
-  ].filter(Boolean),
-);
-
 const asOfText = computed(() => {
   if (!props.asOf) return undefined;
   const d = props.asOf instanceof Date ? props.asOf : new Date(props.asOf);
@@ -135,6 +125,21 @@ const asOfText = computed(() => {
     : `Updated ${new Intl.DateTimeFormat(props.locale ?? 'en-GB', { timeStyle: 'short' }).format(d)}`;
 });
 
+// Period first, then the baseline it was measured against — "last 7 days · vs previous 7 days".
+// The other order reads as one repeated phrase. `asOf` joins the SAME run so it gets a separator for
+// free; the caveat is the only part kept as its own element, because aria-describedby needs an id to
+// point at and a run of text cannot carry one.
+const captionLead = computed(() =>
+  isBlank.value && props.reason
+    ? REASON_COPY[props.reason]
+    : joinCaption(
+        props.period,
+        props.delta && `vs ${props.delta.comparisonLabel}`,
+        props.partial && 'Period in progress',
+        asOfText.value,
+      ),
+);
+
 const caveatId = computed(() => (props.caveat ? `${uid}-caveat` : undefined));
 
 const styles = computed(() =>
@@ -235,12 +240,8 @@ const onKeydown = (e: KeyboardEvent) => {
     </dd>
 
     <p :class="cls('caption')">
-      <slot name="caption">
-        <span v-if="isBlank && reason">{{ REASON_COPY[reason] }}</span>
-        <span v-else>{{ captionParts.join(' · ') }}</span>
-      </slot>
-      <span v-if="asOfText" class="ms-1">{{ asOfText }}</span>
-      <span v-if="caveat" :id="caveatId" class="ms-1">{{ caveat }}</span>
+      <slot name="caption">{{ captionLead }}</slot>
+      <span v-if="caveat" :id="caveatId">{{ captionLead ? ' · ' : '' }}{{ caveat }}</span>
     </p>
 
     <div v-if="$slots.visual" :class="cls('visual')"><slot name="visual" /></div>

package/src/kpi/FKpiGroup.vue

@@ -133,7 +133,7 @@ const gridStyle = computed(() =>
       :aria-orientation="selectable && !multiple ? orientation : undefined"
       class="grid grid-rows-[auto_auto_auto_auto] items-stretch"
       :class="[
-        divided ? 'gap-px bg-[var(--ui-border)]' : 'gap-4',
+        divided ? 'gap-px' : 'gap-4',
         // Ring outset, not inset: `divided` rules are this element's background through 1px gaps,
         // so the tiles sit flush to its border box and an inset stroke lands on them.
         divided && !flush && 'overflow-hidden rounded-lg ring-1 ring-default',
@@ -143,13 +143,21 @@ const gridStyle = computed(() =>
     >
       <!-- The dl is display:contents so the tiles join the grid directly, which also means it is
            the group's ONLY element child — a `divide-x` on the grid would target the dl and never
-           reach a tile. The hairlines are the grid's own 1px gaps showing the container's colour
-           through, which is the one treatment that stays correct when the row wraps: a `divide-*`
-           rule would draw a stray edge on the first tile of every wrapped row.
+           reach a tile. A `divide-*` rule is wrong for a second reason too: it would draw a stray
+           edge on the first tile of every wrapped row.
 
-           That colour is --ui-border, not bg-accented: these gaps read as the same rules as the
-           ring around the row, and accented sits several steps lighter, so the separators inside
-           the group came out brighter than the border enclosing them. -->
+           ★★ THE HAIRLINES ARE THE TILES' OWN RINGS MEETING IN THE 1px GAP, not this element's
+           background showing through. They were the background until a four-tile group on three
+           columns painted the two leftover cells as a filled grey slab — a ~460x130px rectangle at
+           every width from 768 to 1100px, iPad landscape included. A background cannot tell a seam
+           from an empty cell; a ring on the tile only exists where a tile does.
+
+           Tailwind's ring is an OUTSET box-shadow, so two neighbours each cast 1px into the same
+           1px gap and the seam is the same ink and the same geometry as before — `ring-default` is
+           --ui-border, which is what this comment used to insist the colour had to be: the gaps read
+           as the same rules as the ring around the row, where `bg-accented` sits several steps
+           lighter and came out brighter than the border enclosing it. `overflow-hidden` clips the
+           outer tiles' rings, so the perimeter stays the group's own single ring and never doubles. -->
       <dl class="contents">
         <slot />
       </dl>

package/src/kpi/kpi.theme.ts

@@ -54,10 +54,14 @@ export const kpiTheme = tv({
     // 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.
+    // The tile stays OPAQUE, and it draws its OWN seam: `ring-1 ring-default` is an outset
+    // box-shadow, so two neighbours each cast 1px into the group's 1px gap and meet as one hairline.
+    // The group used to paint --ui-border edge to edge and let the gaps show it through, which drew
+    // the same seam but could not tell a seam from an empty grid cell — four tiles on three columns
+    // left the two leftovers as a filled grey slab. Ink that lives on the tile exists only where a
+    // tile does. See FKpiGroup.vue.
     naked: {
-      true: { root: 'forest-kpi-joined bg-default shadow-none ring-0' },
+      true: { root: 'forest-kpi-joined bg-default shadow-none ring-1 ring-default' },
     },
     /**
      * How the `visual` slot meets the card. Two graphics, opposite needs, and the slot used to
@@ -133,7 +137,11 @@ export const kpiTheme = tv({
       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',
+        // ⚠ `ring-1 ring-default` AND NOT `ring-0`: the seam now lives on the tile, so cancelling
+        // the ring outright would punch a gap in the strip's hairlines around the selected segment.
+        // Both halves are needed — a bare `ring-1` loses the width fight but keeps `selected`'s
+        // primary colour, leaving a coloured seam.
+        root: 'ring-1 ring-default 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

package/src/kpi/kpiFormat.ts

@@ -70,3 +70,17 @@ export const formatPercent = (
     minimumFractionDigits: 0,
     maximumFractionDigits: precision,
   }).format(fraction);
+
+/**
+ * The caption's parts in reading order, joined by the tile's separator.
+ *
+ * ★★ EVERY PART GOES THROUGH HERE, which is the point. FKpi used to join three parts with ' · ' and
+ * then append `asOf` and `caveat` as bare sibling spans carrying only a 4px margin — so a tile given
+ * both a comparison label and a caveat rendered "vs previous quarterVerified with our partners", with
+ * no separator at all. The margin was never the fix: Vue's whitespace condense emits no text node
+ * between sibling spans, so `textContent` ran the words together and assistive tech read one word.
+ *
+ * Falsy parts drop out, so a tile carrying one part gets no stray leading or trailing dot.
+ */
+export const joinCaption = (...parts: (string | false | null | undefined)[]): string =>
+  parts.filter((p): p is string => !!p).join(' · ');

package/src/logo/FSubLogo.vue

@@ -9,7 +9,7 @@
 //
 // Variants: lockup (lead + keycap) · badge (keycap alone) · icon (square, first letter) · joined
 // (lead + sub-brand butted on as one word).
-import { computed } from 'vue';
+import { computed, useId } from 'vue';
 import { WORDMARK_PATHS, WORDMARK_W, WORDMARK_H } from '@humanforest/tokens/logo';
 import { setWord, runInk } from '@humanforest/tokens/glyphs';
 import {
@@ -91,7 +91,14 @@ const rect = computed(() => {
 
 // One clip per instance trims the flat ascenders. The id must be unique per mark — two lockups on a
 // page would otherwise share a def, and a downloaded file has to carry its own.
-const clipId = `fsub-cut-${++uid}`;
+//
+// ★★ useId(), NOT A MODULE COUNTER. Module state lives for the whole SSR process, so request N emits
+// `fsub-cut-N` while a freshly hydrating client always starts at 1. The server's markup is
+// internally consistent, so the mark looks right and only a hydration warning fires — but the client
+// vnode holds an id the document does not, and the first `variant` change to mount a new glyph group
+// points it at `url(#fsub-cut-1)`. That def does not exist, the ascender trim silently stops, and
+// GT's flat ascenders come back — which is the entire reason this clip exists.
+const clipId = `fsub-cut-${useId()}`;
 // the trim line: the t's ink top, which is where the drawn f stops
 const CUT_Y = setWord('t', { font: 'gt', size: SUBLOGO_GT_SIZE, baseline: SUBLOGO_BASELINE }).cutY;
 
@@ -127,11 +134,6 @@ const vars = computed(() => ({
 const label = computed(() => `${props.lead} ${word.value}`);
 </script>
 
-<script lang="ts">
-// module-scoped so every instance on a page gets its own clip id
-let uid = 0;
-</script>
-
 <template>
   <svg
     class="fsub" :viewBox="viewBox" :style="vars"

package/src/map/FVehicleMark.vue

@@ -1,13 +1,3 @@
-<script lang="ts">
-/**
- * ⚠ MODULE SCOPE, deliberately. `<script setup>` runs once PER INSTANCE, so a counter declared there resets
- * to the same value for every mark — every instance would take the id `fvm1`, and the gradient collision this
- * prefix exists to prevent would be back with extra steps.
- */
-let seq = 0;
-const nextUid = () => `fvm${(seq += 1)}`;
-</script>
-
 <script setup lang="ts">
 // FVehicleMark — one vehicle, drawn from its facts. NOT a map component.
 //
@@ -37,7 +27,7 @@ const nextUid = () => `fvm${(seq += 1)}`;
 //   <FMarker :lng-lat="v.at" selected interactive><FVehicleMark v-bind="v.facts" /></FMarker>
 // Usage anywhere else:
 //   <FVehicleMark state="FUNCTIONAL" battery="LOW" :size="28" />
-import { computed } from 'vue';
+import { computed, useId } from 'vue';
 import { MARKER_SVG } from './markerAsset';
 import manifest from '../../icons/forest/map/manifest.json';
 import {
@@ -114,7 +104,11 @@ const colour = (t: string) => resolveMapColor(`var(${t})`);
  * icon is its own document, and broken here: two of these on one page would both resolve `url(#inUse)` to the
  * first one's stops, so a list of vehicles would show the first row's gradient on every row.
  */
-const uid = nextUid();
+// ★★ useId() AND NOT A MODULE COUNTER. A module-scope counter does give every instance a distinct
+// id, which is what this needs — but it never resets under SSR, so the server writes `fvm7` into the
+// v-html'd asset where the hydrating client generates `fvm1`. useId() is stable across the pair and
+// still unique per instance, which is the whole requirement.
+const uid = useId();
 
 const artwork = computed(() => {
   void tokenMode.value;

package/src/themes/button.mechanics.ts

@@ -98,22 +98,29 @@ export const SOLID = [
   FOCUS,
 ].join(' ');
 
-export const GLOSS = [
-  // Web-only "gloss" emphasis — framed's lip outline with a line of light ONE pixel inside it along the
-  // top (the shine sits below the border, over the face — never on the border itself). The line is the
-  // face's OWN colour lightened (oklch l + --btn-shine-l, default 0.25), not white, so the sheen is
-  // on-brand per intent and works in both modes. Neutral's near-black face needs a bigger lift to read
-  // (PAL_NEUTRAL bumps --btn-shine-l to 0.5 in light; dark stays 0.25 — its near-white face would clip).
-  // One box-shadow, two inset layers: layer 1 (FRONT) the lip outline, --btn-edge
-  // wide; layer 2 (BEHIND) a light band offset calc(edge + 1px), so the outline covers its top `edge` px
-  // and only the next 1px shows. Both inset → footprint identical to framed.
-  'border-0 text-[var(--btn-ink)] bg-[var(--btn-face)]',
-  'shadow-[inset_0_0_0_var(--btn-edge,1px)_var(--btn-lip),inset_0_calc(var(--btn-edge,1px)_+_1px)_0_0_oklch(from_var(--btn-face)_calc(l_+_var(--btn-shine-l,0.25))_c_h)]',
-  // hover/press shift --btn-face itself (not just bg), so BOTH the fill and the shine (derived from
-  // --btn-face) track the current state — the line stays +0.25 lighter than whatever face is showing.
-  'hover:[--btn-face:var(--btn-hover)] active:[--btn-face:var(--btn-press)]',
-  FOCUS,
-].join(' ');
+/*
+  GLOSS IS GONE, AND IT IS WORTH KNOWING WHY BEFORE BRINGING IT BACK.
+
+  It was a web-only emphasis: framed's lip outline with a line of light one pixel inside the top,
+  drawn as the face's OWN colour lightened in-gamut —
+    oklch(from var(--btn-face) calc(l + var(--btn-shine-l,0.25)) c h)
+  — so the sheen stayed on-brand per intent and worked in both modes. Switched off in d6e99218
+  (2026-07-08) and never switched back, which left two faults standing:
+
+  · `variant: { gloss: '' }` stayed in the enum with no compound to style it, so
+    <UButton variant="gloss"> type-checked, rendered, and looked like nothing at all.
+  · it was the ONLY relative-colour construct in the shipped surface, and postcss-calc's Jison
+    grammar has no term for a bare channel keyword — so every consumer's production build logged
+      Lexical error on line 1: Unrecognized text … l + var(--btn-shine-l,.25)
+    The declaration survived into the CSS, so it was cosmetic; it also fails any build treating
+    warnings as errors, and it fired for everyone.
+
+  REVIVING IT: the arithmetic is load-bearing and must stay channel arithmetic — `color-mix(… white)`
+  drags chroma to zero and desaturates the line. To keep the warning away, write the sum as
+  `max(l + var(--btn-shine-l,0.25), 0)`: measured identical to the last decimal in Chromium across a
+  dark face, neutral-900 at shine 0.5 and neutral-50, because L can never go under 0 — it simply
+  drops the `calc` token the lexer chokes on.
+*/
 
 export const SUBTLE = [
   // A ramp-pinned INSET RING (a box-shadow, not a border → no added height) over a plain surface fill.
@@ -184,7 +191,10 @@ export const PAL_SECONDARY = '[--btn-face:var(--warm-500)] dark:[--btn-face:var(
 // outline hover edge stays monochrome instead of leaking brand green via the shared --btn-ring.
 // Rest --btn-line is 300/700 (not the ramp's 400/600) to match UInput's resting border
 // (ring-accented → --ui-border-accented = neutral-300/700), so a neutral button sits flush with a field.
-export const PAL_NEUTRAL = '[--btn-face:var(--neutral-900)] dark:[--btn-face:var(--neutral-50)] [--btn-hover:var(--neutral-800)] dark:[--btn-hover:var(--neutral-100)] [--btn-press:var(--neutral-700)] dark:[--btn-press:var(--neutral-200)] [--btn-lip:var(--neutral-400)] dark:[--btn-lip:var(--neutral-300)] [--btn-ring:var(--neutral-500)] [--btn-t1:var(--neutral-50)] dark:[--btn-t1:var(--neutral-950)] [--btn-t2:var(--neutral-100)] dark:[--btn-t2:var(--neutral-900)] [--btn-t3:var(--neutral-200)] dark:[--btn-t3:var(--neutral-800)] [--btn-line:var(--neutral-300)] dark:[--btn-line:var(--neutral-700)] [--btn-text:var(--neutral-900)] dark:[--btn-text:var(--neutral-100)] [--btn-ink:var(--neutral-0)] dark:[--btn-ink:var(--neutral-900)] [--btn-shine-l:0.5] dark:[--btn-shine-l:0.25]';
+// --btn-shine-l went with GLOSS: neutral's near-black face needed a bigger lift than 0.25 to read,
+// and nothing reads the variable now. It was still emitting two dead utility classes into every
+// consumer's stylesheet. Restore both halves (0.5 light / 0.25 dark) if gloss ever comes back.
+export const PAL_NEUTRAL = '[--btn-face:var(--neutral-900)] dark:[--btn-face:var(--neutral-50)] [--btn-hover:var(--neutral-800)] dark:[--btn-hover:var(--neutral-100)] [--btn-press:var(--neutral-700)] dark:[--btn-press:var(--neutral-200)] [--btn-lip:var(--neutral-400)] dark:[--btn-lip:var(--neutral-300)] [--btn-ring:var(--neutral-500)] [--btn-t1:var(--neutral-50)] dark:[--btn-t1:var(--neutral-950)] [--btn-t2:var(--neutral-100)] dark:[--btn-t2:var(--neutral-900)] [--btn-t3:var(--neutral-200)] dark:[--btn-t3:var(--neutral-800)] [--btn-line:var(--neutral-300)] dark:[--btn-line:var(--neutral-700)] [--btn-text:var(--neutral-900)] dark:[--btn-text:var(--neutral-100)] [--btn-ink:var(--neutral-0)] dark:[--btn-ink:var(--neutral-900)]';
 
 // All seven intents share the colour-keyed solid/flat/outline/soft/ghost classes.
 export const ALL = ['primary', 'secondary', 'success', 'info', 'warning', 'error', 'neutral'];

package/src/themes/button.ts

@@ -70,7 +70,6 @@ export const buttonTheme = {
       keycap: '',
       pad: '',
       framed: '',
-      gloss: '',
       subtle: '',
       link: '',
     },
@@ -114,7 +113,6 @@ export const buttonTheme = {
     ...emphasis('keycap', KEYCAP),
     ...emphasis('pad', PAD),
     ...emphasis('framed', FRAMED),
-    // ...emphasis('gloss', GLOSS),
     ...emphasis('solid', SOLID),
     ...emphasis('subtle', SUBTLE),
     ...emphasis('soft', SOFT),