@humanforest/nuxt-layer 0.1.3 → 0.3.0

package/packages/ui/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/packages/ui/src/themes/checkbox.ts

@@ -7,16 +7,24 @@
  *     while aligning with Forest's overall soft-radius vocabulary (--ui-radius = 0.5 rem).
  *   - `label`: font-medium is already stock; we keep it and add nothing — the Nuxt UI default is
  *     correct here.
- *   - `base` focus ring: Forest's house convention `focus-visible:outline-2 focus-visible:outline-offset-2`
- *     (an offset ring), over stock's flush `focus-visible:outline-3`. The outline COLOUR is stock's
- *     semantic value, resolved to the Forest OKLCH ramp via docs.css / forest-preset — no colour
- *     override needed, only the width + offset.
+ *   - focus ring: Forest's house convention `outline-2 outline-offset-2` (an offset ring), over
+ *     stock's flush `outline-3`. The outline COLOUR is stock's semantic value, resolved to the
+ *     Forest OKLCH ramp via docs.css / forest-preset — no colour override needed, only the width
+ *     and offset. Where that ring has to be written is the awkward part; see below.
  *   - `legend` (CheckboxGroup): font-bold — bold against the regular item labels, giving the
  *     group label a clear hierarchy above the individual checkbox labels.
  *
- * The card variant is left entirely stock — no radius override.
+ * ★ THE RING IS A COMPOUND, NOT A SLOT. Stock paints it in two places and neither is a plain slot:
+ * on `base` for the `list` variant with a visible box, and on `root` (as `has-focus-visible:`) for
+ * `card`, and for `list` once the box is hidden. Both live in stock's compoundVariants, which tv
+ * appends AFTER the slots — so a `slots.base` override loses to them and silently does nothing.
+ * The width therefore has to be restated at the same layer, in the entries below.
  *
- * Slots touched: base.
+ * The offset is the exception: no stock rule sets `outline-offset`, so the one on `base` still
+ * reaches from `slots` and is not repeated. The root entries carry their own, `has-focus-visible:`
+ * being a different property from the bare `outline-offset-2` on base.
+ *
+ * Slots touched: base, root, icon.
  * Slot names sourced from: apps/docs/node_modules/.nuxt-ui/ui/checkbox.ts
  *
  * The CheckboxGroup legend opinion lives in its own sibling fragment (checkbox-group.ts),
@@ -26,22 +34,32 @@
 export const checkboxTheme = {
   slots: {
     // Deltas over stock: `rounded` (4px) for the Forest soft radius (stock rounded-sm/2px), and the
-    // house focus ring `outline-2 outline-offset-2` (stock is a flush outline-3). Ring colour and the
-    // indicator bg resolve to the Forest OKLCH ramps via the colour-alias bridge — no override there.
-    base: 'rounded focus-visible:outline-2 focus-visible:outline-offset-2',
+    // ring's offset. The WIDTH is not here — it would be overridden; see the compounds below.
+    base: 'rounded focus-visible:outline-offset-2',
   },
   // Touch: a checkbox's tap target is the whole label ROW, and at md that row is short (~20px). Under
-  // a coarse (finger) pointer each size grows one size up — box (base), row height (container) and
-  // label text (wrapper) — so the row becomes a taller, easier target. No sliding part, so the bump
-  // is clean (unlike the switch thumb). xl is the ceiling; each size lists only its deltas up.
+  // a coarse (finger) pointer each size grows one size up — box (base), tick (icon), row height
+  // (container) and label text (wrapper) — so the row becomes a taller, easier target. No sliding
+  // part, so the bump is clean (unlike the switch thumb). xl is the ceiling; each size lists only
+  // its deltas up, which is why container and wrapper appear on two rungs and the box on four.
+  //
+  // ★ THE TICK IS SIZED SEPARATELY FROM THE BOX. Stock pins `icon` per size rather than filling the
+  // box, so growing `base` alone leaves the tick at its fine-pointer size inside a bigger square.
   // `coarse:` carries the `:not(.cut-fixed)` escape so the mobile cut (baked size lg) opts out.
   variants: {
     size: {
-      xs: { base: 'coarse:size-3.5' },
-      sm: { base: 'coarse:size-4', container: 'coarse:h-5', wrapper: 'coarse:text-sm' },
-      md: { base: 'coarse:size-4.5' },
-      lg: { base: 'coarse:size-5', container: 'coarse:h-6', wrapper: 'coarse:text-base' },
+      xs: { base: 'coarse:size-3.5', icon: 'coarse:size-3' },
+      sm: { base: 'coarse:size-4', icon: 'coarse:size-3.5', container: 'coarse:h-5', wrapper: 'coarse:text-sm' },
+      md: { base: 'coarse:size-4.5', icon: 'coarse:size-4' },
+      lg: { base: 'coarse:size-5', icon: 'coarse:size-4.5', container: 'coarse:h-6', wrapper: 'coarse:text-base' },
       // xl: ceiling
     },
   },
+  // The house width, restated where stock's own compounds would otherwise win. Colour is left to
+  // stock, so these carry no `color` discriminator and apply across every ramp.
+  compoundVariants: [
+    { variant: 'list', indicator: ['start', 'end'], class: { base: 'focus-visible:outline-2' } },
+    { variant: 'card', class: { root: 'has-focus-visible:outline-2 has-focus-visible:outline-offset-2' } },
+    { variant: 'list', indicator: 'hidden', class: { root: 'has-focus-visible:outline-2 has-focus-visible:outline-offset-2' } },
+  ],
 } as const;

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

@@ -73,6 +73,7 @@ export { paginationTheme as pagination } from './pagination';
 export { pinInputTheme as pinInput } from './pin-input';
 export { popoverTheme as popover } from './popover';
 export { progressTheme as progress } from './progress';
+export { progressGroupTheme as progressGroup } from './progress-group';
 // Prose components are namespaced under ui.prose.* — the fragment runs stock, carrying only the
 // `ed-demo` marker the docs editorial grid reads off a demo pane.
 export { proseTheme as prose } from './prose';
@@ -85,6 +86,7 @@ export { sidebarTheme as sidebar } from './sidebar';
 export { skeletonTheme as skeleton } from './skeleton';
 export { slideoverTheme as slideover } from './slideover';
 export { sliderTheme as slider } from './slider';
+export { splitterTheme as splitter } from './splitter';
 export { stepperTheme as stepper } from './stepper';
 export { switchTheme as switch } from './switch';
 export { tableTheme as table } from './table';

package/packages/ui/src/themes/progress-group.ts

@@ -0,0 +1,39 @@
+/**
+ * Forest theme fragment — UProgressGroup (several values as segments of one track, plus a legend).
+ *
+ * New in Nuxt UI 4.11, and it reaches a Forest consumer whether or not we document it: the layer
+ * registers @nuxt/ui wholesale, so the component is typeable the moment the dependency resolves.
+ * This fragment exists so that what arrives is not off-brand, not because the system recommends it.
+ *
+ * Forest opinions applied:
+ *
+ *   segment, status — the motion tokens, replacing stock's hard-coded `duration-200 ease-out`.
+ *     UProgress next to it already animates on `--motion-slow` / `--motion-ease-out` (progress.ts),
+ *     and two bars of the same family easing differently is the kind of seam that only ever shows
+ *     up once both are on screen.
+ *
+ * We do NOT override:
+ *   - `base` (the track) — stock's `bg-accented` groove and `rounded-full` are already the Forest
+ *     reading; radius follows --ui-radius through the preset.
+ *   - Colour variants — `bg-primary`, `bg-error` and the Forest ramps (forest/maple/river/warm/acid)
+ *     are registered by forest-preset, and a per-item `color` that is not a registered name is
+ *     passed through as an inline background, so `var(--dataviz-categorical-safe-N)` works as-is.
+ *   - `motion-reduce:transition-none` — stock sets it, and the global reduced-motion floor in
+ *     packages/tokens/motion supersedes it regardless. Restating it would be drift.
+ *   - The size ladder, the legend slots, and `list`/`item` layout — no Forest opinion here.
+ *
+ * ★ NOT A REPLACEMENT FOR FDistributionBar. Its bar segments carry no slot, so nothing can hang a
+ * tooltip or a focus stop on them, and each segment is its own `role="progressbar"` — a five-part
+ * figure announces as five progress bars rather than one. FDistributionBar exists for the
+ * composition read: one `role="img"`, one sentence, and optional interactive segments.
+ *
+ * Slots touched: segment, status.
+ * Slot names sourced from: apps/docs/node_modules/.nuxt-ui/ui/progress-group.ts
+ */
+
+export const progressGroupTheme = {
+  slots: {
+    segment: 'duration-(--motion-slow) ease-(--motion-ease-out)',
+    status: 'duration-(--motion-slow) ease-(--motion-ease-out)',
+  },
+} as const;

package/packages/ui/src/themes/splitter.ts

@@ -0,0 +1,33 @@
+/**
+ * Forest theme fragment — USplitter (resizable panels with a draggable handle).
+ *
+ * New in Nuxt UI 4.11. Nothing in Forest uses it yet — FAppSidebar resizes through
+ * UDashboardSidebar's own `resizable`, and FSidePanel is deliberately two fixed rungs rather than a
+ * drag. The fragment is here for the same reason as progress-group's: the component is typeable by
+ * any consumer on the layer, so its focus ring should be the house one on arrival.
+ *
+ * Forest opinions applied:
+ *
+ *   handle — the house focus ring: offset, and pinned to the ramp var rather than the semantic
+ *     `outline-primary` token, matching link.ts, accordion.ts and carousel.ts. Stock's width is
+ *     already `outline-2`, so only the offset and the colour are stated here.
+ *
+ * We do NOT override:
+ *   - The handle's resting appearance. Stock paints nothing until focus, and that is right for a
+ *     seam between two panels — see dashboard-resize-handle.ts for the case where Forest does draw
+ *     a grab affordance, and note it does not port: that handle's box is zero-wide and sits ON the
+ *     seam, so its pill is positioned against a zero-width edge. This one is a real 2-unit column.
+ *   - `panel`, `root`, and the orientation cursors — layout and affordance, no Forest opinion.
+ *
+ * ★ If a split pane is ever built in Forest, it should be built on this rather than hand-rolled,
+ * and this fragment will need the resting/hover treatment that decision implies.
+ *
+ * Slots touched: handle.
+ * Slot names sourced from: apps/docs/node_modules/.nuxt-ui/ui/splitter.ts
+ */
+
+export const splitterTheme = {
+  slots: {
+    handle: 'focus-visible:outline-offset-2 focus-visible:outline-[var(--forest-500)]',
+  },
+} as const;

package/styles.cdn.gen.css

@@ -1297,6 +1297,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.