@humanforest/ui 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanforest/ui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "files": [
     "src",
@@ -9,7 +9,7 @@
     "preset.gen.js"
   ],
   "dependencies": {
-    "@humanforest/tokens": "^0.2.0",
+    "@humanforest/tokens": "^0.3.0",
     "@internationalized/date": "^3.12.2",
     "@mapbox/search-js-core": "^1.6.0",
     "@turf/boolean-point-in-polygon": "^7.4.0",
@@ -30,6 +30,7 @@
     "./map-search-coordinates": "./src/map/sources/coordinates.ts",
     "./address": "./src/address/index.ts",
     "./canvas": "./src/canvas/index.ts",
+    "./card": "./src/card/index.ts",
     "./kpi": "./src/kpi/index.ts",
     "./logo": "./src/logo/index.ts",
     "./shell": "./src/shell/index.ts",

package/src/card/FInsetCard.vue

@@ -0,0 +1,237 @@
+<script setup lang="ts">
+// A card whose body is an INSET BOX: the box carries the content, and the card's own ground shows
+// as ONE strip — a header above it or a footer below, never both. For dashboard tiles.
+//
+//   <FInsetCard>              …a chart…   <template #footer>…</template>   </FInsetCard>
+//   <FInsetCard :gap="4">     …a chart…   <template #header>…</template>   </FInsetCard>
+//   <FInsetCard bare>         <template #default="{ boxUi }"> <FKpi :ui="boxUi" … />
+//
+// ★ WHY A WRAPPER, NOT A CARD VARIANT. Card variants are a FILL axis (soft/outline/subtle/solid +
+// the tints). "Inset box" is a composition, and making it a variant would put its blast radius on
+// every card in the system. Same reasoning as FlushCard, which is the other end of this axis: it
+// zeroes the body padding so a table runs to the card's edge; this one shrinks it to a visible gap.
+//
+// ★ THE GAP IS ONE VALUE DOING THREE JOBS. Setting --forest-card-pad drives (a) the body padding,
+// so the box is inset by it, (b) the concentric radius, because forest.css derives a nested card's
+// corner as `outer − pad`, and (c) FKpi's bleed margin, which pulls by the same var. Set it once
+// here and all three stay in step; set the padding with a class instead and they silently diverge.
+//
+// ★ THE BODY DROPS ITS PADDING ON THE SIDE THE STRIP IS ON. The box is inset on three sides; on the
+// fourth it meets the strip directly, and the strip owns all the space there. Two consequences, both
+// load-bearing: the box's edge lands flush against the strip (as it does in the reference), and the
+// strip's `pt` and `pb` can then be EQUAL and actually read equal. Leave the body padding on and it
+// stacks — the label sits `gap + pt` from the box but only `pb` from the card edge, which is the
+// lopsided look this pattern kept producing.
+//
+// ★ THE STRIP RESTATES ITS PADDING UNDER THE FRAGMENT'S OWN VARIANT. Forest's `flatGap` carries
+// `footer: '[&:not(:first-child)]:pt-0'` / `header: '[&:not(:last-child)]:pb-0'` to collapse a
+// doubled gap on a normal card. Here the body already zeroed that side, so the collapse would eat
+// the strip's only top padding. A bare `py-*` cannot answer it — the `:not()` selector out-specifies
+// a plain class — so the value is restated under the same variant.
+//
+// ★ WHOLE CLASS STRINGS, NEVER CONCATENATED. Tailwind scans source text, so `p-${gap}` and
+// `pt-[${n}px]` generate nothing at all — they fail silently, at runtime, with no error. Every
+// combination is spelled out below. This is why `gap` is an enum and not a number.
+import { computed, useSlots, watchEffect } from 'vue';
+
+type Gap = 4 | 8 | 12;
+
+// ★ ONE SOURCE OF TRUTH FOR THE GAP. The var is not a stylistic choice — two rules OUTSIDE this
+// component read it and no Tailwind class can reach either: forest.css derives the nested card's
+// concentric radius as `calc(--forest-card-radius - --forest-card-pad)`, and kpi.theme.ts pulls the
+// bleed by `-mx-[var(--forest-card-pad)]`. Measured: with the var set, box radii are 20/16/12 for
+// gaps 4/8/12; without it they all stay at 8.
+// So the padding CLASS reads the same var rather than restating the number — otherwise the value
+// lives in two places and a future edit can move one and not the other. That also makes the body
+// classes gap-independent: only `pad` varies.
+const PAD: Record<Gap, string> = { 4: '0.25rem', 8: '0.5rem', 12: '0.75rem' };
+
+// ★ THE BOX NEEDS THE VAR ON ITSELF, NOT JUST INHERITED. The bold contexts set
+// `[--forest-card-pad:1.25rem]` on EVERY card root (mobile-theme.ts / marketing-theme.ts), and the
+// box is a card — so the context's value lands on the box's own element and beats the frame's,
+// which only reaches it by inheritance. The concentric rule then runs on the box with the CONTEXT's
+// padding while the body was inset by OURS: 8px of inset with a corner struck for 20px.
+// Restating the gap on the box makes both halves read the same number. Literal strings per gap
+// because Tailwind scans source text and cannot generate `[--forest-card-pad:${x}]`.
+const PAD_CLASS: Record<Gap, string> = {
+  4: '[--forest-card-pad:0.25rem]',
+  8: '[--forest-card-pad:0.5rem]',
+  12: '[--forest-card-pad:0.75rem]',
+};
+
+// The body drops its padding on whichever side the strip is on — see the note above. Both
+// breakpoints every time: the card fragment re-pins `sm:p-*`, so a bare `pb-0` still pads at ≥640px.
+const BODY = {
+  none: 'p-[var(--forest-card-pad)] sm:p-[var(--forest-card-pad)]',
+  header: 'p-[var(--forest-card-pad)] pt-0 sm:p-[var(--forest-card-pad)] sm:pt-0',
+  footer: 'p-[var(--forest-card-pad)] pb-0 sm:p-[var(--forest-card-pad)] sm:pb-0',
+} as const;
+
+// Gap-independent, because the body no longer contributes on the strip's side: pt === pb.
+// The 8px here deliberately equals the DEFAULT gap: the space around the box and the space around
+// the strip's own label are then one number, so the frame reads as a single rhythm rather than two
+// unrelated ones. Change the default gap and this should move with it.
+// ★ THE STRIP OWNS ITS HEIGHT, THE CONTENT DOES NOT. Without a floor the band is as tall as whatever
+// sits in it, so a footer holding a UButton (min-h-8, its touch target — see themes/button.ts, where
+// `min-h` is the sole height driver) came out 48px against a header of text at ~40px, and a card
+// with one of each looked lopsided. min-h-10 is that button plus the strip's own 8+8, so the tallest
+// realistic content still fits and a plain text row is centred in the same band.
+//
+// `grid items-center` rather than `flex items-center`: a lone grid child spans the column, so a row
+// using `ms-auto` to push its meta right still works. Under flex it would shrink to content and the
+// meta would collapse leftward.
+const STRIP = {
+  header: 'grid min-h-10 items-center px-4 pt-2 sm:px-4 [&:not(:last-child)]:pb-2',
+  footer: 'grid min-h-10 items-center px-4 pb-2 sm:px-4 [&:not(:first-child)]:pt-2',
+} as const;
+
+const props = withDefaults(
+  defineProps<{
+    /** The inset, in px. An enum because the classes must exist in source — see the note above. */
+    gap?: Gap;
+    /** The card's hairline. Uses the relative ring, so it holds at any surface level. */
+    outlined?: boolean;
+    /**
+     * The child already draws its own surface (an FKpi does), so this card must not draw a second
+     * one. Named for the exception rather than the rule so the common case stays free and the
+     * exception is a bare attribute — `<FInsetCard bare>` — since Vue's shorthand can only ever
+     * express `true`, which would make the opposite spelling cost `:box="false"` at every KPI.
+     */
+    bare?: boolean;
+
+    /**
+     * The strip's content, for the shape nearly every card wants: an icon, a title, something
+     * right-aligned above; a single action below. Given as props so a call site does not hand-roll
+     * the same flex row each time — and so the voice (overline/toned title, caption meta, muted
+     * action) is decided once here rather than re-chosen per page.
+     *
+     * The `#header` / `#footer` slots still win when a card needs a shape these cannot express.
+     */
+    icon?: string;
+    title?: string;
+    meta?: string;
+    /** Footer action label. `to` makes it a link; without one it is a button. */
+    action?: string;
+    to?: string;
+
+  }>(),
+  { gap: 8, outlined: true, bare: false },
+);
+
+const slots = useSlots();
+
+// A strip is present when its slot OR its props are supplied — the body's padding and the
+// one-strip rule both key off this, so neither can be fooled by the prop form.
+const hasHeader = computed(() => !!(slots.header || props.title));
+const hasFooter = computed(() => !!(slots.footer || props.action));
+
+// One strip is the whole idea: the box plus the ground it sits on. With both, the box becomes the
+// filling in a sandwich, neither side can drop its padding, and the frame stops reading as a frame.
+if (import.meta.env.DEV) {
+  watchEffect(() => {
+    if (hasHeader.value && hasFooter.value)
+      console.warn('[FInsetCard] `header` and `footer` together — this pattern takes one strip, not both.');
+  });
+}
+
+
+
+// Set as a var rather than a class so the radius and FKpi's bleed follow it.
+const style = computed(() => ({ '--forest-card-pad': PAD[props.gap] }));
+
+const ui = computed(() => ({
+  body: hasFooter.value ? BODY.footer : hasHeader.value ? BODY.header : BODY.none,
+  header: STRIP.header,
+  footer: STRIP.footer,
+}));
+
+// ★ THE FRAME IS ALWAYS `soft`, and the variant is not exposed. Probed 2026-09-10 with the prop
+// restored and the divider suppressed, measuring frame vs box in both modes:
+//
+//   soft     frame l1        box page   → box visible
+//   subtle   frame l1        box page   → box visible
+//   outline  frame PAGE      box page   → BOX INVISIBLE, both modes
+//   solid    frame inverted  box page   → visible, but a light box in a black card
+//
+// `outline` fills the frame with the page colour, and the box is pinned to the page colour too, so
+// the inset box vanishes into its own frame — the one thing this component exists to draw. That is
+// the real reason, and it is a property of the fill being pinned, not of the divider: `divide-y-0`
+// suppressed the hairline in one class, so the divider was never the objection it looked like.
+//
+// `soft` + a ring, rather than `subtle`: subtle also restores divide-y, and the gap is what
+// separates the strip here — a hairline in it would say the same thing twice.
+// ★ `h-fit` IS LOAD-BEARING, not a layout preference. A grid or flex row stretches its children by
+// default, and a stretched card grows past its content — the extra height lands BELOW the box, so
+// the even inset turns into a lopsided gap at the bottom and the frame stops reading as a frame.
+// The card must hug its content vertically.
+// ⚠ NOT `self-start`, which was the first cut: `align-self` acts on the CROSS axis, so in a flex
+// COLUMN it stops the card filling the width instead of capping its height — the card shrank to its
+// content in every column layout. `h-fit` caps the height and leaves width alone, which is the axis
+// actually at issue.
+const rootClass = computed(() =>
+  ['h-fit', props.outlined ? 'ring ring-[var(--forest-card-ring)]' : ''].filter(Boolean).join(' '),
+);
+
+// ★ THE BOX IS ALWAYS RAISED — there is no ramp option, on purpose. Letting the nesting ladder fill
+// the box steps it one level AWAY from the page, which in light means DARKER than the card it sits
+// in. That reads as a recess, not as a panel, and it is not a look this pattern should be able to
+// produce. --forest-card-inset (forest.css) is the raised surface: always lighter than the card, in
+// both modes. It replaced a bare `bg-default`, which is the PAGE colour and so went darker than the
+// card in dark — the box read as a hole punched in the frame.
+//
+// The box takes no padding of its own: UCard already pads its BODY slot, and adding p-* to the root
+// stacks on top of it for double the intended space.
+const boxUi = computed(() => ({ root: `bg-[var(--forest-card-inset)] ${PAD_CLASS[props.gap]}` }));
+
+// ★ FOR `bare`, WHERE THE CHILD IS ITS OWN SURFACE (an FKpi). Exposed as a slot prop so the
+// call site passes it straight to the child's `ui` without needing to know any of this:
+//   · the child pads its ROOT (FKpi's root IS the padded grid), unlike UCard which pads its body
+//   · pb is left OFF so FKpi's `visual-fit="bleed"` keeps its own `pb-0` and the graphic reaches the
+//     bottom edge — a blanket `p-4` here silently re-adds it
+//   · the bleed margin is restated to match the reading padding actually in force. FKpi pulls by
+//     `-mx-[var(--forest-card-pad)]`, which is the GAP — not the 16px this box pads by — so without
+//     this the graphic stops short on both sides.
+// A workaround for FKpi's coupling to --forest-card-pad; the real fix belongs in kpi.theme.ts, at
+// which point the `visual` line here can go.
+const selfBoxUi = computed(() => ({
+  root: `bg-[var(--forest-card-inset)] px-4 pt-4 ${PAD_CLASS[props.gap]}`,
+  visual: '-mx-4',
+}));
+</script>
+
+<template>
+  <UCard variant="soft" :class="rootClass" :style="style" :ui="ui">
+    <template v-if="hasHeader" #header>
+      <!-- The slot's FALLBACK is the prop form: pass `#header` and it replaces this wholesale. -->
+      <slot name="header">
+        <div class="flex items-center gap-2">
+          <UIcon v-if="icon" :name="icon" class="size-4 shrink-0 text-muted" />
+          <span class="type-overline truncate text-toned">{{ title }}</span>
+          <span v-if="meta" class="ms-auto shrink-0 type-caption text-muted">{{ meta }}</span>
+        </div>
+      </slot>
+    </template>
+
+    <UCard v-if="!bare" :ui="boxUi">
+      <slot />
+    </UCard>
+    <slot v-else :box-ui="selfBoxUi" />
+
+    <template v-if="hasFooter" #footer>
+      <!-- `xs` on purpose: the strip's floor is 40px, and a `md` button's 32px touch target plus the
+           strip's own 8+8 would push it to 48 and leave the header shorter than the footer. -->
+      <slot name="footer">
+        <UButton
+          :to="to"
+          size="xs"
+          variant="link"
+          color="neutral"
+          trailing-icon="i-lucide-arrow-right"
+          class="w-full justify-between px-0 text-muted"
+        >
+          {{ action }}
+        </UButton>
+      </slot>
+    </template>
+  </UCard>
+</template>

package/src/card/index.ts

@@ -0,0 +1,3 @@
+// Forest card compositions. UCard itself is Nuxt UI's, themed in ../themes/card.ts — this entry
+// carries only the compositions built ON it that a call site would otherwise hand-roll.
+export { default as FInsetCard } from './FInsetCard.vue';

package/src/map/FMap.vue

@@ -3,8 +3,9 @@
 // owns the boilerplate
 // every surface would otherwise repeat: the access-token guard (with a setup fallback), a lazy WebGL
 // init (the context is created only when the frame nears the viewport, so a page with several maps
-// doesn't pay for all of them up front), the load fade, cooperative gestures (so a page scrolls past
-// the map), and teardown. Emits `ready(map)` once the style has loaded — add sources, layers, config
+// doesn't pay for all of them up front), the load fade, and teardown. Cooperative gestures are
+// available (`cooperative`) but OFF unless a surface asks: a map in a document should not swallow
+// the scroll, and a map that IS the surface should not need two fingers to move. Emits `ready(map)` once the style has loaded — add sources, layers, config
 // and interactions in that handler.
 //
 // Token: pass `access-token`, or set `mapboxgl.accessToken` once at app start. Public `pk.…` tokens
@@ -75,7 +76,16 @@ const props = withDefaults(
      *  the surface — only turn this off when the surface carries it elsewhere (e.g. an app's legal
      *  screen, or chrome drawn above a bottom sheet). */
     attribution?: boolean;
-    /** ⌘/ctrl-scroll to zoom — on by default so a page scrolls past the map */
+    /**
+     * Cooperative gestures. ONE flag, TWO behaviours — Mapbox does not separate them: scroll-zoom
+     * then needs ⌘/ctrl held, AND a touch pan needs TWO FINGERS (pitch, three). It is the second
+     * half that decides the default.
+     *
+     * OFF by default, which is Mapbox's own default too. A map is usually the subject of the
+     * surface it is on — an ops canvas, a rider finding a vehicle — and there one finger should
+     * move it. Turn it ON for a map embedded in a document, where a map that swallows the scroll
+     * traps the reader on the way past.
+     */
     cooperative?: boolean;
     /** create the WebGL context only when the frame nears the viewport */
     lazy?: boolean;
@@ -102,7 +112,7 @@ const props = withDefaults(
     lightPreset: 'auto',
     height: 'h-105',
     attribution: true,
-    cooperative: true,
+    cooperative: false,
     lazy: true,
     frame: false,
   },

package/src/shell/FSidePanel.vue

@@ -54,7 +54,12 @@ const props = withDefaults(
   // navigation and the weight split between two edges. It is what a console with a left rail does
   // everywhere (Linear, Figma, Retool). Pass `side="start"` where the panel IS the navigation for its
   // view, which in practice means a settings sub-nav.
-  { behaviour: 'push', side: 'end', size: 'md' },
+  // ★ `close: undefined` is load-bearing, not noise. A type-declared `close?: boolean` compiles to
+  // `{ type: Boolean }`, and Vue casts an ABSENT boolean prop to `false` unless the options carry a
+  // `default` key — so without this `props.close ?? overlay` never sees `undefined`, and an overlay
+  // panel drew no close at all unless a consumer asked for one. Declaring the default keeps the three
+  // states the prop is written for: unset (follow the behaviour), true, false.
+  { behaviour: 'push', side: 'end', size: 'md', close: undefined },
 );
 
 const open = defineModel<boolean>('open', { default: true });
@@ -214,6 +219,20 @@ const sidebarUi = computed(() => ({
   // panel title and a card title share a baseline instead of nearly sharing one.
   header: 'min-h-0 p-4 pb-0',
   inner: overlay.value ? 'forest-canvas-chrome divide-y-0' : '',
+  // ★ THE PANEL OWNS DISMISS — the button it renders into `#actions`, wired to its own `open`. Stock adds a
+  // SECOND one under 1024px and it is inert: `canClose` is `close && collapsible !== 'none' ||
+  // isMobile`, and that `|| isMobile` survives this component's `collapsible="none"`, while the click
+  // writes USidebar's own `open` model — which this never binds and which changes nothing in the
+  // `collapsible="none"` branch (no `data-state`, no mobile menu). So it is a dead control, and on a
+  // phone it sat next to a live one.
+  //
+  // ★ Hidden through the theme rather than through `<template #close />`, which LOOKS like the tighter
+  // fix and does not work: Vue falls back to a slot's default content when the passed slot renders no
+  // valid vnode, so an empty template hands back exactly the button it was meant to suppress (measured
+  // — stock's close was still in the DOM). And not `:open` either: USidebar's
+  // `watch(isMobile, …, { immediate: true })` sets that model to `false` on crossing 1024px, so a bound
+  // panel would shut itself on a phone.
+  close: 'hidden',
 }));
 </script>
 

package/src/styles/forest.css

@@ -409,6 +409,20 @@
   --forest-card-l2: color-mix(in oklab, var(--ui-bg), var(--ui-text-highlighted) 8%);
   --forest-card-l3: color-mix(in oklab, var(--ui-bg), var(--ui-text-highlighted) 13%);
 }
+/* ── Inset surface — a RAISED panel sitting on a card, the inverse of the ramp above ──────────────
+   The ramp steps AWAY from the page (light darker, dark lighter), which reads as a recess. A panel
+   inset into a card's own ground is the opposite gesture: it should read as lifted, so it steps
+   TOWARD white in both modes — i.e. always lighter than the card it sits in.
+   Light lands back on the page plane (a white panel on a grey card, the dashboard look); dark cannot
+   do that, because the page is the darkest thing there, so it borrows the ramp's own next level.
+   Measured against a card at L1 (.967 light / .229 dark): this is .994 / .268 — lighter in both.
+   ⚠ Declared on EVERY mode-boundary selector for the same reason the levels above are: the value
+   derives from --ui-bg, a custom property resolves ONCE where it is declared, and on :root alone a
+   nested force-light or force-dark island would inherit the outer mode's already-resolved colour.
+   ⚠ NOT --ui-bg-elevated or --ui-bg-muted, which sound right and are not: both are DARKER than the
+   Forest card surface in dark (.156 against the card's .229), so a panel on them reads as a hole. */
+:root, .light { --forest-card-inset: var(--ui-bg); }
+.dark { --forest-card-inset: var(--forest-card-l2); }
 /* Map — WHICH PALETTE OWNS WHICH REGION (José, 2026-07-26). Two rules, and they do not overlap:
      the DISC and the BADGE take the VIVID set (plus neutrals). They are categorical: they say WHICH
        kind of thing this is, and vivid separates further than the CVD-gated set does at marker size.