@cfasim-ui/docs 0.4.10 → 0.4.12

package/charts/_shared/useChartFoundation.ts

@@ -6,6 +6,7 @@ import { useChartPadding, type ChartPadding } from "./useChartPadding.js";
 import { useChartTooltip } from "./useChartTooltip.js";
 import type { TooltipClamp } from "../tooltip-position.js";
 import { useChartMenu } from "./useChartMenu.js";
+import type { TitleStyle } from "./chartProps.js";
 
 const DEFAULT_WIDTH_FALLBACK = 400;
 const DEFAULT_HEIGHT = 200;
@@ -15,6 +16,7 @@ export interface ChartFoundationOptions {
   width: () => number | undefined;
   height: () => number | undefined;
   title: () => string | undefined;
+  titleStyle: () => TitleStyle | undefined;
   xLabel: () => string | undefined;
   yLabel: () => string | undefined;
   debounce: () => number | undefined;
@@ -25,11 +27,22 @@ export interface ChartFoundationOptions {
   downloadLink: () => boolean | string | undefined;
   chartPadding: () => ChartPadding | undefined;
   // Chart-specific hooks that the composable can't infer.
-  hasInlineLegend: () => boolean;
+  /**
+   * Labels for the inline legend in render order. Empty array = no
+   * legend strip. Drives wrapping into multiple rows and the resulting
+   * top-padding reservation.
+   */
+  inlineLegendLabels: () => readonly string[];
   hasTooltipSlot: () => boolean;
   getCsv: () => string;
   pointerToIndex: (clientX: number, clientY: number) => number | null;
   onHover: (payload: { index: number } | null) => void;
+  /**
+   * 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
+   * height matched to the container when fullscreen.
+   */
+  extraBelowHeight?: () => number;
 }
 
 /**
@@ -39,25 +52,52 @@ export interface ChartFoundationOptions {
  * consumes.
  */
 export function useChartFoundation(opts: ChartFoundationOptions) {
-  const { containerRef, measuredWidth } = useChartSize({
+  const { containerRef, measuredWidth, measuredHeight } = useChartSize({
     debounce: opts.debounce,
   });
 
-  const width = computed(
-    () => opts.width() ?? (measuredWidth.value || DEFAULT_WIDTH_FALLBACK),
-  );
-  const height = computed(() => opts.height() ?? DEFAULT_HEIGHT);
+  const {
+    svgRef,
+    items: menuItems,
+    downloadLinkText,
+    csvHref,
+    resolvedFilename: menuFilename,
+    isFullscreen,
+  } = useChartMenu({
+    filename: opts.filename,
+    legacyMenuLabel: opts.menu,
+    getCsv: opts.getCsv,
+    downloadLink: opts.downloadLink,
+    fullscreen: true,
+  });
+
+  const width = computed(() => {
+    if (isFullscreen.value && measuredWidth.value > 0) {
+      return measuredWidth.value;
+    }
+    return opts.width() ?? (measuredWidth.value || DEFAULT_WIDTH_FALLBACK);
+  });
 
-  const { padding, legendY, innerW, innerH, bounds } = useChartPadding({
-    title: opts.title,
-    xLabel: opts.xLabel,
-    yLabel: opts.yLabel,
-    hasInlineLegend: opts.hasInlineLegend,
-    width: () => width.value,
-    height: () => height.value,
-    extraPadding: opts.chartPadding,
+  const height = computed(() => {
+    if (isFullscreen.value && measuredHeight.value > 0) {
+      const extra = opts.extraBelowHeight?.() ?? 0;
+      return measuredHeight.value - extra;
+    }
+    return opts.height() ?? DEFAULT_HEIGHT;
   });
 
+  const { padding, legendY, inlineLegendLayout, innerW, innerH, bounds } =
+    useChartPadding({
+      title: opts.title,
+      titleStyle: opts.titleStyle,
+      xLabel: opts.xLabel,
+      yLabel: opts.yLabel,
+      inlineLegendLabels: opts.inlineLegendLabels,
+      width: () => width.value,
+      height: () => height.value,
+      extraPadding: opts.chartPadding,
+    });
+
   const {
     hoverIndex,
     tooltipRef,
@@ -72,19 +112,6 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
     onHover: opts.onHover,
   });
 
-  const {
-    svgRef,
-    items: menuItems,
-    downloadLinkText,
-    csvHref,
-    resolvedFilename: menuFilename,
-  } = useChartMenu({
-    filename: opts.filename,
-    legacyMenuLabel: opts.menu,
-    getCsv: opts.getCsv,
-    downloadLink: opts.downloadLink,
-  });
-
   return {
     containerRef,
     svgRef,
@@ -92,6 +119,7 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
     height,
     padding,
     legendY,
+    inlineLegendLayout,
     innerW,
     innerH,
     bounds,
@@ -103,6 +131,8 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
     downloadLinkText,
     csvHref,
     menuFilename,
+    isFullscreen,
+    measuredHeight,
   };
 }
 

package/charts/_shared/useChartFullscreen.ts

@@ -0,0 +1,104 @@
+import { computed, onMounted, onUnmounted, ref } from "vue";
+import type { ChartMenuItem } from "../ChartMenu/ChartMenu.vue";
+
+/**
+ * Module-level refcount so multiple expanded charts on the same page
+ * share one body-scroll lock — the last one to collapse restores the
+ * original `overflow` value.
+ */
+let bodyLockCount = 0;
+let savedBodyOverflow = "";
+
+function lockBodyScroll() {
+  if (typeof document === "undefined") return;
+  if (bodyLockCount === 0) {
+    savedBodyOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+  }
+  bodyLockCount++;
+}
+
+function unlockBodyScroll() {
+  if (typeof document === "undefined") return;
+  if (bodyLockCount === 0) return;
+  bodyLockCount--;
+  if (bodyLockCount === 0) {
+    document.body.style.overflow = savedBodyOverflow;
+  }
+}
+
+/**
+ * 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.
+ */
+export function useChartFullscreen() {
+  const isFullscreen = ref(false);
+  let locked = false;
+
+  function setExpanded(value: boolean) {
+    if (value === isFullscreen.value) return;
+    isFullscreen.value = value;
+    if (value && !locked) {
+      lockBodyScroll();
+      locked = true;
+    } else if (!value && locked) {
+      unlockBodyScroll();
+      locked = false;
+    }
+  }
+
+  function onKey(e: KeyboardEvent) {
+    if (e.key !== "Escape" || !isFullscreen.value) return;
+    // Skip when Esc is closing a menu/dialog layered on top of us so we
+    // don't collapse the chart at the same time. Reka's dropdown menu
+    // uses a document-level Esc listener and doesn't call preventDefault,
+    // so checking the event target is the most reliable signal.
+    const t = e.target;
+    if (t instanceof Element && t.closest('[role="menu"], [role="dialog"]')) {
+      return;
+    }
+    setExpanded(false);
+  }
+
+  function enter() {
+    setExpanded(true);
+  }
+  function exit() {
+    setExpanded(false);
+  }
+  function toggle() {
+    setExpanded(!isFullscreen.value);
+  }
+
+  onMounted(() => {
+    if (typeof document === "undefined") return;
+    document.addEventListener("keydown", onKey);
+  });
+  onUnmounted(() => {
+    if (typeof document === "undefined") return;
+    document.removeEventListener("keydown", onKey);
+    // Component torn down while expanded — release the lock so the body
+    // doesn't stay frozen.
+    if (locked) {
+      unlockBodyScroll();
+      locked = false;
+    }
+  });
+
+  /**
+   * Returns a reactive ChartMenuItem ref that flips between Expand and
+   * Collapse — shared by useChartMenu and any chart (e.g. ChoroplethMap)
+   * that builds its menu list directly.
+   */
+  const menuItem = computed<ChartMenuItem>(() => ({
+    label: isFullscreen.value ? "Collapse" : "Expand",
+    action: toggle,
+    ariaPressed: isFullscreen.value,
+  }));
+
+  return { isFullscreen, toggle, enter, exit, menuItem };
+}

package/charts/_shared/useChartMenu.ts

@@ -1,6 +1,7 @@
 import { computed, ref, type Ref } from "vue";
 import type { ChartMenuItem } from "../ChartMenu/ChartMenu.vue";
 import { saveSvg, savePng, downloadCsv } from "../ChartMenu/download.js";
+import { useChartFullscreen } from "./useChartFullscreen.js";
 
 export interface ChartMenuOptions {
   filename: () => string | undefined;
@@ -10,11 +11,18 @@ export interface ChartMenuOptions {
   getCsv: () => string;
   /** Whether a separate download link is rendered (and the CSV menu item should be hidden). */
   downloadLink: () => 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.
+   */
+  fullscreen?: boolean;
 }
 
 /**
- * Computes the standard chart menu items (SVG / PNG / CSV) plus the
- * CSV-download-link state shared by every chart.
+ * Computes the standard chart menu items (Expand / SVG / PNG / CSV) plus
+ * the CSV-download-link state shared by every chart.
  */
 export function useChartMenu(opts: ChartMenuOptions) {
   const svgRef = ref<SVGSVGElement | null>(null);
@@ -26,9 +34,15 @@ export function useChartMenu(opts: ChartMenuOptions) {
     return typeof menu === "string" ? menu : "chart";
   }
 
+  const fullscreen = opts.fullscreen ? useChartFullscreen() : null;
+
   const items = computed<ChartMenuItem[]>(() => {
     const fname = resolvedFilename();
-    const out: ChartMenuItem[] = [
+    const out: ChartMenuItem[] = [];
+    if (fullscreen) {
+      out.push(fullscreen.menuItem.value);
+    }
+    out.push(
       {
         label: "Save as SVG",
         action: () => {
@@ -41,7 +55,7 @@ export function useChartMenu(opts: ChartMenuOptions) {
           if (svgRef.value) savePng(svgRef.value, fname);
         },
       },
-    ];
+    );
     if (!opts.downloadLink()) {
       out.push({
         label: "Download CSV",
@@ -68,5 +82,6 @@ export function useChartMenu(opts: ChartMenuOptions) {
     downloadLinkText,
     csvHref,
     resolvedFilename,
+    isFullscreen: fullscreen?.isFullscreen ?? ref(false),
   };
 }

package/charts/_shared/useChartPadding.ts

@@ -1,7 +1,56 @@
 import { computed } from "vue";
+import type { LabelStyle, TitleStyle } from "./chartProps.js";
 
-/** Vertical space reserved at the top of the chart for inline legend swatches. */
-export const INLINE_LEGEND_HEIGHT = 20;
+/** Vertical space reserved per row of the inline legend strip. */
+export const INLINE_LEGEND_ROW_HEIGHT = 20;
+/** Default line height (px) for the chart title; overridable per chart. */
+export const TITLE_LINE_HEIGHT = 18;
+/** Default font size (px) for the chart title; overridable per chart. */
+export const TITLE_FONT_SIZE = 14;
+/** Default font weight for the chart title; overridable per chart. */
+export const TITLE_FONT_WEIGHT: number | string = 600;
+/** Default font size (px) for axis labels (`xLabel` / `yLabel`). */
+export const AXIS_LABEL_FONT_SIZE = 13;
+/** Default font size (px) for axis tick labels (the numbers on each axis). */
+export const TICK_LABEL_FONT_SIZE = 10;
+/** Default fill-opacity for tick labels when no custom color is set. */
+export const TICK_LABEL_OPACITY = 0.6;
+/** Default font size (px) for inline legend item labels. */
+export const LEGEND_FONT_SIZE = 11;
+/** Vertical space below the title's last baseline before the next element. */
+const TITLE_BOTTOM_GAP = 8;
+
+/**
+ * Resolve a `LabelStyle` against per-element defaults. Returns the
+ * fields the chart's `<text>` element needs. When `style.color` is set,
+ * the default fill-opacity is dropped so the exact color renders.
+ */
+export function resolveLabelStyle(
+  style: LabelStyle | undefined,
+  defaults: { fontSize: number; fillOpacity?: number },
+): {
+  fontSize: number;
+  fill: string;
+  fontWeight: number | string | undefined;
+  fillOpacity: number | undefined;
+} {
+  return {
+    fontSize: style?.fontSize ?? defaults.fontSize,
+    fill: style?.color ?? "currentColor",
+    fontWeight: style?.fontWeight,
+    fillOpacity: style?.color != null ? undefined : defaults.fillOpacity,
+  };
+}
+/**
+ * Estimated character width at font-size 11 used by inline-legend
+ * measurement. Matches the value used by LineChart's area-section labels
+ * so wrapping behaves consistently across the chart's text overlays.
+ */
+const LEGEND_CHAR_WIDTH = 7;
+/** X offset of legend text from the start of its row slot. */
+const LEGEND_TEXT_INDENT = 18;
+/** Horizontal gap between adjacent legend items on the same row. */
+const LEGEND_ITEM_GAP = 16;
 
 /**
  * Extra space added around the chart's standard layout. A number applies
@@ -20,15 +69,29 @@ export type ChartPadding =
 
 export interface ChartPaddingOptions {
   title: () => string | undefined;
+  titleStyle?: () => TitleStyle | undefined;
   xLabel: () => string | undefined;
   yLabel: () => string | undefined;
-  hasInlineLegend: () => boolean;
+  /**
+   * Labels for the inline legend items, in render order. Empty array
+   * (or omitted) means no legend strip. Drives both row-count for
+   * reserving top padding and per-item wrap positions.
+   */
+  inlineLegendLabels: () => readonly string[];
   width: () => number;
   height: () => number;
   /** Extra pixels added on top of the standard axis spacing. */
   extraPadding?: () => ChartPadding | undefined;
 }
 
+/** Position of a single legend item within the legend strip. */
+export interface PositionedLegendItem {
+  /** X offset relative to `padding.left`. */
+  x: number;
+  /** Row index, 0-based. */
+  row: number;
+}
+
 function resolvePadding(p: ChartPadding | undefined) {
   if (p == null) return { top: 0, right: 0, bottom: 0, left: 0 };
   if (typeof p === "number") return { top: p, right: p, bottom: p, left: p };
@@ -40,6 +103,14 @@ function resolvePadding(p: ChartPadding | undefined) {
   };
 }
 
+/**
+ * Estimated rendered width (in px) of a single legend item — indicator,
+ * text, and surrounding spacing. Used to flow items into rows.
+ */
+function estimateLegendItemWidth(label: string): number {
+  return LEGEND_TEXT_INDENT + label.length * LEGEND_CHAR_WIDTH;
+}
+
 /**
  * Computes the standard chart padding (top/right/bottom/left) and the
  * derived inner plotting region (innerW, innerH). Shared by LineChart
@@ -47,30 +118,86 @@ function resolvePadding(p: ChartPadding | undefined) {
  * consistent. `extraPadding` adds extra space outside the plot — useful
  * for annotations that need to extend past the data area without
  * clipping.
+ *
+ * The inline legend wraps to multiple rows when items don't fit in the
+ * available width; `padding.top` grows by `INLINE_LEGEND_ROW_HEIGHT` per
+ * row so the plot stays clear of the legend strip.
  */
 export function useChartPadding(opts: ChartPaddingOptions) {
-  const padding = computed(() => {
+  // Horizontal padding is computed first because `innerW` depends only
+  // on left/right (not on legend row count). Splitting padding this way
+  // keeps the legend layout — which depends on `innerW` — out of the
+  // reactivity cycle for left/right.
+  const horizontalPadding = computed(() => {
     const extra = resolvePadding(opts.extraPadding?.());
     return {
-      top:
-        (opts.title() ? 26 : 10) +
-        (opts.hasInlineLegend() ? INLINE_LEGEND_HEIGHT : 0) +
-        extra.top,
+      left: (opts.yLabel() ? 56 : 50) + extra.left,
       right: 10 + extra.right,
+    };
+  });
+
+  const innerW = computed(
+    () =>
+      opts.width() -
+      horizontalPadding.value.left -
+      horizontalPadding.value.right,
+  );
+
+  const inlineLegendLayout = computed<{
+    positions: PositionedLegendItem[];
+    rowCount: number;
+  }>(() => {
+    const labels = opts.inlineLegendLabels();
+    if (labels.length === 0) return { positions: [], rowCount: 0 };
+    const available = Math.max(0, innerW.value);
+    const positions: PositionedLegendItem[] = [];
+    let row = 0;
+    let x = 0;
+    for (const label of labels) {
+      const w = estimateLegendItemWidth(label);
+      // Wrap to a new row when the item won't fit, except when we're
+      // already at row-start (`x === 0`): a single oversized label gets
+      // its own row instead of triggering an infinite-wrap loop.
+      if (x > 0 && x + w > available) {
+        row++;
+        x = 0;
+      }
+      positions.push({ x, row });
+      x += w + LEGEND_ITEM_GAP;
+    }
+    return { positions, rowCount: row + 1 };
+  });
+
+  // Title height in px. `\n` in the title creates additional lines, each
+  // adding `titleStyle.lineHeight` (default 18). When there is no title,
+  // reserve a small top margin so the plot doesn't hug the top edge.
+  const titleHeight = computed(() => {
+    const t = opts.title();
+    if (!t) return 10;
+    const lineHeight = opts.titleStyle?.()?.lineHeight ?? TITLE_LINE_HEIGHT;
+    const lineCount = t.split("\n").length;
+    return lineCount * lineHeight + TITLE_BOTTOM_GAP;
+  });
+
+  const padding = computed(() => {
+    const extra = resolvePadding(opts.extraPadding?.());
+    const rowCount = inlineLegendLayout.value.rowCount;
+    return {
+      top: titleHeight.value + rowCount * INLINE_LEGEND_ROW_HEIGHT + extra.top,
       bottom: (opts.xLabel() ? 38 : 30) + extra.bottom,
-      left: (opts.yLabel() ? 56 : 50) + extra.left,
+      left: horizontalPadding.value.left,
+      right: horizontalPadding.value.right,
     };
   });
-  // Y-center of the inline legend strip. Sits at the top of the padding
-  // band (just below any title), so any user-supplied `extraPadding.top`
-  // becomes empty room between the legend and the plot — useful for
-  // annotations that need to extend above the data area.
+
+  // Y-center of the first inline-legend row. Sits at the top of the
+  // padding band (just below any title), so any user-supplied
+  // `extraPadding.top` becomes empty room between the legend and the
+  // plot. Subsequent rows are offset by `INLINE_LEGEND_ROW_HEIGHT`.
   const legendY = computed(
-    () => (opts.title() ? 26 : 10) + INLINE_LEGEND_HEIGHT / 2,
-  );
-  const innerW = computed(
-    () => opts.width() - padding.value.left - padding.value.right,
+    () => titleHeight.value + INLINE_LEGEND_ROW_HEIGHT / 2,
   );
+
   const innerH = computed(
     () => opts.height() - padding.value.top - padding.value.bottom,
   );
@@ -88,7 +215,14 @@ export function useChartPadding(opts: ChartPaddingOptions) {
       height: innerH.value,
     };
   });
-  return { padding, legendY, innerW, innerH, bounds };
+  return {
+    padding,
+    legendY,
+    inlineLegendLayout,
+    innerW,
+    innerH,
+    bounds,
+  };
 }
 
 export type ChartBounds = {

package/charts/_shared/useChartSize.ts

@@ -15,23 +15,27 @@ export interface ChartSizeOptions {
 export function useChartSize(opts: ChartSizeOptions = {}) {
   const containerRef = ref<HTMLElement | null>(null);
   const measuredWidth = ref(0);
+  const measuredHeight = ref(0);
   let observer: ResizeObserver | null = null;
   let resizeTimeout: ReturnType<typeof setTimeout> | null = null;
 
   onMounted(() => {
     if (!containerRef.value) return;
     measuredWidth.value = containerRef.value.clientWidth;
+    measuredHeight.value = containerRef.value.clientHeight;
     observer = new ResizeObserver((entries) => {
       const entry = entries[0];
       if (!entry) return;
+      const apply = () => {
+        measuredWidth.value = entry.contentRect.width;
+        measuredHeight.value = entry.contentRect.height;
+      };
       const debounce = opts.debounce?.();
       if (debounce) {
         if (resizeTimeout) clearTimeout(resizeTimeout);
-        resizeTimeout = setTimeout(() => {
-          measuredWidth.value = entry.contentRect.width;
-        }, debounce);
+        resizeTimeout = setTimeout(apply, debounce);
       } else {
-        measuredWidth.value = entry.contentRect.width;
+        apply();
       }
     });
     observer.observe(containerRef.value);
@@ -45,5 +49,10 @@ export function useChartSize(opts: ChartSizeOptions = {}) {
   return {
     containerRef,
     measuredWidth,
-  } as { containerRef: Ref<HTMLElement | null>; measuredWidth: Ref<number> };
+    measuredHeight,
+  } as {
+    containerRef: Ref<HTMLElement | null>;
+    measuredWidth: Ref<number>;
+    measuredHeight: Ref<number>;
+  };
 }

package/charts/hsa-mapping.ts

@@ -0,0 +1 @@
+export { fipsToHsa, hsaNames } from "./ChoroplethMap/hsaMapping.js";

package/charts/index.ts

@@ -1,3 +1,5 @@
+import "./_shared/fullscreen.css";
+
 export {
   default as LineChart,
   type LineChartData,
@@ -21,7 +23,6 @@ export {
   type FocusValue,
   type FocusStyle,
 } from "./ChoroplethMap/ChoroplethMap.vue";
-export { fipsToHsa, hsaNames } from "./ChoroplethMap/hsaMapping.js";
 export { default as ChartTooltip } from "./ChartTooltip/ChartTooltip.vue";
 export {
   default as DataTable,

package/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.10",
+  "version": "0.4.12",
   "package": "@cfasim-ui/docs",
   "content": {
     "components": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/docs",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "LLM-friendly component and chart documentation for cfasim-ui",
   "license": "Apache-2.0",
   "repository": {