@cfasim-ui/docs 0.5.0 → 0.6.0

package/charts/ChartMenu/ChartMenu.vue

@@ -19,18 +19,48 @@ const props = withDefaults(
     items: ChartMenuItem[];
     /** Force the dropdown style even when only one item is provided. */
     forceDropdown?: boolean;
+    /**
+     * When the chart is expanded, the menu trigger is replaced by a
+     * persistent close (✕) button that emits `close`.
+     */
+    isFullscreen?: boolean;
   }>(),
-  { forceDropdown: false },
+  { forceDropdown: false, isFullscreen: false },
 );
 
+const emit = defineEmits<{ (e: "close"): void }>();
+
 const useDropdown = () => props.forceDropdown || props.items.length > 1;
 </script>
 
 <template>
-  <div class="chart-menu-trigger-area">
+  <div
+    class="chart-menu-trigger-area"
+    :class="{ 'chart-menu-trigger-area--expanded': isFullscreen }"
+  >
+    <!-- Expanded: a close button replaces the menu trigger -->
+    <button
+      v-if="isFullscreen"
+      class="chart-menu-button chart-close-button"
+      aria-label="Collapse"
+      @click="emit('close')"
+    >
+      <svg
+        width="16"
+        height="16"
+        viewBox="0 0 16 16"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.75"
+        stroke-linecap="round"
+        aria-hidden="true"
+      >
+        <path d="M4 4l8 8M12 4l-8 8" />
+      </svg>
+    </button>
     <!-- Single item: plain button -->
     <button
-      v-if="!useDropdown()"
+      v-else-if="!useDropdown()"
       class="chart-menu-button chart-menu-single"
       :aria-label="items[0].label"
       @click="items[0].action"
@@ -88,11 +118,19 @@ const useDropdown = () => props.forceDropdown || props.items.length > 1;
 <style scoped>
 .chart-menu-trigger-area {
   position: absolute;
-  top: 0;
-  right: 0;
+  top: 0.5em;
+  right: 0.5em;
   z-index: 1;
 }
 
+/* In fullscreen the button anchors to the viewport corner (the wrapper's
+   content padding doesn't move an absolutely-positioned child), so inset it
+   further for modal-style breathing room. */
+.chart-menu-trigger-area--expanded {
+  top: 1.25em;
+  right: 1.25em;
+}
+
 .chart-menu-button {
   display: flex;
   align-items: center;
@@ -112,6 +150,11 @@ const useDropdown = () => props.forceDropdown || props.items.length > 1;
   opacity: 1;
 }
 
+/* The close button is always visible while the chart is expanded. */
+.chart-close-button {
+  opacity: 1;
+}
+
 .chart-menu-button:hover {
   background: var(--color-bg-1, rgba(0, 0, 0, 0.05));
   color: var(--color-text);
@@ -119,6 +162,33 @@ const useDropdown = () => props.forceDropdown || props.items.length > 1;
 </style>
 
 <style>
+/* Reveal the menu button when the user hovers/focuses anywhere in the
+   chart. These reference the parent wrapper classes, so they can't be
+   scoped to ChartMenu. (In fullscreen the menu button is swapped for the
+   always-visible close button, so no rule is needed there.) */
+.line-chart-wrapper:hover .chart-menu-button,
+.bar-chart-wrapper:hover .chart-menu-button,
+.choropleth-wrapper:hover .chart-menu-button,
+.line-chart-wrapper:focus-within .chart-menu-button,
+.bar-chart-wrapper:focus-within .chart-menu-button,
+.choropleth-wrapper:focus-within .chart-menu-button {
+  opacity: 1;
+}
+
+/* Visually-hidden live region used by each chart wrapper to announce
+   expansion. Lives here so it ships once with the shared menu. */
+.chart-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
 .chart-menu-content {
   z-index: 100;
   background: var(--color-bg-0);

package/charts/ChoroplethMap/ChoroplethMap.md

@@ -365,6 +365,10 @@ the focused feature toggles back off. If a tooltip is configured, focusing
 shows that feature's tooltip. Users can pan/zoom freely around the focused
 area; the built-in **Reset** button clears focus and snaps back.
 
+Selection works on touch too: a single-finger **tap** on a feature emits
+`stateClick` and toggles focus, while drags (pan) and pinches (zoom) are left
+to the map. Hover tooltips stay off on touch for performance.
+
 Counties are tiny without a zoom — focus is a natural fit for drill-down.
 
 <ComponentDemo>
@@ -714,6 +718,7 @@ set `tooltip-trigger`.
 | `tooltipClamp` | `"none" \| "chart" \| "window"` | No | `"chart"` |
 | `focus` | `FocusValue` | No | — |
 | `focusZoomLevel` | `number` | No | `4` |
+| `fullscreenTarget` | `string \| HTMLElement` | No | — |
 
 
 ### StateData

package/charts/ChoroplethMap/ChoroplethMap.vue

@@ -174,6 +174,15 @@ const props = withDefaults(
     focus?: FocusValue;
     /** Scale factor applied when `focus` is set. Default: 4 */
     focusZoomLevel?: number;
+    /**
+     * Where to teleport the map while expanded (the Expand menu item). A
+     * CSS selector or element; defaults to `body`. Moving it to the
+     * document root keeps `position: fixed` resolving against the viewport
+     * instead of being trapped by an ancestor's `transform`/`filter`/
+     * `contain`/`perspective` or stacking context. Set this when your app
+     * doesn't mount at the document root.
+     */
+    fullscreenTarget?: string | HTMLElement;
   }>(),
   {
     geoType: "states",
@@ -189,6 +198,10 @@ const props = withDefaults(
   },
 );
 
+// The template root is a <Teleport>, so fallthrough attrs (class, style,
+// data-*, id…) can't auto-inherit — forward them onto the wrapper manually.
+defineOptions({ inheritAttrs: false });
+
 const emit = defineEmits<{
   (
     e: "stateClick",
@@ -308,10 +321,33 @@ let pendingMoveX = 0;
 let pendingMoveY = 0;
 let pendingMoveFrame = 0;
 
+// Touch tap-to-select. Touch devices get no synthesized-click guarantee
+// (iOS treats the first tap on a hover target as a hover, and the d3-zoom
+// touch listeners can swallow the synthetic click), so we resolve taps from
+// the raw touch events ourselves. A gesture counts as a tap when a single
+// finger lifts close to where it landed, soon after — anything longer or
+// draggier is a pan/long-press and is left to d3-zoom.
+const TAP_SLOP = 10; // px of movement allowed between touchstart and touchend
+const TAP_MAX_MS = 600; // longer presses aren't taps
+let tapStart: {
+  x: number;
+  y: number;
+  time: number;
+  featId: string | null;
+} | null = null;
+
 function setupInteraction() {
-  if (isTouchDevice) return;
   const g = mapGroupRef.value;
   if (!g) return;
+  // Tap-to-select is wired on every device. `touchend` is non-passive so a
+  // confirmed tap can preventDefault and suppress the compatibility
+  // click/hover the browser would otherwise synthesize (the double-fire and
+  // iOS first-tap-hover sources).
+  g.addEventListener("touchstart", onTouchStart, { passive: true });
+  g.addEventListener("touchend", onTouchEnd);
+  g.addEventListener("touchcancel", onTouchCancel, { passive: true });
+  // Hover + tooltip stay off on touch (stroke-width churn degrades zoom/pan).
+  if (isTouchDevice) return;
   g.addEventListener("click", onDelegatedEvent);
   g.addEventListener("mouseover", onDelegatedEvent);
   g.addEventListener("mousemove", onDelegatedMouseMove);
@@ -321,6 +357,9 @@ function setupInteraction() {
 function teardownInteraction() {
   const g = mapGroupRef.value;
   if (!g) return;
+  g.removeEventListener("touchstart", onTouchStart);
+  g.removeEventListener("touchend", onTouchEnd);
+  g.removeEventListener("touchcancel", onTouchCancel);
   g.removeEventListener("click", onDelegatedEvent);
   g.removeEventListener("mouseover", onDelegatedEvent);
   g.removeEventListener("mousemove", onDelegatedMouseMove);
@@ -1146,6 +1185,18 @@ function eventToFeatureId(target: EventTarget | null): string | null {
   return el ? ((el as HTMLElement).dataset.featId ?? null) : null;
 }
 
+// Emits stateClick plus the baked-in click-to-focus toggle so
+// `v-model:focus="ref"` Just Works: selecting the currently focused feature
+// clears focus (emits null); selecting any other feature emits its id. With
+// a `focus` array, any selection of a member clears everything — parents
+// wanting fine-grained multi-select handle merging via `@update:focus`.
+// Shared by the mouse-click and touch-tap paths.
+function emitSelection(data: TooltipPayload) {
+  emit("stateClick", { id: data.id, name: data.name, value: data.value });
+  const wasFocused = focusedBaseIds(normalizedFocus.value).has(data.id);
+  emit("update:focus", wasFocused ? null : data.id);
+}
+
 function onDelegatedEvent(event: Event) {
   if (isZooming) return;
   const me = event as MouseEvent;
@@ -1155,14 +1206,7 @@ function onDelegatedEvent(event: Event) {
   if (!data) return;
   const payload = { id: data.id, name: data.name, value: data.value };
   if (event.type === "click") {
-    emit("stateClick", payload);
-    // Click-to-focus toggle, baked in so `v-model:focus="ref"` Just Works:
-    // clicking the currently focused feature clears focus (emits null);
-    // clicking any other feature emits its id. With a `focus` array, any
-    // click on a member clears everything — parents wanting fine-grained
-    // multi-select handle merging themselves via `@update:focus`.
-    const wasFocused = focusedBaseIds(normalizedFocus.value).has(data.id);
-    emit("update:focus", wasFocused ? null : data.id);
+    emitSelection(data);
   } else if (event.type === "mouseover") {
     setHover(pathsByFeatureId.get(featId)!);
     if (hasInteractiveTooltip.value)
@@ -1182,6 +1226,44 @@ function onDelegatedMouseOut(event: MouseEvent) {
   clearHover();
 }
 
+function onTouchStart(event: TouchEvent) {
+  // Single-finger only — a second touch is a pinch-zoom, not a selection.
+  if (event.touches.length !== 1) {
+    tapStart = null;
+    return;
+  }
+  const t = event.touches[0]!;
+  tapStart = {
+    x: t.clientX,
+    y: t.clientY,
+    time: event.timeStamp,
+    featId: eventToFeatureId(event.target),
+  };
+}
+
+function onTouchEnd(event: TouchEvent) {
+  const start = tapStart;
+  tapStart = null;
+  // No feature under the initial touch, or a second finger joined in.
+  if (!start || !start.featId || event.touches.length > 0) return;
+  const t = event.changedTouches[0];
+  if (!t) return;
+  // Moved too far (a pan) or held too long (a long-press) → not a tap.
+  if (Math.abs(t.clientX - start.x) > TAP_SLOP) return;
+  if (Math.abs(t.clientY - start.y) > TAP_SLOP) return;
+  if (event.timeStamp - start.time > TAP_MAX_MS) return;
+  const data = tooltipDataById.get(start.featId);
+  if (!data) return;
+  // Suppress the synthetic click/hover the browser would replay from this
+  // tap, so selection fires exactly once and never via iOS's hover-first tap.
+  event.preventDefault();
+  emitSelection(data);
+}
+
+function onTouchCancel() {
+  tapStart = null;
+}
+
 // ─── Imperative SVG path management ──────────────────────────────────────
 //
 // 3,000+ counties are too many to round-trip through Vue's render scheduler
@@ -1372,7 +1454,9 @@ const gradientCss = computed(() => {
   return `linear-gradient(to right, ${stops})`;
 });
 
-const fullscreen = useChartFullscreen();
+const fullscreen = useChartFullscreen({
+  target: () => props.fullscreenTarget,
+});
 
 const menuItems = computed<ChartMenuItem[]>(() => {
   const fname = menuFilename();
@@ -1439,70 +1523,81 @@ watch(
 </script>
 
 <template>
-  <div
-    ref="containerRef"
-    :class="[
-      'choropleth-wrapper',
-      { pannable: pan, 'is-fullscreen': fullscreen.isFullscreen.value },
-    ]"
+  <Teleport
+    :to="fullscreen.teleportTarget.value"
+    :disabled="!fullscreen.isFullscreen.value"
   >
-    <ChartMenu v-if="menu" :items="menuItems" />
-    <div class="chart-sr-only" aria-live="polite">
-      {{ fullscreen.isFullscreen.value ? "Map expanded to fill window" : "" }}
-    </div>
-    <!--
+    <div
+      ref="containerRef"
+      v-bind="$attrs"
+      :class="[
+        'choropleth-wrapper',
+        { pannable: pan, 'is-fullscreen': fullscreen.isFullscreen.value },
+      ]"
+      :style="fullscreen.fullscreenStyle.value"
+    >
+      <ChartMenu
+        v-if="menu"
+        :items="menuItems"
+        :is-fullscreen="fullscreen.isFullscreen.value"
+        @close="fullscreen.exit"
+      />
+      <div class="chart-sr-only" aria-live="polite">
+        {{ fullscreen.isFullscreen.value ? "Map expanded to fill window" : "" }}
+      </div>
+      <!--
       Title + legend live as an HTML overlay on top of the SVG so they keep
       their intrinsic px sizes regardless of how the browser scales the
       viewBox to fit the container.
     -->
-    <div v-if="title || showLegend" class="choropleth-header">
-      <div v-if="title" class="choropleth-title" :style="titleInlineStyle">
-        {{ title }}
-      </div>
-      <div
-        v-if="showLegend"
-        class="choropleth-legend"
-        :style="legendInlineStyle"
-      >
-        <span v-if="legendTitle" class="choropleth-legend-title">
-          {{ legendTitle }}
-        </span>
-        <template v-if="isCategorical || isThreshold">
-          <span
-            v-for="item in discreteLegendItems"
-            :key="item.key"
-            class="choropleth-legend-item"
-          >
-            <span
-              class="choropleth-legend-swatch"
-              :style="{ background: item.color }"
-            />
-            {{ item.label }}
+      <div v-if="title || showLegend" class="choropleth-header">
+        <div v-if="title" class="choropleth-title" :style="titleInlineStyle">
+          {{ title }}
+        </div>
+        <div
+          v-if="showLegend"
+          class="choropleth-legend"
+          :style="legendInlineStyle"
+        >
+          <span v-if="legendTitle" class="choropleth-legend-title">
+            {{ legendTitle }}
           </span>
-        </template>
-        <div v-else class="choropleth-legend-continuous">
-          <div
-            class="choropleth-legend-gradient"
-            :style="{ background: gradientCss }"
-          />
-          <div class="choropleth-legend-ticks">
+          <template v-if="isCategorical || isThreshold">
             <span
-              v-for="tick in continuousTicks"
-              :key="tick.value"
-              :style="{ left: tick.pct + '%' }"
+              v-for="item in discreteLegendItems"
+              :key="item.key"
+              class="choropleth-legend-item"
             >
-              {{ tick.value }}
+              <span
+                class="choropleth-legend-swatch"
+                :style="{ background: item.color }"
+              />
+              {{ item.label }}
             </span>
+          </template>
+          <div v-else class="choropleth-legend-continuous">
+            <div
+              class="choropleth-legend-gradient"
+              :style="{ background: gradientCss }"
+            />
+            <div class="choropleth-legend-ticks">
+              <span
+                v-for="tick in continuousTicks"
+                :key="tick.value"
+                :style="{ left: tick.pct + '%' }"
+              >
+                {{ tick.value }}
+              </span>
+            </div>
           </div>
         </div>
       </div>
-    </div>
-    <svg
-      ref="svgRef"
-      :viewBox="`0 0 ${width} ${height}`"
-      preserveAspectRatio="xMidYMid meet"
-    >
-      <!--
+      <svg
+        ref="svgRef"
+        :viewBox="`0 0 ${width} ${height}`"
+        preserveAspectRatio="xMidYMid meet"
+      >
+        <!--
         Path elements are created imperatively in `rebuildPaths()`; Vue never
         diffs the per-feature subtree so reactive state changes don't walk
         thousands of vnodes. `mapGroupRef` carries the zoom transform;
@@ -1511,32 +1606,33 @@ watch(
         focus-overlay layer (separate group so hover-raised base paths
         can't cover an overlay).
       -->
-      <g ref="mapGroupRef">
-        <g ref="baseGroupRef" />
-        <g ref="overlayGroupRef" />
-      </g>
-    </svg>
-    <button
-      v-if="isZoomed"
-      type="button"
-      class="choropleth-reset"
-      aria-label="Reset zoom"
-      @click="resetZoom"
-    >
-      Reset
-    </button>
-    <ChoroplethTooltip v-if="hasInteractiveTooltip" ref="tooltipChildRef">
-      <template #default="raw">
-        <slot name="tooltip" v-bind="narrowSlotProps(raw)">
-          <span v-if="tooltipFormat" v-html="tooltipFormat(raw)" />
-          <template v-else-if="raw.value == null">{{ raw.name }}</template>
-          <template v-else>
-            {{ raw.name }}: {{ formatTooltipValue(raw.value) }}
-          </template>
-        </slot>
-      </template>
-    </ChoroplethTooltip>
-  </div>
+        <g ref="mapGroupRef">
+          <g ref="baseGroupRef" />
+          <g ref="overlayGroupRef" />
+        </g>
+      </svg>
+      <button
+        v-if="isZoomed"
+        type="button"
+        class="choropleth-reset"
+        aria-label="Reset zoom"
+        @click="resetZoom"
+      >
+        Reset
+      </button>
+      <ChoroplethTooltip v-if="hasInteractiveTooltip" ref="tooltipChildRef">
+        <template #default="raw">
+          <slot name="tooltip" v-bind="narrowSlotProps(raw)">
+            <span v-if="tooltipFormat" v-html="tooltipFormat(raw)" />
+            <template v-else-if="raw.value == null">{{ raw.name }}</template>
+            <template v-else>
+              {{ raw.name }}: {{ formatTooltipValue(raw.value) }}
+            </template>
+          </slot>
+        </template>
+      </ChoroplethTooltip>
+    </div>
+  </Teleport>
 </template>
 
 <style scoped>
@@ -1566,6 +1662,15 @@ watch(
   cursor: grab;
 }
 
+/* While expanded the wrapper is a flex column (inline style); the SVG keeps
+   its prop-driven size otherwise, so stretch it to fill the expanded box. */
+.choropleth-wrapper.is-fullscreen svg {
+  flex: 1 1 auto;
+  min-height: 0;
+  height: 100%;
+  width: 100%;
+}
+
 .choropleth-wrapper.pannable svg:active {
   cursor: grabbing;
 }

package/charts/LineChart/LineChart.md

@@ -263,6 +263,8 @@ Set `legend` on a series to add an entry to the inline legend strip above the pl
 
 Hover over the chart to see a tooltip with values at each data point. Set `tooltip-trigger="hover"` to enable the built-in tooltip with crosshair and highlight dots. Use the `#tooltip` slot for custom content. Pass `tooltip-value-format` to control how numeric values render (e.g. percentages, currency); it falls back to `y-tick-format` when omitted.
 
+On touch devices, drag **horizontally** across the chart to scrub the tooltip between points; a **vertical** swipe scrolls the page instead of getting captured by the chart.
+
 <ComponentDemo>
   <LineChart
     :series="[
@@ -415,6 +417,11 @@ Set `outline: true` on a series to draw a page-colored stroke behind the
 line. This is useful when lines overlap, cross dense areas, or sit on a
 busy background — the outline keeps each series visually distinct.
 
+Override the outline's color with `outlineColor` (any CSS color; defaults
+to the page background `var(--color-bg-0, #fff)`) and its thickness with
+`outlineWidth` (extra width added to the line's `strokeWidth`, split evenly
+per side; defaults to `4`).
+
 <ComponentDemo>
   <LineChart
     :series="[
@@ -928,10 +935,17 @@ positioned from the anchor as usual via `offset`.
 
 ### Chart menu
 
-The chart menu (top-right) leads with Expand / Collapse and then Save as SVG,
-Save as PNG, and Download CSV. Expand grows the chart to fill the browser
-window so the plot has more room; press <kbd>Esc</kbd> or pick "Collapse" to
-return to the inline size. Set `menu="false"` to hide the trigger entirely.
+The chart menu (top-right) leads with Fullscreen and then Save as SVG,
+Save as PNG, and Download CSV. Fullscreen grows the chart to fill the browser
+window so the plot has more room; while expanded the menu trigger is replaced
+by a close (✕) button — click it or press <kbd>Esc</kbd> to return to the
+inline size. Set `menu="false"` to hide the trigger entirely.
+
+While expanded the chart is teleported to `<body>` so it reliably covers the
+viewport even when an ancestor uses `transform`, `filter`, `contain`, or
+establishes a stacking context. If your app doesn't mount at the document root
+(e.g. inside a shadow root or a dedicated overlay container), point
+`fullscreenTarget` at a CSS selector or element to teleport there instead.
 
 ### Custom CSV download
 
@@ -1008,6 +1022,7 @@ until the user clicks Download:
 | `filename` | `string` | No | — |
 | `downloadLink` | `boolean \| string` | No | — |
 | `downloadButton` | `boolean \| string` | No | — |
+| `fullscreenTarget` | `string \| HTMLElement` | No | — |
 | `annotations` | `readonly ChartAnnotation[]` | No | — |
 | `chartPadding` | `ChartPadding` | No | — |
 | `y` | `LineChartData` | No | — |
@@ -1070,6 +1085,8 @@ interface Series {
   opacity?: number;
   line?: boolean;
   outline?: boolean; // page-colored stroke drawn behind the line
+  outlineColor?: string; // outline stroke color (default: var(--color-bg-0, #fff))
+  outlineWidth?: number; // extra width added to strokeWidth (default: 4)
   dots?: boolean;
   dotRadius?: number;
   dotFill?: string;