@humanforest/nuxt-layer 0.3.1 → 0.3.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@humanforest/nuxt-layer",
   "type": "module",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Forest design system as a Nuxt layer — extend it to inherit the theme, colour roles, icons and brand fonts in one line.",
   "main": "./nuxt.config.ts",
   "files": [

package/packages/charts/src/FSparkline.vue

@@ -50,6 +50,12 @@ const props = withDefaults(
     area?: boolean;
     /** Marks the last point, so the series has an end rather than running off the edge. */
     endpoint?: boolean;
+    /**
+     * Takes the height its container gives it, with `height` as the floor. For a graphic in a space
+     * its surroundings have made taller (a KPI bleed row that a stretched card or a group has given
+     * more height), where the chart is the part that should grow. Works for both marks.
+     */
+    fill?: boolean;
     /**
      * Monotone interpolation, on by default. Monotone rather than a plain spline: it stays inside
      * the data's own range, so no peak appears between two points that neither of them reached.
@@ -71,7 +77,7 @@ const props = withDefaults(
      */
     mark?: 'line' | 'bar';
   }>(),
-  { height: 32, color: 'var(--ui-primary)', area: false, endpoint: false, curve: true, mark: 'line', compare: undefined, compareColor: undefined },
+  { height: 32, color: 'var(--ui-primary)', area: false, endpoint: false, fill: false, curve: true, mark: 'line', compare: undefined, compareColor: undefined },
 );
 
 if (import.meta.env.DEV) {
@@ -155,14 +161,14 @@ const endpointTop = computed(() => {
 </script>
 
 <template>
-  <div class="relative w-full" :style="{ height: `${height}px`, color }">
+  <div class="relative w-full" :class="fill ? 'h-full' : ''" :style="fill ? { minHeight: `${height}px`, color } : { height: `${height}px`, color }">
     <!-- Plain DOM rather than a mark: there are no axes, scales or tooltip to share with the XY
          container, so a flex row of columns is the whole implementation and costs no chart runtime.
          The 2px gap is fixed, so the bucket count sets how thin the bars get: n buckets across w
          pixels leaves (w - 2(n - 1)) / n each. A tile 280px wide holds 12 buckets at 21px and 60 at
          2.7px — still bars; past roughly 60 the gap outweighs the bar and the row reads as a
          texture, where the measure belongs to a line instead. -->
-    <div v-if="mark === 'bar'" class="flex h-full w-full items-end gap-0.5" aria-hidden="true">
+    <div v-if="mark === 'bar'" class="flex w-full items-end gap-0.5" :class="fill ? 'absolute inset-0' : 'h-full'" aria-hidden="true">
       <span
         v-for="(v, i) in data"
         :key="i"
@@ -180,12 +186,17 @@ const endpointTop = computed(() => {
     <!-- No bottom margin: the graphic sits on the tile's own bottom edge, and 2px of clearance
          there reads as a misaligned card rather than as breathing room. The top keeps its 2px so a
          peak is not clipped by the stroke's own width, and the right reserves room for the endpoint
-         dot when there is one. -->
+         dot when there is one. Under `fill` the container is laid over the root rather than sizing
+         it: the root takes the space it is given, floored at `height`, and Unovis measures that box,
+         never its own SVG (which would feed back) and never its 300px fallback for an empty box.
+         An inline style, not a utility: Unovis's own stylesheet pins `.unovis-xy-container` to
+         `position: relative`, and a class loses to it. -->
     <VisXYContainer
       v-else
       :key="themeVersion"
+      :style="fill ? { position: 'absolute', inset: '0' } : undefined"
       :data="points"
-      :height="height"
+      :height="fill ? undefined : height"
       :margin="{ top: 2, right: endpoint ? 4 : 0, bottom: 0, left: 0 }"
       :y-domain="domain ?? undefined"
       :duration="motionDuration('slow')"

package/packages/ui/src/card/FInsetCard.vue

@@ -11,10 +11,10 @@
 // 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 GAP IS ONE VALUE DOING TWO JOBS. Setting --forest-card-pad drives (a) the body padding, so
+// the box is inset by it, and (b) the concentric radius, because forest.css derives a nested card's
+// corner as `outer − pad`. Set it once here and both 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
@@ -36,11 +36,10 @@ 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.
+// ★ ONE SOURCE OF TRUTH FOR THE GAP. The var is not a stylistic choice — a rule OUTSIDE this
+// component reads it and no Tailwind class can reach it: forest.css derives the nested card's
+// concentric radius as `calc(--forest-card-radius - --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.
@@ -118,13 +117,20 @@ const props = withDefaults(
      * body rather than the card's.
      */
     flush?: boolean;
+    /**
+     * The card fills the height its row gives it instead of hugging its content, so cards in a row
+     * end level. Only for content that can take the extra height: an FKpi whose bleed chart is a
+     * `fill` sparkline grows into it. A bar, a table or a line of text cannot, and the spare height
+     * lands as a gap under it.
+     */
+    stretch?: boolean;
 
     /** Footer action label. `to` makes it a link; without one it is a button. */
     action?: string;
     to?: string;
 
   }>(),
-  { gap: 8, outlined: true, bare: false, flush: false },
+  { gap: 8, outlined: true, bare: false, flush: false, stretch: false },
 );
 
 const slots = useSlots();
@@ -149,11 +155,14 @@ if (import.meta.env.DEV) {
 
 
 
-// Set as a var rather than a class so the radius and FKpi's bleed follow it.
+// Set as a var rather than a class so the radius follows it.
 const style = computed(() => ({ '--forest-card-pad': PAD[props.gap] }));
 
+// Under `stretch` the body takes whatever height the card is given beyond its strip.
 const ui = computed(() => ({
-  body: hasFooter.value ? BODY.footer : hasHeader.value ? BODY.header : BODY.none,
+  body: [hasFooter.value ? BODY.footer : hasHeader.value ? BODY.header : BODY.none, props.stretch ? 'flex-1' : '']
+    .filter(Boolean)
+    .join(' '),
   header: STRIP.header,
   footer: STRIP.footer,
 }));
@@ -176,13 +185,15 @@ const ui = computed(() => ({
 // ★ `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.
+// The card must hug its content vertically. `stretch` drops it for a row whose cards should end
+// level: the card becomes a flex column and its body takes the spare height, which only reads well
+// when the content can grow into it.
 // ⚠ 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(' '),
+  [props.stretch ? 'flex flex-col' : '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
@@ -198,23 +209,19 @@ const rootClass = computed(() =>
 // pads at ≥640px. The box keeps its own overflow-hidden either way, which is what clips a flush
 // child to the rounded corner; a child that must scroll (UTable) already scrolls itself.
 const boxUi = computed(() => ({
-  root: `bg-[var(--forest-card-inset)] ${PAD_CLASS[props.gap]}`,
+  root: `bg-[var(--forest-card-inset)] ${PAD_CLASS[props.gap]}${props.stretch ? ' h-full' : ''}`,
   ...(props.flush ? { body: 'p-0 sm:p-0' } : {}),
 }));
 
 // ★ 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.
+//   · the card pad is the GAP, restated on the child for the corner — the same reason as `boxUi`
+//   · the child's own padding goes through --forest-kpi-pad, because FKpi otherwise pads by the card
+//     pad, which is now the gap. The hook sets all four sides, and FKpi's bleed pulls by the same
+//     expression, so `visual-fit="bleed"` still zeroes the bottom and meets both edges. A padding
+//     class cannot do this: FKpi merges `ui.root` last, so a `pb-4` here would beat the bleed's `pb-0`.
 const selfBoxUi = computed(() => ({
-  root: `bg-[var(--forest-card-inset)] px-4 pt-4 ${PAD_CLASS[props.gap]}`,
-  visual: '-mx-4',
+  root: `bg-[var(--forest-card-inset)] [--forest-kpi-pad:1rem] ${PAD_CLASS[props.gap]}${props.stretch ? ' h-full' : ''}`,
 }));
 </script>
 

package/packages/ui/src/kpi/FKpi.vue

@@ -6,7 +6,7 @@
 // were both taken.
 //
 // The tile is a UCard, so it inherits the card surface and moves when cards move. Inside a group it
-// registers itself, spans four subgrid rows, and may become a tab or a toggle.
+// registers itself, spans the group's 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, joinCaption, type KpiFormat } from './kpiFormat';
@@ -37,6 +37,14 @@ const props = withDefaults(
     /** Forces the figure's face. Unset lets the context's --fx-metric traits decide. */
     face?: 'tabular' | 'display';
 
+    /**
+     * Visually hides the label while keeping it the figure's accessible name — for a tile whose
+     * title is drawn outside it, such as FInsetCard's header strip. Use this rather than
+     * `ui.header: 'sr-only'`, which takes the row out of the grid — in a group, that pulls the
+     * figure out of line with its neighbours.
+     */
+    hideLabel?: boolean;
+
     /**
      * How the `visual` slot meets the card. `bleed` runs the graphic to the side and bottom edges —
      * right for a sparkline, which is data and nothing else. `inset` keeps the card's padding and
@@ -154,6 +162,7 @@ const styles = computed(() =>
     visualFit: slots.visual ? props.visualFit : undefined,
     intent: delta.value?.intent,
     face: props.face,
+    hideLabel: props.hideLabel,
     status: props.status,
     emphasis: props.emphasis,
     dimmed: isBlank.value,
@@ -244,9 +253,9 @@ const onKeydown = (e: KeyboardEvent) => {
       <span v-if="caveat" :id="caveatId">{{ captionLead ? ' · ' : '' }}{{ caveat }}</span>
     </p>
 
-    <div v-if="$slots.visual" :class="cls('visual')"><slot name="visual" /></div>
+    <div v-if="$slots.visual" :class="cls('visual')" data-kpi-visual><slot name="visual" /></div>
     <slot name="insight" />
-    <div v-if="$slots.links || $slots.footer" :class="cls('footer')">
+    <div v-if="$slots.links || $slots.footer" :class="cls('footer')" data-kpi-footer>
       <slot name="links" />
       <slot name="footer" />
     </div>

package/packages/ui/src/kpi/FKpiGroup.vue

@@ -1,15 +1,15 @@
 <script setup lang="ts">
 // A row of KPI tiles.
 //
-// The row is a four-row grid and each tile spans all four with grid-template-rows: subgrid, so
-// labels, values, captions and visuals align across the row however long any one label runs.
-// Without it, a two-line label pushes its own value down and nothing lines up.
+// Each tile spans the group's rows with grid-template-rows: subgrid, so labels, values, captions and
+// visuals align across the row however long any one label runs. Without it, a two-line label pushes
+// its own value down and nothing lines up.
 //
 // Selection: single mode is a tablist with manual activation, pointing at the chart it controls;
 // multiple mode is a set of aria-pressed toggles, because more than one selected tile is not a tab
 // row. One live region for the whole row — a per-tile region turns a refresh into a chorus.
 import { computed, provide, reactive, ref, watch } from 'vue';
-import { KPI_GROUP_KEY, type KpiGroupContext } from './kpi.theme';
+import { KPI_GROUP_KEY, kpiGroupRows, type KpiGroupContext } from './kpi.theme';
 import type { KpiFormat } from './kpiFormat';
 import {
   createKpiRegistry,
@@ -124,15 +124,17 @@ const gridStyle = computed(() =>
 
 <template>
   <div>
-    <!-- Four content-sized rows. Not 1fr on the last one: the group is sized by its content, so 1fr
-         resolves to whatever is left over — nothing — and a visual placed in that row overflows onto
-         the caption above it. -->
+    <!-- No row template: the rows are implicit and content-sized. Never 1fr, which resolves to nothing
+         in a content-sized group and lets a visual overflow onto the caption above it. Each tile spans
+         kpiGroupRows of them, a count that grows only for parts some tile actually has, so a group
+         with no visual keeps no empty row and no gap in front of one. -->
     <div
       :role="selectable && !multiple ? 'tablist' : selectable ? 'group' : undefined"
       :aria-label="label"
       :aria-orientation="selectable && !multiple ? orientation : undefined"
-      class="grid grid-rows-[auto_auto_auto_auto] items-stretch"
+      class="grid items-stretch"
       :class="[
+        kpiGroupRows,
         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.

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

@@ -1,11 +1,11 @@
 // 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 value's type size is a container query on the tile's figure row, 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.
+// Row alignment is subgrid: inside a group the tile spans the group's rows, 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';
@@ -13,21 +13,31 @@ 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.
+    // means the padding has to live here instead, and it is the only padding on the tile.
     // 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.
+    // 32px-radius card. --forest-kpi-pad overrides it where the card pad means something else:
+    // FInsetCard pins the card pad to its gap for the corner, and sets the tile's padding here. The
+    // bleed pulls by the same expression, so the graphic meets the edge the padding leaves.
+    //
+    // No row template: the rows are implicit, one per part present, so a tile without a visual has
+    // no empty track under its caption, and no gap in front of one. A bleed visual adds a flexible
+    // last row (`visualFit`); a grouped tile takes its rows from the group instead (`aligned`).
     //
     // 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',
+    root: 'relative grid grid-cols-[minmax(0,1fr)] gap-1 p-[var(--forest-kpi-pad,var(--forest-card-pad))]',
     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',
+    // ★ THE SIZE QUERIES' CONTAINER IS THE BODY, NOT THE ROOT. A container query is layout
+    // containment, and a layout-contained grid cannot be a subgrid: on the root, a grouped tile's
+    // `grid-template-rows: subgrid` computes to `none`, each tile sizes its own rows, and a group
+    // lines up only where its tiles happen to match. The body spans the tile's content width and
+    // holds every part that queries it.
+    body: 'flex flex-wrap items-baseline gap-x-2 gap-y-1 @container/kpi',
     // 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.
@@ -71,22 +81,36 @@ export const kpiTheme = tv({
      * `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.
+     * margin would shrink the grid row and pull the graphic up over the caption. Its row is the
+     * tile's last and flexible one, and the graphic spans it bottom-aligned: a tile given more
+     * height than it needs — a group's shared row, a stretched FInsetCard — grows a `fill`
+     * sparkline into the spare height and leaves any other graphic on the bottom edge.
      *
      * `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.
+     * packs the tile's rows to the top with `content-start`, so a tile stretched taller than its
+     * content keeps the extra height below the graphic rather than spread between its rows.
      */
     visualFit: {
-      bleed: { root: 'pb-0', visual: 'self-end -mx-[var(--forest-card-pad)]' },
+      bleed: { root: 'pb-0 grid-rows-[auto_auto_auto_1fr]', visual: 'self-stretch flex flex-col justify-end -mx-[var(--forest-kpi-pad,var(--forest-card-pad))]' },
       inset: { root: 'content-start', visual: 'self-start' },
     },
+    // A grouped tile spans exactly the rows its group declares (kpiGroupRows), so a group with no
+    // visual has no empty last track and no group gap under its captions.
     aligned: {
-      true: { root: 'row-span-4 grid-rows-subgrid' },
+      true: { root: 'row-span-(--forest-kpi-rows) grid-rows-subgrid' },
+    },
+    /**
+     * The label is visually hidden but stays the figure's accessible name — for a tile whose title
+     * is drawn OUTSIDE it, such as FInsetCard's header strip. `sr-only` goes on the LABEL, and the
+     * ROW only collapses to zero height: a grouped tile shares its rows with its neighbours, and
+     * a row taken out of the flow would pull the figure, caption and visual up a track, out of line
+     * with every tile whose label shows. `-mt-1` cancels the gap after the zero-height row, so a
+     * standalone figure sits on the tile's top padding; it must equal the root's `gap-1`. A grouped
+     * figure keeps its row (compound below).
+     */
+    hideLabel: {
+      true: { header: 'h-0 overflow-hidden', label: 'sr-only', body: '-mt-1' },
     },
     selectable: {
       true: {
@@ -148,6 +172,9 @@ export const kpiTheme = tv({
     // 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)]' } },
+    // Inside a group the figure keeps its row: the group lays every tile on shared subgrid rows, so
+    // pulling one figure up into the gap would misalign it against a neighbour whose label shows.
+    { hideLabel: true, aligned: true, class: { body: 'mt-0' } },
   ],
   defaultVariants: {
     status: 'ok',
@@ -155,6 +182,15 @@ export const kpiTheme = tv({
   },
 });
 
+/**
+ * The group's row count, which every grouped tile spans: label, figure and caption, one more when any
+ * tile has a visual, one more when any has a footer. Declared on the group because the rows are
+ * shared, so no tile can count them alone, and counted with `:has()` so it follows the slots that
+ * actually render.
+ */
+export const kpiGroupRows =
+  '[--forest-kpi-rows:3] has-[[data-kpi-visual]]:[--forest-kpi-rows:4] has-[[data-kpi-footer]]:[--forest-kpi-rows:4] has-[[data-kpi-visual]]:has-[[data-kpi-footer]]:[--forest-kpi-rows:5]';
+
 export type KpiSlot = keyof ReturnType<typeof kpiTheme>;
 
 export interface KpiGroupContext {