@humanforest/ui 0.1.0

package/src/shell/FToolbarActions.vue

@@ -0,0 +1,32 @@
+<script setup lang="ts">
+// A view's own controls, placed at the right-hand end of the section's toolbar.
+//
+//   <FToolbarActions>
+//     <UButton label="Recentre" @click="recentre" />
+//   </FToolbarActions>
+//
+// A console section owns its navigation and renders it once, in the route that owns the section. Its
+// VIEWS own their actions. The two are siblings in that route's template — toolbar beside the router
+// view — so a view cannot fill the toolbar's slots, and provide/inject cannot cross siblings either.
+// What both sit inside is the SHELL, so the shell carries the ref and this teleports into it.
+//
+// These land in the FIRST toolbar to claim the seam, which is not necessarily the nearest bar in the
+// markup: on a section stacking a nav row over a filter row that is the NAV row, and a view writing
+// its own second bar still sends its actions up to the section's.
+//
+// Renders where it was written when no toolbar has claimed the seam. A page whose actions vanished
+// silently is broken in a way nobody notices; controls appearing somewhere odd say so immediately.
+import { computed, inject } from 'vue';
+import { TOOLBAR_SEAT_KEY } from './shell';
+
+const seat = inject(TOOLBAR_SEAT_KEY, null);
+const target = computed(() => seat?.actions.value ?? null);
+</script>
+
+<template>
+  <!-- `disabled` rather than v-if, so the slot still renders with no toolbar above. Teleport wants a
+       valid `to` even when disabled, hence the body fallback. -->
+  <Teleport :to="target ?? 'body'" :disabled="!target">
+    <slot />
+  </Teleport>
+</template>

package/src/shell/index.ts

@@ -0,0 +1,33 @@
+// The Forest app shell — the chrome AROUND a page, and the toolbar seat a page can reach into.
+//
+//   <FAppShell>       sidebar + header + the inset card the page lives in
+//   <FAppSidebar>     the brand mark, the nav and the collapsed rail — the app supplies the list
+//   <FAppNavbar>      the rail control and the crumb — the app supplies the crumb and its actions
+//   <FScrollShadow>   the overflow signal for a column whose scrollbar is hidden — the sidebar's
+//   <FSidePanel>      a column belonging to a CONTAINER rather than the app — settings sub-nav, or a
+//                     filter/list panel over a canvas. Not the app rail; see the component's own note.
+//   <FPageToolbar>   the page's filters, view controls or sub-route nav, flush at the top of the card
+//   <FToolbarActions> a view's own controls, placed at the right of the section's toolbar
+//   TOOLBAR_SEAT_KEY   the injection carrying the toolbar seat; exported for a custom shell
+//   createToolbarClaims the claim ordering behind a seat's actions, for a shell of one's own
+//
+// The look of every region is theme fragments (themes/dashboard-*.ts), not this component — what
+// lives here is the ARRANGEMENT: chrome outside the card, and a way for a page to reach it.
+export { default as FAppShell } from './FAppShell.vue';
+export { default as FAppSidebar } from './FAppSidebar.vue';
+export { default as FAppNavbar } from './FAppNavbar.vue';
+export { default as FScrollShadow } from './FScrollShadow.vue';
+export { default as FSidePanel } from './FSidePanel.vue';
+export {
+  CANVAS_INSET_VAR,
+  SIDE_PANEL_WIDTH,
+  sidePanelInsetPx,
+  type SidePanelBehaviour,
+  type SidePanelSide,
+  type SidePanelSize,
+} from './sidePanel';
+export { createToolbarClaims, TOOLBAR_SEAT_KEY, type ToolbarClaims, type ToolbarSeat } from './shell';
+export type { FNavItem, FNavGroup, FCrumb } from './nav';
+export { default as FPageToolbar } from './FPageToolbar.vue';
+export { type PageToolbarWell } from './pageToolbar';
+export { default as FToolbarActions } from './FToolbarActions.vue';

package/src/shell/nav.ts

@@ -0,0 +1,37 @@
+/**
+ * A navigable destination in the app shell's sidebar.
+ *
+ * Deliberately thin. It carries what a row NEEDS to draw itself and nothing about where the list came
+ * from — an app's own nav tree (routes, a manifest, a permissions filter) maps onto this rather than
+ * the shell prescribing a shape for it.
+ *
+ * `to` is optional on purpose: an entry with no destination renders disabled and badged rather than
+ * being dropped, so a system that is still growing reads as intentional instead of missing.
+ */
+export type FNavItem = {
+  label: string;
+  /** Any icon name the app's icon set resolves. */
+  icon?: string;
+  /** Omit for a destination that does not exist yet — the row renders disabled. */
+  to?: string;
+  /** Flags the row as work in progress; it still links. */
+  wip?: boolean;
+};
+
+/** A labelled section of the sidebar. The label heads the group when expanded. */
+export type FNavGroup = {
+  label: string;
+  items: FNavItem[];
+};
+
+/**
+ * A step in the header's crumb — `group · page`.
+ *
+ * `to` is optional and usually absent: a crumb says where you are, and the group half of `group ·
+ * page` is a section of the nav rather than a route. A step that genuinely is a destination can
+ * carry one.
+ */
+export type FCrumb = {
+  label: string;
+  to?: string;
+};

package/src/shell/pageToolbar.ts

@@ -0,0 +1,69 @@
+/**
+ * Which well rung <FPageToolbar> aligns its controls to.
+ *
+ * A toolbar bleeds to the card's edge so its hairline reads as a rule across the whole card, but its
+ * CONTROLS have to line up with the page content below — on a 1720px card those are 252px apart. The
+ * rung must therefore match the page body's own well, which is why the page states it.
+ *
+ * There is no `flush` rung, and that is a judgement rather than an omission. The body's `.well-flush`
+ * exists so a CANVAS reaches the panel edge, and a canvas has no content start to line up with — so
+ * the alignment this prop is for does not arise. Controls also want their gutter whether or not the
+ * surface beneath them does: a filter jammed against the card's edge reads as broken. A canvas page's
+ * toolbar takes `full` — cap released so it spans the card, gutters kept so the controls can breathe.
+ */
+
+export type PageToolbarWell = 'default' | 'reading' | 'full';
+
+const WELLS: Record<PageToolbarWell, string> = {
+  default: '',
+  reading: 'well-reading',
+  full: 'well-full',
+};
+
+export function pageToolbarWellClass(well: PageToolbarWell): string {
+  return WELLS[well];
+}
+
+/**
+ * How the toolbar draws itself.
+ *
+ * `rule` — full-bleed, a hairline across the whole card, no fill. The default, and what a navigation
+ * row wants: it reads as part of the card's chrome.
+ *
+ * `card` — an inset panel: filled, rounded, and clear of all four edges. What a FILTER row wants,
+ * because a row of applied clauses is state the page is currently in rather than chrome, and it needs
+ * to read as a thing sitting on the surface. Linear's shape, and a page mixes the two — navigation on
+ * a rule, filters on a card beneath it.
+ *
+ * The fill alone does NOT carry this. Measured against the card behind it, `bg-muted` is 0.020
+ * luminance in light against 0.060 in dark — which is why a plain tint was probed for this row once
+ * before and rejected as imperceptible in light. What makes the panel read is the RADIUS and the
+ * INSET, which are geometry and behave the same in both modes; the ring gives it an edge of its own.
+ */
+export type PageToolbarVariant = 'rule' | 'card';
+
+export type PageToolbarSurface = {
+  /** Goes on UDashboardToolbar's root, which is the full-bleed layer. */
+  root: string;
+  /** Goes on the flex row inside the well, which is the layer that becomes the panel. */
+  row: string;
+};
+
+const SURFACES: Record<PageToolbarVariant, PageToolbarSurface> = {
+  rule: { root: '', row: '' },
+  // `border-b-0` cancels stock's rule: a panel with a line under it reads as neither one nor the
+  // other. `py-2` is the inset — the well's own gutter already handles the horizontal.
+  //
+  // The ring is MODE-SPLIT, and measured rather than guessed. Against this panel's own `bg-muted`
+  // fill, `ring-default` is 0.072 luminance apart in light but EXACTLY EQUAL in dark (both 0.1497) —
+  // an edge that simply is not there. `ring-accented` clears it by 0.099. Neither token works in both
+  // modes, which is the same collapse the docs code blocks split their frame for.
+  card: {
+    root: 'border-b-0 py-2',
+    row: 'rounded-md bg-muted ring ring-default dark:ring-accented px-2 py-1.5',
+  },
+};
+
+export function pageToolbarSurface(variant: PageToolbarVariant): PageToolbarSurface {
+  return SURFACES[variant];
+}

package/src/shell/shell.ts

@@ -0,0 +1,74 @@
+import { computed, ref, type InjectionKey, type Ref } from 'vue';
+
+/**
+ * The seat <FAppShell> hands down to <FPageToolbar>.
+ *
+ * An element, not a selector string. A shipped component cannot own a global id — two shells on one
+ * page would collide, and a page teleporting by selector has to guess a name the shell happens to
+ * render. Injection also gives the "no shell above me" case for free: `inject` returns null and the
+ * toolbar renders where it was written instead.
+ */
+export type ToolbarSeat = {
+  /**
+   * Inside the panel, at the top of the inset card and ABOVE the page's own scrollport, so a toolbar
+   * holds while the page scrolls under it.
+   */
+  toolbar: Ref<HTMLElement | null>;
+  /**
+   * The right-hand end of the FIRST CLAIMANT's well, filled by <FToolbarActions>.
+   *
+   * The SHELL holds this although the TOOLBAR sets it: a section renders its toolbar and its router
+   * view as siblings, so a view's actions cannot inject from the toolbar — provide/inject walks the
+   * component parent chain and cannot cross siblings. Only something above both can carry it.
+   *
+   * Derived from the claimants rather than assigned, so that a section stacking a nav row over a
+   * filter row keeps the nav row's seam while it is there, and PROMOTES the survivor if it goes.
+   * Null only when no toolbar is mounted at all.
+   */
+  actions: Readonly<Ref<HTMLElement | null>>;
+  /** Called by <FPageToolbar> whenever it appears — mounted, or reactivated inside <KeepAlive>. */
+  claimActions: (el: HTMLElement) => void;
+  /**
+   * Called by <FPageToolbar> whenever it goes — unmounted, or deactivated inside <KeepAlive>.
+   * Promotes the next claimant if this one was first.
+   */
+  releaseActions: (el: HTMLElement) => void;
+};
+
+export const TOOLBAR_SEAT_KEY: InjectionKey<ToolbarSeat> = Symbol('forest-toolbar-seat');
+
+/** The claimant list a seat's `actions` is derived from, plus the two functions that move it. */
+export type ToolbarClaims = Pick<ToolbarSeat, 'actions' | 'claimActions' | 'releaseActions'> & {
+  /** Every claimant, in claim order. `actions` is the first of them. */
+  claimants: Ref<HTMLElement[]>;
+};
+
+/**
+ * Builds the claim state behind a seat.
+ *
+ * <FAppShell> provides one of these, and so does the docs preview that stages a toolbar inside a
+ * frame rather than in the real card. Both owe a page the same ordering, so the ordering lives here
+ * and neither restates it.
+ *
+ * Spread the three seat keys alongside a `toolbar` ref to make a {@link ToolbarSeat}; `claimants` is
+ * the list itself, held out so the order can be read directly.
+ *
+ * Both functions are idempotent — claiming a toolbar already in the list changes nothing, and so
+ * does releasing one that is not in it. A toolbar that claims twice for one appearance, or releases
+ * twice for one departure, still leaves the list right.
+ */
+export function createToolbarClaims(): ToolbarClaims {
+  const claimants = ref<HTMLElement[]>([]);
+  const actions = computed(() => claimants.value[0] ?? null);
+
+  const claimActions = (el: HTMLElement) => {
+    if (!claimants.value.includes(el)) claimants.value.push(el);
+  };
+
+  const releaseActions = (el: HTMLElement) => {
+    const i = claimants.value.indexOf(el);
+    if (i !== -1) claimants.value.splice(i, 1);
+  };
+
+  return { claimants, actions, claimActions, releaseActions };
+}

package/src/shell/sidePanel.ts

@@ -0,0 +1,115 @@
+/**
+ * FSidePanel's measures, and the one calculation anything outside it needs.
+ *
+ * ★ WHY THIS IS A MODULE AND NOT TWO NUMBERS IN A COMPONENT. An overlay panel covers a strip of the
+ * surface it floats on, and three separate things have to agree on how wide that strip is:
+ *
+ *   · the panel, which draws it;
+ *   · the map camera, whose `padding` keeps it clear so a flyTo does not centre underneath the panel;
+ *   · the canvas HUD, whose rails on that edge shift over rather than hiding behind it.
+ *
+ * The first two are the ones that drift: the panel is CSS and the camera is JS, so they cannot read one
+ * value unless something like this exists. (The HUD is reached through a custom property instead — see
+ * CANVAS_INSET_VAR.) This module is that one value, and `sidePanelInsetPx` is the only correct way to
+ * turn a size into the camera's number.
+ */
+
+/** The two rungs. A free `width` prop is deliberately not offered — see SIDE_PANEL_WIDTH. */
+export type SidePanelSize = 'md' | 'lg';
+
+/**
+ * Which edge of its container the panel takes, in logical directions.
+ *
+ * `end` is the default: a panel is secondary chrome inside a shell whose own rail already holds the
+ * start edge, so start would stack two columns on one side. `start` is for the case where the panel is
+ * the navigation for its view — a settings sub-nav.
+ */
+export type SidePanelSide = 'start' | 'end';
+
+/**
+ * Does the content beside it move over, or does the panel lie on top of it?
+ *
+ *   push     the panel is a flow item — a settings sub-nav, a dashboard filter column. The page beside
+ *            it is narrower while it is open.
+ *   overlay  the panel is absolutely positioned over the surface — a filter or list panel on a map. The
+ *            canvas keeps its full size and the panel covers a strip of it.
+ */
+export type SidePanelBehaviour = 'push' | 'overlay';
+
+/**
+ * ★ TWO RUNGS, NOT A NUMBER. A panel's width is a system decision, not a per-page one: two panels a
+ * click apart at 320 and 344 read as a bug, and nothing in a usage site can see the other panel to stay
+ * consistent with it.
+ *
+ *   md   17rem — the same measure as the canvas HUD's wide rail (--forest-canvas-rail-top), so a panel
+ *        and a rail card on the same canvas line up rather than nearly lining up.
+ *   lg   22rem — for a list of rows, where md leaves a row's secondary text with nowhere to go.
+ *
+ * Both are also expressed in px because the camera's `padding` is a JS number and rem is not.
+ */
+export const SIDE_PANEL_WIDTH: Record<SidePanelSize, { css: string; px: number }> = {
+  md: { css: '17rem', px: 272 },
+  lg: { css: '22rem', px: 352 },
+};
+
+/**
+ * The gutter an overlay panel floats in, matching the HUD's own chrome gutter (--forest-chrome-gutter,
+ * 1rem). Duplicated here as a number for the same reason the widths are: the camera cannot read a custom
+ * property. The static test asserts the two stay equal.
+ */
+export const SIDE_PANEL_GUTTER_PX = 16;
+
+/**
+ * The strip an OVERLAY panel covers, in px — what `<FMap :padding>` should keep clear on that edge.
+ *
+ *   gutter + panel + gutter
+ *
+ * Both gutters count HERE, and only here: the outer one is the space between the panel and the canvas
+ * edge, the inner one is clearance. A camera inset of just the panel's width parks a marker flush
+ * against the panel's edge, which reads as "hidden behind it" even though it is not. Chrome does not
+ * want that second gutter — it brings its own — so CANVAS_INSET_VAR publishes one gutter fewer.
+ *
+ * Returns 0 when the panel is closed, so a usage site is one expression rather than a branch:
+ *
+ *   :padding="{ right: sidePanelInsetPx('lg', open) }"   // key matches the panel's side
+ */
+export const sidePanelInsetPx = (size: SidePanelSize, open = true): number =>
+  open ? SIDE_PANEL_WIDTH[size].px + SIDE_PANEL_GUTTER_PX * 2 : 0;
+
+/**
+ * The custom property an overlay panel declares on its container so <FCanvasHud> insets its rails on
+ * that edge. The HUD adds it to the safe-area inset it already keeps clear, so a panel and a device
+ * notch compose instead of one overwriting the other.
+ *
+ * ★ ITS VALUE IS NOT `sidePanelInsetPx`, and the difference is deliberate. This publishes the strip the
+ * panel OCCUPIES (outer gutter + width); the camera's number adds a second gutter of clearance. The
+ * HUD's areas already carry the chrome gutter as internal padding, so a trailing gutter here lands
+ * twice — measured, it left a 32px trough between the panel and the first rail item where every other
+ * pair of chrome on that canvas shares 16.
+ *
+ * A property rather than a prop because the HUD and the panel are siblings, not parent and child: the
+ * panel cannot pass anything to the HUD, but it can declare on the ancestor they share.
+ *
+ * ★ PHYSICAL sides, because what they are added to is physical: `env(safe-area-inset-*)` describes a
+ * notch, which does not move under RTL. The panel's own `side` is logical and maps to these here — the
+ * one place that mapping would have to become direction-aware if an RTL surface ever ships.
+ */
+export const CANVAS_INSET_VAR = {
+  start: '--forest-canvas-inset-left',
+  end: '--forest-canvas-inset-right',
+} as const satisfies Record<SidePanelSide, string>;
+
+/**
+ * How long the panel's own travel takes, published alongside the inset.
+ *
+ * ★ THE INSET WITHOUT THE DURATION IS WORSE THAN NEITHER. Everything that follows an open panel — the
+ * HUD's rails, the map's camera — otherwise moves in ONE frame while the panel glides for 240ms: three
+ * things responding to one gesture, only one of them animated. That reads as the panel being smooth and
+ * everything else being broken.
+ *
+ * Published rather than assumed because the panel's travel is ASYMMETRIC (a fast exit, a slower enter),
+ * so a follower that hard-coded one duration would lag on the way out. Written as a resolved time
+ * (`240ms`), not a `var()` reference, because one of the readers is JS: Mapbox's camera takes a number,
+ * and it cannot resolve a token itself.
+ */
+export const CANVAS_INSET_DURATION_VAR = '--forest-canvas-inset-duration';