@cfasim-ui/docs 0.5.0 → 0.6.0

package/charts/_shared/chartProps.ts

@@ -148,6 +148,16 @@ export interface ChartCommonProps {
    * are set, `downloadButton` wins.
    */
   downloadButton?: boolean | string;
+  /**
+   * Where to teleport the chart while expanded (the Expand menu item). A
+   * CSS selector or element; defaults to `body`. The expanded chart is
+   * moved here so its `position: fixed` resolves against the viewport
+   * instead of being trapped by an ancestor's `transform`/`filter`/
+   * `contain`/`perspective` (which would otherwise become its containing
+   * block) or stacking context. Set this when your app doesn't mount at
+   * the document root (e.g. inside a shadow root or a dedicated overlay).
+   */
+  fullscreenTarget?: string | HTMLElement;
   /** Annotations rendered as the top layer of the chart. */
   annotations?: readonly ChartAnnotation[];
   /**

package/charts/_shared/useChartFoundation.ts

@@ -26,6 +26,7 @@ export interface ChartFoundationOptions {
   filename: () => string | undefined;
   downloadLink: () => boolean | string | undefined;
   downloadButton: () => boolean | string | undefined;
+  fullscreenTarget: () => string | HTMLElement | undefined;
   chartPadding: () => ChartPadding | undefined;
   // Chart-specific hooks that the composable can't infer.
   /**
@@ -38,6 +39,12 @@ export interface ChartFoundationOptions {
   getCsv: () => string;
   pointerToIndex: (clientX: number, clientY: number) => number | null;
   onHover: (payload: { index: number } | null) => void;
+  /**
+   * Axis a finger drags along to scrub the tooltip on touch; the
+   * orthogonal direction is left to the browser for page scrolling.
+   * Defaults to `"x"`.
+   */
+  scrubAxis?: () => "x" | "y";
   /**
    * Extra height (in px) the chart adds *below* the SVG plot area
    * (e.g. LineChart's area-section labels). Used to keep the SVG total
@@ -66,6 +73,9 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
     triggerCsvDownload,
     resolvedFilename: menuFilename,
     isFullscreen,
+    fullscreenStyle,
+    teleportTarget,
+    exitFullscreen,
   } = useChartMenu({
     filename: opts.filename,
     legacyMenuLabel: opts.menu,
@@ -73,6 +83,7 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
     downloadLink: opts.downloadLink,
     downloadButton: opts.downloadButton,
     fullscreen: true,
+    fullscreenTarget: opts.fullscreenTarget,
   });
 
   const width = computed(() => {
@@ -113,6 +124,7 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
     clamp: () => opts.tooltipClamp() ?? "chart",
     pointerToIndex: opts.pointerToIndex,
     containerRef,
+    scrubAxis: opts.scrubAxis,
     onHover: opts.onHover,
   });
 
@@ -138,6 +150,9 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
     triggerCsvDownload,
     menuFilename,
     isFullscreen,
+    fullscreenStyle,
+    teleportTarget,
+    exitFullscreen,
     measuredHeight,
   };
 }

package/charts/_shared/useChartFullscreen.ts

@@ -27,15 +27,38 @@ function unlockBodyScroll() {
   }
 }
 
+export interface ChartFullscreenOptions {
+  /**
+   * Reactive getter for where to teleport the expanded chart. A CSS
+   * selector or element; resolves to `"body"` when unset. Teleporting
+   * out to the document root is what makes `position: fixed` reliable:
+   * a `transform`/`filter`/`contain`/`perspective` on any ancestor would
+   * otherwise become the containing block and trap the "fullscreen" box
+   * inside it.
+   */
+  target?: () => string | HTMLElement | undefined;
+}
+
 /**
- * Tracks whether the chart is in "expanded" mode (fills the window via
- * CSS). The browser Fullscreen API isn't used — the consumer wires a
- * `.is-fullscreen` class to its wrapper and the CSS handles positioning,
- * which avoids Fullscreen API restrictions (user-gesture requirement,
- * permission policy, iframe sandboxing) and keeps the chart inside the
- * document so the rest of the page remains keyboard-navigable.
+ * Tracks whether the chart is in "expanded" mode (fills the window). The
+ * browser Fullscreen API isn't used — avoiding its restrictions
+ * (user-gesture requirement, permission policy, iframe sandboxing) and
+ * keeping the chart inside the document so the rest of the page stays
+ * keyboard-navigable.
+ *
+ * Resilience is the whole point here, so the layout is driven two ways
+ * that don't depend on the CSS cascade:
+ *  - `fullscreenStyle` returns the critical layout as an *inline* style
+ *    object. Inline styles outrank any class rule regardless of stylesheet
+ *    source order, so they beat each chart's scoped `position: relative`
+ *    base rule (equal specificity, and the scoped rule often loads last)
+ *    and still work even if the consumer never imported the package CSS.
+ *  - `teleportTarget` moves the node to the document root so the fixed
+ *    positioning resolves against the viewport, not a transformed ancestor.
+ * The `.is-fullscreen` class remains on the wrapper only as a hook for the
+ * one rule inline styles can't express (ChoroplethMap's SVG stretch).
  */
-export function useChartFullscreen() {
+export function useChartFullscreen(opts: ChartFullscreenOptions = {}) {
   const isFullscreen = ref(false);
   let locked = false;
 
@@ -95,10 +118,44 @@ export function useChartFullscreen() {
    * that builds its menu list directly.
    */
   const menuItem = computed<ChartMenuItem>(() => ({
-    label: isFullscreen.value ? "Collapse" : "Expand",
+    label: isFullscreen.value ? "Collapse" : "Fullscreen",
     action: toggle,
     ariaPressed: isFullscreen.value,
   }));
 
-  return { isFullscreen, toggle, enter, exit, menuItem };
+  /**
+   * Critical fullscreen layout as inline styles (only while expanded).
+   * Bound via `:style` on the chart wrapper so it always wins over the
+   * scoped base rule and survives a missing stylesheet import.
+   */
+  const fullscreenStyle = computed<Record<string, string> | undefined>(() =>
+    isFullscreen.value
+      ? {
+          position: "fixed",
+          inset: "0",
+          "z-index": "var(--cfasim-z-fullscreen, 1000)",
+          background: "var(--color-bg-0, #fff)",
+          color: "var(--color-text, inherit)",
+          padding: "2em",
+          "box-sizing": "border-box",
+          display: "flex",
+          "flex-direction": "column",
+          "justify-content": "center",
+        }
+      : undefined,
+  );
+
+  const teleportTarget = computed<string | HTMLElement>(
+    () => opts.target?.() || "body",
+  );
+
+  return {
+    isFullscreen,
+    toggle,
+    enter,
+    exit,
+    menuItem,
+    fullscreenStyle,
+    teleportTarget,
+  };
 }

package/charts/_shared/useChartMenu.ts

@@ -14,16 +14,18 @@ export interface ChartMenuOptions {
   /** Whether a separate download button is rendered (and the CSV menu item should be hidden). */
   downloadButton?: () => boolean | string | undefined;
   /**
-   * When true, prepends an Expand/Collapse menu item that toggles the
-   * chart into a full-window view. The consumer is responsible for
-   * binding the returned `isFullscreen` ref to a CSS class on its
-   * wrapper.
+   * When true, prepends a Fullscreen menu item that toggles the chart
+   * into a full-window view. The consumer binds the returned
+   * `isFullscreen` class plus `fullscreenStyle` to its wrapper and wraps
+   * it in a `<Teleport :to="teleportTarget" :disabled="!isFullscreen">`.
    */
   fullscreen?: boolean;
+  /** Forwarded to `useChartFullscreen` — see its `target` option. */
+  fullscreenTarget?: () => string | HTMLElement | undefined;
 }
 
 /**
- * Computes the standard chart menu items (Expand / SVG / PNG / CSV) plus
+ * Computes the standard chart menu items (Fullscreen / SVG / PNG / CSV) plus
  * the CSV-download-link state shared by every chart.
  */
 export function useChartMenu(opts: ChartMenuOptions) {
@@ -36,7 +38,9 @@ export function useChartMenu(opts: ChartMenuOptions) {
     return typeof menu === "string" ? menu : "chart";
   }
 
-  const fullscreen = opts.fullscreen ? useChartFullscreen() : null;
+  const fullscreen = opts.fullscreen
+    ? useChartFullscreen({ target: opts.fullscreenTarget })
+    : null;
 
   const items = computed<ChartMenuItem[]>(() => {
     const fname = resolvedFilename();
@@ -100,5 +104,8 @@ export function useChartMenu(opts: ChartMenuOptions) {
     triggerCsvDownload,
     resolvedFilename,
     isFullscreen: fullscreen?.isFullscreen ?? ref(false),
+    fullscreenStyle: fullscreen?.fullscreenStyle ?? computed(() => undefined),
+    teleportTarget: fullscreen?.teleportTarget ?? computed(() => "body"),
+    exitFullscreen: fullscreen?.exit ?? (() => {}),
   };
 }

package/charts/_shared/useChartTooltip.ts

@@ -19,6 +19,13 @@ export interface ChartTooltipOptions {
   containerRef: Ref<HTMLElement | null>;
   /** Pointer-vertical offset applied for touch interactions. */
   touchYOffset?: number;
+  /**
+   * Axis a finger drags *along* to scrub the tooltip. On touch, a drag in
+   * the orthogonal direction is left to the browser so the page can still
+   * scroll. Defaults to `"x"` (horizontal scrub, vertical page scroll) —
+   * correct for time-series line charts and vertical bar charts.
+   */
+  scrubAxis?: () => "x" | "y";
   /**
    * Emit hover events. The first arg is `{ index }` while hovering and
    * `null` when leaving.
@@ -33,12 +40,21 @@ export interface ChartTooltipOptions {
  */
 export function useChartTooltip(opts: ChartTooltipOptions) {
   const TOUCH_Y_OFFSET = opts.touchYOffset ?? 50;
+  // Pixels a finger must travel before we commit a touch drag to either
+  // scrubbing the tooltip or scrolling the page.
+  const TOUCH_SLOP = 10;
   const hoverIndex = ref<number | null>(null);
   const isTouching = ref(false);
   const tooltipRef = ref<HTMLElement | null>(null);
   const pointer = ref<{ clientX: number; clientY: number } | null>(null);
   const tooltipPos = ref<{ left: number; top: number } | null>(null);
 
+  // Touch-gesture tracking (plain locals — they don't drive rendering).
+  // "pending" until the drag direction is known; then "scrub" (we own the
+  // gesture and move the tooltip) or "scroll" (the browser scrolls the page).
+  let touchStart: { x: number; y: number } | null = null;
+  let touchMode: "pending" | "scrub" | "scroll" = "pending";
+
   function pointerFromEvent(
     event: MouseEvent | TouchEvent,
   ): { clientX: number; clientY: number } | null {
@@ -110,13 +126,47 @@ export function useChartTooltip(opts: ChartTooltipOptions) {
 
   function onTouchStart(event: TouchEvent) {
     if (!opts.enabled()) return;
-    event.preventDefault();
+    const pt = pointerFromEvent(event);
+    if (!pt) return;
+    // Don't preventDefault here: that would cancel the browser's scroll for
+    // the whole gesture before we know its direction. We decide on the
+    // first move instead. (`touch-action` on the overlay caps which
+    // direction the browser may still claim.)
+    touchStart = { x: pt.clientX, y: pt.clientY };
+    touchMode = "pending";
     isTouching.value = true;
     updateHover(event);
   }
 
   function onTouchMove(event: TouchEvent) {
     if (!opts.enabled()) return;
+    // The page owns this gesture — let it scroll, leave the tooltip hidden.
+    if (touchMode === "scroll") return;
+
+    if (touchMode === "pending") {
+      const pt = pointerFromEvent(event);
+      if (!pt || !touchStart) return;
+      const dx = Math.abs(pt.clientX - touchStart.x);
+      const dy = Math.abs(pt.clientY - touchStart.y);
+      if (dx + dy < TOUCH_SLOP) {
+        // Too small to classify — track under the finger, but don't yet
+        // preventDefault so the browser can still start a scroll.
+        updateHover(event);
+        return;
+      }
+      const scrubAxis = opts.scrubAxis?.() ?? "x";
+      const isScrub = scrubAxis === "x" ? dx >= dy : dy >= dx;
+      if (!isScrub) {
+        // Drag is across the scrub axis — hand the gesture to the browser.
+        touchMode = "scroll";
+        hoverIndex.value = null;
+        opts.onHover?.(null);
+        return;
+      }
+      touchMode = "scrub";
+    }
+
+    // Scrubbing: we own the gesture, so suppress the native scroll.
     event.preventDefault();
     updateHover(event);
   }
@@ -124,14 +174,17 @@ export function useChartTooltip(opts: ChartTooltipOptions) {
   function onTouchEnd() {
     if (!opts.enabled()) return;
     isTouching.value = false;
+    touchStart = null;
+    touchMode = "pending";
     hoverIndex.value = null;
     opts.onHover?.(null);
   }
 
   // Note: when binding via `v-on="handlers"`, Vue expects event names
-  // *without* the `on` prefix. Touch events default to passive in some
-  // contexts; consumers using touch overlays should still bind the
-  // touch handlers individually with `.prevent`.
+  // *without* the `on` prefix. The touch handlers call `preventDefault`
+  // internally (only while scrubbing), so the overlay must NOT bind them
+  // passively, and should set `touch-action` to the scroll direction it
+  // wants to keep (e.g. `pan-y` when `scrubAxis` is `"x"`).
   const handlers = {
     mousemove: onMouseMove,
     mouseleave: onMouseLeave,

package/charts/index.ts

@@ -1,5 +1,3 @@
-import "./_shared/fullscreen.css";
-
 export {
   default as LineChart,
   type LineChartData,

package/components/ButtonGroup/ButtonGroup.md

@@ -0,0 +1,64 @@
+# ButtonGroup
+
+A container that visually joins a set of [`Button`](./button)s (or any
+elements) into a single connected unit. It only handles layout and styling —
+each button keeps its own click handler and state. For a stateful "pick one (or
+more)" control that looks like a button group, use
+[`ToggleGroup`](./toggle-group) instead.
+
+## Examples
+
+### Joined buttons
+
+<ComponentDemo>
+  <ButtonGroup aria-label="Document actions">
+    <Button variant="secondary">Cut</Button>
+    <Button variant="secondary">Copy</Button>
+    <Button variant="secondary">Paste</Button>
+  </ButtonGroup>
+
+<template #code>
+
+```vue
+<ButtonGroup aria-label="Document actions">
+  <Button variant="secondary">Cut</Button>
+  <Button variant="secondary">Copy</Button>
+  <Button variant="secondary">Paste</Button>
+</ButtonGroup>
+```
+
+  </template>
+</ComponentDemo>
+
+### Vertical
+
+Set `orientation="vertical"` to stack the buttons. They stretch to a common
+width so the dividers line up.
+
+<ComponentDemo>
+  <ButtonGroup orientation="vertical" aria-label="Zoom">
+    <Button>Zoom in</Button>
+    <Button>Reset</Button>
+    <Button>Zoom out</Button>
+  </ButtonGroup>
+
+<template #code>
+
+```vue
+<ButtonGroup orientation="vertical" aria-label="Zoom">
+  <Button>Zoom in</Button>
+  <Button>Reset</Button>
+  <Button>Zoom out</Button>
+</ButtonGroup>
+```
+
+  </template>
+</ComponentDemo>
+
+## Props
+
+| Prop | Type | Required | Default |
+|------|------|----------|---------|
+| `ariaLabel` | `string` | No | — |
+| `orientation` | `"horizontal" \| "vertical"` | No | `"horizontal"` |
+

package/components/ButtonGroup/ButtonGroup.vue

@@ -0,0 +1,91 @@
+<script setup lang="ts">
+withDefaults(
+  defineProps<{
+    ariaLabel?: string;
+    orientation?: "horizontal" | "vertical";
+  }>(),
+  { orientation: "horizontal" },
+);
+</script>
+
+<template>
+  <div
+    class="button-group"
+    role="group"
+    :data-orientation="orientation"
+    :aria-label="ariaLabel"
+  >
+    <slot />
+  </div>
+</template>
+
+<style scoped>
+.button-group {
+  display: inline-flex;
+}
+
+.button-group[data-orientation="vertical"] {
+  flex-direction: column;
+}
+
+/* Children butt directly against each other; only the outer corners stay
+ * rounded and all children stretch to a common size. */
+.button-group :deep(> *) {
+  border-radius: 0;
+  align-self: stretch;
+}
+
+/* Pull each child onto its neighbour so a pair of adjacent borders collapses
+ * into a single shared 1px divider (instead of two borders + a gap). */
+.button-group[data-orientation="horizontal"] :deep(> *:not(:first-child)) {
+  margin-left: -1px;
+}
+
+.button-group[data-orientation="vertical"] :deep(> *:not(:first-child)) {
+  margin-top: -1px;
+}
+
+/* Lift the active child so its full border / focus ring shows above the
+ * overlapping neighbour. */
+.button-group :deep(> *:hover),
+.button-group :deep(> *:focus-visible),
+.button-group :deep(> *:focus) {
+  position: relative;
+  z-index: 1;
+}
+
+/* Bordered buttons share their border as the divider. The solid `Button`
+ * variant has no border, so give adjacent solid buttons a divider of their
+ * own (a contrast-derived hairline that reads on the button colour). */
+.button-group[data-orientation="horizontal"]
+  :deep(.button[data-variant="primary"] + .button[data-variant="primary"]) {
+  border-left: 1px solid
+    color-mix(in srgb, var(--color-text-on-primary) 35%, transparent);
+}
+
+.button-group[data-orientation="vertical"]
+  :deep(.button[data-variant="primary"] + .button[data-variant="primary"]) {
+  border-top: 1px solid
+    color-mix(in srgb, var(--color-text-on-primary) 35%, transparent);
+}
+
+.button-group[data-orientation="horizontal"] :deep(> *:first-child) {
+  border-top-left-radius: 0.375em;
+  border-bottom-left-radius: 0.375em;
+}
+
+.button-group[data-orientation="horizontal"] :deep(> *:last-child) {
+  border-top-right-radius: 0.375em;
+  border-bottom-right-radius: 0.375em;
+}
+
+.button-group[data-orientation="vertical"] :deep(> *:first-child) {
+  border-top-left-radius: 0.375em;
+  border-top-right-radius: 0.375em;
+}
+
+.button-group[data-orientation="vertical"] :deep(> *:last-child) {
+  border-bottom-left-radius: 0.375em;
+  border-bottom-right-radius: 0.375em;
+}
+</style>

package/components/MultiSelect/MultiSelect.md

@@ -0,0 +1,143 @@
+# MultiSelect
+
+A multi-select combobox with autocomplete. Built on reka-ui's Combobox: type to
+filter the options, click to add them, and selected values appear as removable
+chips. Binds to a `string[]` via `v-model`.
+
+## Examples
+
+<script setup>
+import { ref } from 'vue'
+const states = ref(['ca'])
+const stationery = ref([])
+</script>
+
+<ComponentDemo>
+  <div style="width: 280px">
+    <MultiSelect
+      v-model="states"
+      label="States"
+      placeholder="Search states…"
+      :options="[
+        { value: 'ca', label: 'California' },
+        { value: 'ny', label: 'New York' },
+        { value: 'tx', label: 'Texas' },
+        { value: 'wa', label: 'Washington' },
+        { value: 'fl', label: 'Florida' },
+      ]"
+    />
+  </div>
+
+<template #code>
+
+```vue
+<script setup>
+import { ref } from "vue";
+const states = ref(["ca"]);
+</script>
+
+<MultiSelect
+  v-model="states"
+  label="States"
+  placeholder="Search states…"
+  :options="[
+    { value: 'ca', label: 'California' },
+    { value: 'ny', label: 'New York' },
+    { value: 'tx', label: 'Texas' },
+    { value: 'wa', label: 'Washington' },
+    { value: 'fl', label: 'Florida' },
+  ]"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+Type in the field to filter, click an option to add it, and use a chip's `✕`
+button (or press Backspace in an empty input) to remove a selection.
+
+### Hidden label
+
+Use `hide-label` to visually hide the label while keeping it available to screen
+readers. Prefer this over `aria-label` whenever you have label text.
+
+<ComponentDemo>
+  <div style="width: 280px">
+    <MultiSelect
+      v-model="stationery"
+      label="Supplies"
+      hide-label
+      placeholder="Add supplies…"
+      :options="[
+        { value: 'pen', label: 'Pen' },
+        { value: 'pencil', label: 'Pencil' },
+        { value: 'marker', label: 'Marker' },
+        { value: 'eraser', label: 'Eraser' },
+      ]"
+    />
+  </div>
+
+<template #code>
+
+```vue
+<MultiSelect
+  v-model="supplies"
+  label="Supplies"
+  hide-label
+  placeholder="Add supplies…"
+  :options="[
+    { value: 'pen', label: 'Pen' },
+    { value: 'pencil', label: 'Pencil' },
+    { value: 'marker', label: 'Marker' },
+    { value: 'eraser', label: 'Eraser' },
+  ]"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+## Accessibility
+
+MultiSelect is built on reka-ui's Combobox, which implements the
+[ARIA combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/):
+
+- The text field has `role="combobox"` with `aria-expanded`, `aria-controls`,
+  `aria-autocomplete="list"`, and `aria-activedescendant` tracking the
+  highlighted option as you arrow through the list.
+- The popup is a `role="listbox"` with `aria-multiselectable="true"`; each option
+  is a `role="option"` and reflects its state via `aria-selected`.
+- Keyboard support is handled for you: type to filter, ↑/↓ to move, Enter to
+  toggle the highlighted option, Escape to close, and Backspace in an empty input
+  removes the last chip.
+- Pass `label` so the field is named by a real `<label>` (associated via
+  `aria-labelledby`); use `hide-label` to keep it for screen readers while hiding
+  it visually, or `aria-label` when there's no visible label text.
+- Each chip's remove button has an `aria-label` (e.g. "Remove California").
+
+## Model
+
+| Name | Type |
+|------|------|
+| `v-model` | `string[]` |
+
+## Props
+
+| Prop | Type | Required | Default |
+|------|------|----------|---------|
+| `label` | `string` | No | — |
+| `hideLabel` | `boolean` | No | — |
+| `ariaLabel` | `string` | No | — |
+| `options` | `MultiSelectOption[]` | Yes | — |
+| `placeholder` | `string` | No | — |
+| `hint` | `string` | No | — |
+
+
+### MultiSelectOption
+
+```ts
+interface MultiSelectOption {
+  value: string;
+  label: string;
+}
+```