@humanforest/ui 0.1.0

package/src/canvas/FCanvasControlGroup.vue

@@ -0,0 +1,100 @@
+<script setup lang="ts">
+// A merged cluster of canvas controls — zoom in / zoom out, or a set of map modes. Reads as ONE control
+// with several positions, which is why the members share one surface rather than floating as separate
+// tiles.
+//
+//   <FCanvasControlGroup>
+//     <FCanvasControl icon="i-lucide-plus" label="Zoom in" />
+//     <FCanvasControl icon="i-lucide-minus" label="Zoom out" />
+//   </FCanvasControlGroup>
+//
+// ★ THE GROUP OWNS THE SURFACE, and its members go transparent. Not cosmetic: the canvas-chrome surface
+// is translucent AND blurred, so a per-member surface would stack alpha and blur at every seam and draw
+// the joins as darker bands — the opposite of merged. One surface, hairlines inside it, radius on the
+// outer corners only.
+//
+// ★ WHY NOT <UFieldGroup>, which already joins controls and supports a vertical orientation. Because it
+// merges BORDERS, not SURFACES: `-space-y-px` overlaps its children by a pixel so their rings collapse
+// into one, and every child keeps its own background. That is exactly right for opaque form controls and
+// wrong here — the canvas surface is translucent AND backdrop-blurred, so per-child surfaces stack their
+// alpha at every overlap and each runs its own blur pass, sampling the map separately. The cluster stops
+// being one pane of glass and shows its joins as darker, differently-blurred bands.
+//
+// So the geometry is the easy half (a flex column, a hairline between, one radius) and the surface is the
+// reason this component exists: ONE fill, ONE blur, members bare.
+//
+// ★ Styled through child selectors rather than provide/inject — not because injection cannot reach slot
+// content (it can: Vue resolves it through the mounted tree, which is how UFieldGroup talks to its own
+// children), but because these members are not ours to instruct. A member is an <FCanvasControl> whose
+// surface comes from a utility class, and a child selector switches that off through the utility's own
+// vars without the member needing to know it is in a group at all.
+//
+// ★ THE EDGE IS THE BUTTON'S EDGE, and it took two measurements to get right. A lone control draws
+// `ring-accented` INSET (the outline button's own recipe); this group first drew `ring-default` OUTSET,
+// which differs twice over — a lighter colour, and a ring outside the box, so the cluster sat a pixel
+// wider than the controls beside it. Merged and lone have to be the same object at different lengths.
+// The inner hairlines take the same token for the same reason: one edge colour per cluster.
+//
+// ★ AND THE EDGE IS PAINTED ON A LAYER ABOVE THE MEMBERS. An inset box-shadow paints above its own
+// element's background but BELOW its descendants, so the moment a member takes a hover fill — which
+// spans the member's full width — it covers the group's ring along that member's edges and the border
+// breaks exactly where the pointer is. An overlay pseudo-element cannot be covered by a sibling's
+// background, so the edge survives every state a member can be in.
+//
+// ★ A PRESSED member keeps its solid fill: it is the one part that must stay opaque, and inside a merged
+// cluster it fills its whole cell so the selection reads as a position rather than a floating tile.
+//
+// What belongs in one group: actions on the same subject. Zoom in and zoom out, yes; zoom and "open
+// filters", no — a merged cluster claims the two things are one control, and unrelated actions in one
+// stack make that claim falsely.
+import { computed } from 'vue';
+
+const props = withDefaults(
+  defineProps<{
+    /**
+     * Rails stack, so `vertical` is the default. The hub is the one horizontal area — pass
+     * `orientation="horizontal"` there.
+     *
+     * Not inferred from the area it sits in, and injection could not do it even though it would reach
+     * here: a `provide` is one value per HUD instance, and the HUD's areas disagree — its rails are
+     * vertical and its hub is horizontal, so a single provided orientation would be wrong in one of them.
+     * The alternative (a stylesheet rule keyed on `[data-area]`) would bury HUD knowledge in this
+     * component's CSS. The author already chose the area; this says so out loud.
+     */
+    orientation?: 'vertical' | 'horizontal';
+  }>(),
+  { orientation: 'vertical' },
+);
+
+const vertical = computed(() => props.orientation === 'vertical');
+
+// The members: surface off, radius off, and the ring off — the group draws all three once. Only the
+// hairline between members is theirs, and it goes on the leading edge of every member but the first.
+// ★ The surface is switched off through the utility's own VARS, not by out-specifying it. The chrome
+// rule is deliberately doubled (`.forest-canvas-chrome.forest-canvas-chrome`) so component recipes cannot
+// beat it, which means a child selector here loses too — measured, the members kept their own fill and
+// blur and the cluster showed its seams. Declaring the var on the child sidesteps the contest entirely.
+const members = [
+  '[&>*]:[--forest-canvas-chrome-fill:transparent] [&>*]:[--forest-canvas-chrome-blur:none]',
+  // ★ NO RULE BETWEEN MEMBERS. Mapbox's own control group draws one, and an earlier cut of this did
+  // too, on the reasoning that two squares in one pill would otherwise read as a single tall button.
+  // Over a canvas they lose that argument: the surface is a small pane of glass on a busy, moving map,
+  // and every line inside it competes with the map's own. Hover and press do the separating instead —
+  // they land on ONE member and end at its edges, which is a stronger boundary than a hairline because
+  // it appears exactly when the pointer is asking where the boundary is.
+  '[&>*]:rounded-none [&>*]:ring-0 [&>*]:shadow-none',
+].join(' ');
+</script>
+
+<template>
+  <div
+    class="forest-canvas-chrome pointer-events-auto relative flex overflow-hidden rounded-md after:pointer-events-none after:absolute after:inset-0 after:rounded-md after:ring after:ring-inset after:ring-accented"
+    :class="[
+      vertical ? 'flex-col' : 'flex-row',
+      members,
+    ]"
+    role="group"
+  >
+    <slot />
+  </div>
+</template>

package/src/canvas/FCanvasFlyout.vue

@@ -0,0 +1,216 @@
+<script setup lang="ts">
+// One canvas control that opens into a cluster of them, in place.
+//
+//   <FCanvasFlyout icon="i-lucide-lasso" label="Selection tools" :items="tools" @select="pick" />
+//
+// ★ WHY IT EXISTS. A rail is a narrow column shared with the zoom pair, the compass and the rest, and
+// four controls stacked is 144px of a 480px map before anything else gets its share. This is one
+// control at rest, and the cluster exists only while a reader is choosing from it — the only moment it
+// says anything.
+//
+// ★ IT OPENS ACROSS THE RAIL, NOT ALONG IT. `orientation` is the axis the cluster opens ALONG, and it
+// defaults to horizontal precisely because rails are vertical: a group that grew downward would push
+// every control below it along, every time someone glanced at the tools. Opening across spends space
+// the canvas has and the rail does not.
+//
+// ★ AND IT IS AN OVERLAY, NOT A RESIZE. The wrapper only ever occupies the trigger; the cluster is
+// absolutely positioned from it. A rail hugs its widest child (`fit-content`), so a cluster that grew
+// in flow would widen the whole column and drag its neighbours sideways — measured, before this was
+// positioned out of flow.
+//
+// ★ NOT A POPOVER. It grows contiguously from the trigger and shares one surface with it, so it reads
+// as one object opening rather than a panel arriving beside it: no anchor to position, nothing to
+// teleport, no second pane of glass. <FMapSearch> takes the same view for the same reason.
+import { computed, ref, watch } from 'vue';
+import FCanvasControl from './FCanvasControl.vue';
+
+/** One member of the cluster. `value` is what comes back on select. */
+export interface FlyoutItem {
+  value: string;
+  icon: string;
+  label: string;
+  /** lit — for a cluster of modes, the one currently held */
+  pressed?: boolean;
+}
+
+import FCanvasControlGroup from './FCanvasControlGroup.vue';
+
+const open = defineModel<boolean>('open', { default: false });
+
+const emit = defineEmits<{ select: [value: string] }>();
+
+const props = withDefaults(
+  defineProps<{
+    /**
+     * The trigger's icon at rest.
+     *
+     * ★ Deliberately not derived. A flyout of MODES usually wants the active one here, so a reader can
+     * see what is in their hand without opening anything; a flyout of one-shot ACTIONS wants a fixed
+     * icon, because there is no state to report. The component cannot tell which it is in, so it does
+     * not try.
+     */
+    icon: string;
+    label: string;
+    /** Lit at rest — for a mode flyout, whether the mode it names is active. */
+    pressed?: boolean;
+    /** The axis the cluster opens along. Horizontal suits a vertical rail, and vice versa. */
+    orientation?: 'vertical' | 'horizontal';
+    /** Which end the trigger is pinned to, so the cluster opens INWARD rather than off the canvas. */
+    side?: 'start' | 'end';
+    /**
+     * The controls the cluster holds.
+     *
+     * ★ Items rather than a slot, and the motion is why. A cluster's members enter and leave, and
+     * <TransitionGroup> can only drive vnodes it created — hand it slot content and the classes never
+     * land on anything (measured: members appeared with the button's own transition and no enter
+     * class at all). Owning the members buys working motion; the cost is that a member is an icon
+     * control rather than arbitrary markup, which is all a cluster of chrome ever is.
+     */
+    items?: FlyoutItem[];
+    /** Icon for the dismiss the trigger becomes while open. */
+    closeIcon?: string;
+    /** Accessible name for that dismiss. */
+    closeLabel?: string;
+  }>(),
+  {
+    items: () => [],
+    pressed: undefined,
+    orientation: 'horizontal',
+    side: 'end',
+    closeIcon: 'i-lucide-x',
+    closeLabel: 'Close',
+  },
+);
+
+const root = ref<HTMLElement | null>(null);
+const close = () => (open.value = false);
+
+// Picking closes: a cluster of modes has said everything it has to say once one is chosen.
+function choose(value: string) {
+  emit('select', value);
+  close();
+}
+
+/**
+ * Where a member starts from: just inside the trigger, so the cluster reads as unfolding OUT of it
+ * rather than materialising beside it.
+ *
+ * ★ `translate-*`, and the transition names `translate` — not `transform`. In Tailwind v4 the
+ * translate utilities set the `translate` property, so a `transition-[opacity,transform]` would
+ * animate the fade alone and snap the movement.
+ */
+const from = computed(() => {
+  const d = '0.5rem';
+  if (props.orientation === 'horizontal')
+    return { '--forest-flyout-x': props.side === 'end' ? d : `-${d}`, '--forest-flyout-y': '0' };
+  return { '--forest-flyout-x': '0', '--forest-flyout-y': props.side === 'end' ? d : `-${d}` };
+});
+
+/**
+ * ★ A CSS ANIMATION, NOT <TransitionGroup>. Measured: with the members inside a TransitionGroup —
+ * both as slot content and rendered here — the enter classes never landed on them at all; every
+ * member showed the button's own `transition-property` and no opacity or translate of its own. An
+ * animation runs on mount by construction, which is exactly when a member appears, and nothing has
+ * to be wired correctly for it to fire.
+ */
+
+// ★ Focus alone cannot dismiss this. A map canvas is not focusable, so pressing on it may move focus
+// nowhere at all, and the cluster would sit open over the very thing the reader reached for. Watching
+// pointerdown catches the press wherever it lands.
+watch(open, (isOpen, _was, onCleanup) => {
+  if (!isOpen) return;
+  const away = (e: PointerEvent) => {
+    if (!root.value?.contains(e.target as Node)) close();
+  };
+  // Capture, so a handler that stops propagation cannot leave the cluster open behind its own panel.
+  document.addEventListener('pointerdown', away, true);
+  onCleanup(() => document.removeEventListener('pointerdown', away, true));
+});
+
+// The keyboard still moves focus properly, so this covers tabbing away.
+function onFocusOut() {
+  requestAnimationFrame(() => {
+    if (!open.value) return;
+    if (root.value?.contains(document.activeElement)) return;
+    close();
+  });
+}
+</script>
+
+<style>
+/* One keyframe serves all four placements; the flyout sets the axis it enters from. */
+@keyframes forest-flyout-in {
+  from {
+    opacity: 0;
+    translate: var(--forest-flyout-x, 0) var(--forest-flyout-y, 0);
+  }
+}
+.forest-flyout-in {
+  /* No var() fallbacks. They had already DRIFTED: 150ms is Tailwind's stock default, not
+     --motion-fast's 140ms, and the bare `ease-out` keyword is the weak built-in the doctrine bans
+     outright — so the "safety net" quietly contradicted the ladder it was netting. The tokens ship
+     with the layer now (packages/tokens/motion/motion.css), so an absent value means a broken
+     install, which should look broken rather than silently animate off-doctrine. */
+  animation: forest-flyout-in var(--motion-fast) var(--motion-ease-out) both;
+}
+/* The global floor covers transitions; an animation has to be said separately. */
+@media (prefers-reduced-motion: reduce) {
+  .forest-flyout-in {
+    animation: none;
+  }
+}
+</style>
+
+<template>
+  <div
+    ref="root"
+    class="pointer-events-auto relative"
+    :style="from"
+    :class="orientation === 'horizontal' ? 'h-(--forest-canvas-control)' : 'w-(--forest-canvas-control)'"
+    @keydown.escape="close"
+    @focusout="onFocusOut"
+  >
+    <FCanvasControlGroup
+      :orientation="orientation"
+      class="absolute"
+      :class="
+        orientation === 'horizontal'
+          ? ['top-0', side === 'end' ? 'end-0' : 'start-0']
+          : ['start-0', side === 'end' ? 'bottom-0' : 'top-0']
+      "
+    >
+      <!-- Order follows `side` so the TRIGGER stays put and the cluster appears beside it. Pinned at
+           the end, members render first and the trigger last — otherwise opening would walk the
+           trigger off the edge it is anchored to. -->
+        <FCanvasControl
+          v-for="item in open && side === 'end' ? items : []"
+          :key="item.value"
+          :icon="item.icon"
+          :label="item.label"
+          :pressed="item.pressed"
+          class="forest-flyout-in"
+          @click="choose(item.value)"
+        />
+
+      <!-- Closed it is the thing itself; open it is the way out. A dismiss rather than a member,
+           because a member that also closed the cluster would be indistinguishable from one that
+           does not. -->
+      <FCanvasControl
+        :icon="open ? closeIcon : icon"
+        :label="open ? closeLabel : label"
+        :pressed="open ? undefined : pressed"
+        @click="open = !open"
+      />
+
+        <FCanvasControl
+          v-for="item in open && side === 'start' ? items : []"
+          :key="item.value"
+          :icon="item.icon"
+          :label="item.label"
+          :pressed="item.pressed"
+          class="forest-flyout-in"
+          @click="choose(item.value)"
+        />
+    </FCanvasControlGroup>
+  </div>
+</template>