@cfasim-ui/charts 0.7.8 → 0.8.1

package/src/ChoroplethMap/mixedGeo.ts

@@ -0,0 +1,201 @@
+// Mixed-level geography for ChoroplethMap: render most of the map at the base
+// `geoType` while a few states render at a different level — a county map where
+// California is one merged shape (a single state-level estimate), or a state map
+// where New York is broken out into its counties.
+//
+// The unit of substitution is always a whole state: a data row that declares a
+// `geoType` other than the base marks its state, and that state's entire area is
+// re-tiled at the row's level. That keeps the map a partition of the same
+// territory (no gaps, no double-painted areas) whichever direction you mix in.
+//
+// Kept free of Vue/DOM/topojson so it can be unit tested in isolation.
+
+import type { GeoType } from "./ChoroplethMap.vue";
+
+/** Minimal shape of the GeoJSON features this module shuffles around. */
+export interface MixFeature {
+  id?: string | number | null;
+  properties?: { name?: string } | null;
+}
+
+/** id → feature and name → id indexes for one geographic level. */
+export interface LevelLookup<F extends MixFeature = MixFeature> {
+  byId: Map<string, F>;
+  byName: Map<string, string>;
+}
+
+/**
+ * Lazily resolves the lookup for a level, so a map that never mixes never pays
+ * to index the levels it doesn't render. Returns null when the topology can't
+ * supply that level (e.g. "counties" from a states-only topology, or "hsas"
+ * before the lazy HSA chunk loads).
+ */
+export type LevelResolver<F extends MixFeature = MixFeature> = (
+  level: GeoType,
+) => LevelLookup<F> | null;
+
+/** Digits in a fully-qualified id at each level ("06" / "06075"). */
+const ID_WIDTH: Record<GeoType, number> = { states: 2, counties: 5, hsas: 6 };
+
+/**
+ * 2-digit state FIPS a feature id belongs to, or null when it can't be
+ * determined. States and counties carry it as their first two digits; HSA
+ * codes need the FIPS→HSA table (inverted into `hsaToState`), because an HSA
+ * code isn't state-prefixed. No HSA spans two states, so the mapping is total.
+ */
+export function stateOfId(
+  level: GeoType,
+  id: string,
+  hsaToState?: ReadonlyMap<string, string> | null,
+): string | null {
+  if (level === "hsas") return hsaToState?.get(id) ?? null;
+  const padded = id.padStart(ID_WIDTH[level], "0");
+  return /^\d{2}/.test(padded) ? padded.slice(0, 2) : null;
+}
+
+/** Resolves a user-supplied id (code or feature name) to a canonical feature id. */
+function canonicalId(
+  rawId: string,
+  level: GeoType,
+  lookup: LevelLookup,
+): string | null {
+  if (lookup.byId.has(rawId)) return rawId;
+  const padded = rawId.padStart(ID_WIDTH[level], "0");
+  if (lookup.byId.has(padded)) return padded;
+  return lookup.byName.get(rawId) ?? null;
+}
+
+/** A `data` row as far as mixing is concerned. */
+export interface MixRow {
+  id: string;
+  geoType?: GeoType;
+}
+
+export interface OverrideResolution {
+  /** state FIPS → the level that state renders at. */
+  overrides: Map<string, GeoType>;
+  /** Row ids whose state couldn't be resolved (bad id, or level unavailable). */
+  unresolved: string[];
+  /**
+   * Row ids that named an already-claimed state at a different level. The first
+   * row wins; these are reported so the caller can warn.
+   */
+  conflicts: string[];
+}
+
+/**
+ * Collects the per-state level overrides implied by `rows`. Rows without a
+ * `geoType`, or whose `geoType` matches the base map, are plain data and are
+ * ignored here.
+ */
+export function resolveGeoOverrides(
+  rows: readonly MixRow[] | undefined,
+  baseGeoType: GeoType,
+  getLevel: LevelResolver,
+  hsaToState?: ReadonlyMap<string, string> | null,
+): OverrideResolution {
+  const overrides = new Map<string, GeoType>();
+  const unresolved: string[] = [];
+  const conflicts: string[] = [];
+  if (!rows) return { overrides, unresolved, conflicts };
+
+  for (const row of rows) {
+    const level = row.geoType;
+    if (!level || level === baseGeoType) continue;
+    const lookup = getLevel(level);
+    if (!lookup) {
+      unresolved.push(row.id);
+      continue;
+    }
+    const id = canonicalId(row.id, level, lookup);
+    const fips = id == null ? null : stateOfId(level, id, hsaToState);
+    if (!fips) {
+      unresolved.push(row.id);
+      continue;
+    }
+    const claimed = overrides.get(fips);
+    if (claimed == null) overrides.set(fips, level);
+    else if (claimed !== level) conflicts.push(row.id);
+  }
+  return { overrides, unresolved, conflicts };
+}
+
+/**
+ * Serializes overrides into a comparable key. The caller derives the override
+ * map from this string so its identity only changes when the *set* of overrides
+ * does — otherwise every `data` update would rebuild the whole feature tree.
+ */
+export function serializeOverrides(overrides: Map<string, GeoType>): string {
+  return [...overrides]
+    .map(([fips, level]) => `${fips}:${level}`)
+    .sort()
+    .join(",");
+}
+
+/** Inverse of `serializeOverrides`. */
+export function parseOverrides(key: string): Map<string, GeoType> {
+  const map = new Map<string, GeoType>();
+  if (!key) return map;
+  for (const part of key.split(",")) {
+    const [fips, level] = part.split(":");
+    map.set(fips, level as GeoType);
+  }
+  return map;
+}
+
+export interface MixedFeatures<F extends MixFeature> {
+  features: F[];
+  /**
+   * Feature id → level, for substituted features only. Ids absent from the map
+   * render at the base `geoType`.
+   */
+  levelById: Map<string, GeoType>;
+}
+
+/**
+ * Replaces every overridden state's base features with that state's features at
+ * the override level. Returns `base` untouched when there's nothing to mix, so
+ * the common case costs one `size` check.
+ *
+ * `scopeFips` mirrors the map's single-state mode: substituted features outside
+ * the scoped state are dropped, exactly as the base set already is.
+ */
+export function mixFeatures<F extends MixFeature>(
+  base: readonly F[],
+  baseGeoType: GeoType,
+  overrides: Map<string, GeoType>,
+  getLevel: LevelResolver<F>,
+  hsaToState?: ReadonlyMap<string, string> | null,
+  scopeFips?: string | null,
+): MixedFeatures<F> {
+  const levelById = new Map<string, GeoType>();
+  if (overrides.size === 0) return { features: base as F[], levelById };
+
+  // Collect the replacements first: a state is only cut out of the base once
+  // something is standing by to cover it, so a level that isn't ready yet (the
+  // lazy HSA chunk) leaves the base map intact instead of punching a hole.
+  const substitutes: F[] = [];
+  const replaced = new Set<string>();
+  for (const [fips, level] of overrides) {
+    if (scopeFips && fips !== scopeFips) continue;
+    const lookup = getLevel(level);
+    if (!lookup) continue;
+    const forState: F[] = [];
+    for (const [id, f] of lookup.byId) {
+      if (stateOfId(level, id, hsaToState) !== fips) continue;
+      forState.push(f);
+      levelById.set(id, level);
+    }
+    if (!forState.length) continue;
+    replaced.add(fips);
+    substitutes.push(...forState);
+  }
+  if (!replaced.size) return { features: base as F[], levelById };
+
+  const features = base.filter((f) => {
+    const fips = stateOfId(baseGeoType, String(f.id), hsaToState);
+    return !(fips && replaced.has(fips));
+  });
+  features.push(...substitutes);
+  return { features, levelById };
+}

package/src/DataTable/DataTable.md

@@ -0,0 +1,372 @@
+# DataTable
+
+A table for displaying columnar data. Accepts a plain record of arrays or a `ModelOutput` from a simulation.
+
+## Examples
+
+### Basic usage
+
+<ComponentDemo>
+  <DataTable :data="{ day: [0, 1, 2, 3, 4], susceptible: [1000, 980, 945, 900, 860], infected: [1, 21, 56, 101, 141] }" />
+
+<template #code>
+
+```vue
+<DataTable
+  :data="{
+    day: [0, 1, 2, 3, 4],
+    susceptible: [1000, 980, 945, 900, 860],
+    infected: [1, 21, 56, 101, 141],
+  }"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+### Column labels and width
+
+<ComponentDemo>
+  <DataTable
+    :data="{ day: [0, 1, 2, 3, 4], susceptible: [1000, 980, 945, 900, 860], infected: [1, 21, 56, 101, 141] }"
+    :column-config="{
+      day: { label: 'Day', width: 'small' },
+      susceptible: { label: 'Susceptible' },
+      infected: { label: 'Infected' },
+    }"
+  />
+
+<template #code>
+
+```vue
+<DataTable
+  :data="{
+    day: [0, 1, 2, 3, 4],
+    susceptible: [1000, 980, 945, 900, 860],
+    infected: [1, 21, 56, 101, 141],
+  }"
+  :column-config="{
+    day: { label: 'Day', width: 'small' },
+    susceptible: { label: 'Susceptible' },
+    infected: { label: 'Infected' },
+  }"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+### Formatting cell values
+
+Use `format` on a column to override the default rendering. Accepts a
+{@link NumberFormat} value — a preset name (optionally with `:N` digits,
+e.g. `"percent:1"`), a printf-style format string, or a function
+`(value, row) => string`. Formatted values are also used in CSV exports.
+
+<ComponentDemo>
+  <DataTable
+    :data="{ day: [0, 1, 2, 3, 4], rate: [0.012, 0.234, 0.467, 0.512, 0.601], cases: [1, 21, 56, 101, 141] }"
+    :column-config="{
+      day: { label: 'Day', width: 'small' },
+      rate: { label: 'Attack rate', format: 'percent:1' },
+      cases: { label: 'Cases', format: '%05d' },
+    }"
+  />
+
+<template #code>
+
+```vue
+<DataTable
+  :data="{
+    day: [0, 1, 2, 3, 4],
+    rate: [0.012, 0.234, 0.467, 0.512, 0.601],
+    cases: [1, 21, 56, 101, 141],
+  }"
+  :column-config="{
+    day: { label: 'Day', width: 'small' },
+    rate: { label: 'Attack rate', format: 'percent:1' },
+    cases: { label: 'Cases', format: '%05d' },
+  }"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+### Cell class and max rows
+
+<ComponentDemo>
+  <DataTable
+    :data="{ generation: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9], cases: [1, 3, 8, 15, 28, 45, 62, 71, 55, 30] }"
+    :max-rows="5"
+    :column-config="{
+      generation: { label: 'Gen', cellClass: 'text-secondary', width: 50 },
+      cases: { label: 'Cases' },
+    }"
+  />
+
+<template #code>
+
+```vue
+<DataTable
+  :data="{
+    generation: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+    cases: [1, 3, 8, 15, 28, 45, 62, 71, 55, 30],
+  }"
+  :max-rows="5"
+  :column-config="{
+    generation: { label: 'Gen', cellClass: 'text-secondary', width: 50 },
+    cases: { label: 'Cases' },
+  }"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+### Wrapping long content
+
+By default, cell content stays on one line and truncates with an ellipsis
+when it's wider than the column — so a long string in one column can't
+spill into the next. Set `wrap: true` on a column to let it grow
+vertically instead.
+
+<ComponentDemo>
+  <DataTable
+    :data="{
+      drug: ['Compound A', 'Compound B', 'Compound C'],
+      note: [
+        'Well tolerated at all tested doses; no adverse events reported.',
+        'Mild GI symptoms in 4% of participants; resolved without intervention.',
+        'Discontinued at week 6 after liver-enzyme elevation in two participants.',
+      ],
+    }"
+    :column-config="{
+      drug: { width: 'small' },
+      note: { wrap: true, width: 'large' },
+    }"
+  />
+
+<template #code>
+
+```vue
+<DataTable
+  :data="{
+    drug: ['Compound A', 'Compound B', 'Compound C'],
+    note: [
+      'Well tolerated at all tested doses; no adverse events reported.',
+      'Mild GI symptoms in 4% of participants; resolved without intervention.',
+      'Discontinued at week 6 after liver-enzyme elevation in two participants.',
+    ],
+  }"
+  :column-config="{
+    drug: { width: 'small' },
+    note: { wrap: true, width: 'large' },
+  }"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+Use `columnClass` to attach a class to both the header and every body
+cell in a column — handy when whole-column styling (background, border,
+font weight) should match across the header and data. `cellClass` keeps
+its meaning (body cells only).
+
+### Full width
+
+By default the table sizes to its content (columns default to a fixed
+medium width, so they're evenly spaced). Pass `full-width` to stretch the
+table to fill its container; columns without an explicit width will share
+the available space equally.
+
+<ComponentDemo>
+  <DataTable
+    :data="{ day: [0, 1, 2, 3, 4], susceptible: [1000, 980, 945, 900, 860], infected: [1, 21, 56, 101, 141] }"
+    full-width
+  />
+
+<template #code>
+
+```vue
+<DataTable
+  :data="{
+    day: [0, 1, 2, 3, 4],
+    susceptible: [1000, 980, 945, 900, 860],
+    infected: [1, 21, 56, 101, 141],
+  }"
+  full-width
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+### Download menu
+
+A `⋯` menu appears in the top-right corner of every table with a
+**Download** item that exports the data as CSV. Use `download-menu-link`
+to customize the menu item label and `filename` to control the
+downloaded filename. Pass `:menu="false"` to hide the menu entirely.
+
+<ComponentDemo>
+  <DataTable
+    :data="{ day: [0, 1, 2, 3, 4], cases: [1, 21, 56, 101, 141] }"
+    filename="sir-cases"
+    download-menu-link="Download cases (CSV)"
+  />
+
+<template #code>
+
+```vue
+<DataTable
+  :data="{
+    day: [0, 1, 2, 3, 4],
+    cases: [1, 21, 56, 101, 141],
+  }"
+  filename="sir-cases"
+  download-menu-link="Download cases (CSV)"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+### Custom CSV download
+
+By default, the Download menu item exports the displayed table as CSV.
+Use the `csv` prop to supply your own content — for example, to include
+ISO dates, extra columns that aren't in the table, or values formatted
+differently from the on-screen rendering. Accepts a raw string or a
+function returning one (called lazily on click).
+
+<ComponentDemo>
+  <DataTable
+    :data="{ day: [0, 1, 2, 3, 4], cases: [1, 21, 56, 101, 141] }"
+    filename="sir-cases"
+    :csv="'date,day,cases\n2024-01-01,0,1\n2024-01-02,1,21\n2024-01-03,2,56\n2024-01-04,3,101\n2024-01-05,4,141'"
+  />
+
+<template #code>
+
+```vue
+<DataTable
+  :data="{
+    day: [0, 1, 2, 3, 4],
+    cases: [1, 21, 56, 101, 141],
+  }"
+  filename="sir-cases"
+  :csv="`date,day,cases
+2024-01-01,0,1
+2024-01-02,1,21
+2024-01-03,2,56
+2024-01-04,3,101
+2024-01-05,4,141`"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+### Download button
+
+Pass `download-button` to render a visible, labeled button beneath the
+table instead of exposing the download only via the top-right menu. The
+button uses `download-menu-link` as its label, and the menu's Download
+item is suppressed so the action isn't duplicated. The button has the
+class `data-table-download-button` and its styles are unscoped, so it
+can be targeted directly from custom CSS without specificity battles.
+
+<ComponentDemo>
+  <DataTable
+    :data="{ day: [0, 1, 2, 3, 4], cases: [1, 21, 56, 101, 141] }"
+    filename="sir-cases"
+    download-menu-link="Download CSV"
+    download-button
+    :csv="'date,day,cases\n2024-01-01,0,1\n2024-01-02,1,21\n2024-01-03,2,56\n2024-01-04,3,101\n2024-01-05,4,141'"
+  />
+
+<template #code>
+
+```vue
+<DataTable
+  :data="{
+    day: [0, 1, 2, 3, 4],
+    cases: [1, 21, 56, 101, 141],
+  }"
+  filename="sir-cases"
+  download-menu-link="Download CSV"
+  download-button
+  :csv="`date,day,cases
+2024-01-01,0,1
+2024-01-02,1,21
+2024-01-03,2,56
+2024-01-04,3,101
+2024-01-05,4,141`"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+### Download link
+
+Pass `download-link` to render a plain text link beneath the table
+instead of (or alongside) the menu. It's a real `<a href download>` —
+right-click → Save As works. Pass `true` for the default "Download data
+(CSV)" label, or a string to customize. The menu's Download item is
+suppressed when this is set. If both `download-link` and
+`download-button` are set, the button wins.
+
+<ComponentDemo>
+  <DataTable
+    :data="{ day: [0, 1, 2, 3, 4], cases: [1, 21, 56, 101, 141] }"
+    filename="sir-cases"
+    download-link
+  />
+
+<template #code>
+
+```vue
+<DataTable
+  :data="{
+    day: [0, 1, 2, 3, 4],
+    cases: [1, 21, 56, 101, 141],
+  }"
+  filename="sir-cases"
+  download-link
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+<!--@include: ./_api/data-table.md-->
+
+### ColumnConfig
+
+```ts
+interface ColumnConfig {
+  label?: string;
+  width?: "small" | "medium" | "large" | number;
+  align?: "left" | "center" | "right";
+  /** Class applied to body `<td>` cells only. */
+  cellClass?: string;
+  /** Class applied to both the header `<th>` and body `<td>` cells. */
+  columnClass?: string;
+  /** Allow cell contents to wrap. Default `false` (nowrap + ellipsis). */
+  wrap?: boolean;
+  format?: NumberFormat | ((value: CellValue, row: number) => string);
+}
+
+type CellValue = number | string | boolean;
+
+type NumberFormat =
+  | NumberFormatPreset // "plain" | "localized" | "percent" | "compact" | "scientific" | "engineering" (optionally with ":N" digits, e.g. "percent:1")
+  | string // printf-style format, e.g. "%.2f", "%05d"
+  | ((value: number) => string);
+```
+
+See `formatNumber` in `@cfasim-ui/shared` for the underlying utility — you
+can also call it directly in your own code.