@cfasim-ui/docs 0.4.15 → 0.5.0

package/charts/DataTable/DataTable.md

@@ -124,6 +124,56 @@ e.g. `"percent:1"`), a printf-style format string, or a function
   </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
@@ -157,9 +207,8 @@ the available space equally.
 
 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, `filename` to control the downloaded
-filename, and `csv` to supply custom CSV content. Pass `:menu="false"`
-to hide the menu entirely.
+to customize the menu item label and `filename` to control the
+downloaded filename. Pass `:menu="false"` to hide the menu entirely.
 
 <ComponentDemo>
   <DataTable
@@ -184,6 +233,115 @@ to hide the menu entirely.
   </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>
+
 ## Props
 
 | Prop | Type | Required | Default |
@@ -195,6 +353,8 @@ to hide the menu entirely.
 | `csv` | `string \| (() =&gt; string)` | No | — |
 | `filename` | `string` | No | — |
 | `downloadMenuLink` | `string` | No | `"Download"` |
+| `downloadButton` | `boolean` | No | `false` |
+| `downloadLink` | `boolean \| string` | No | — |
 | `fullWidth` | `boolean` | No | `false` |
 
 
@@ -205,7 +365,12 @@ 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);
 }
 

package/charts/DataTable/DataTable.vue

@@ -21,7 +21,22 @@ export interface ColumnConfig {
   label?: string;
   width?: ColumnWidth | number;
   align?: ColumnAlign;
+  /** Class applied to every body `<td>` in this column. */
   cellClass?: string;
+  /**
+   * Class applied to both the header `<th>` and every body `<td>` in
+   * this column. Use for styling that should span the whole column
+   * (borders, backgrounds, fonts). For body-only styling, use
+   * `cellClass`.
+   */
+  columnClass?: string;
+  /**
+   * Allow cell contents to wrap to multiple lines when wider than the
+   * column. Default `false` — cells stay on one line and truncate with
+   * an ellipsis. Set to `true` for text-heavy columns where the full
+   * value should remain visible.
+   */
+  wrap?: boolean;
   /**
    * Custom formatter for cell values in this column. Accepts a
    * {@link NumberFormat} (preset name, printf-style string, or
@@ -54,14 +69,34 @@ const props = withDefaults(
     /** Filename (without extension) for downloaded CSV files. */
     filename?: string;
     /**
-     * Label for the Download item in the table's top-right menu.
-     * Defaults to "Download".
+     * Label for the Download item in the table's top-right menu, and for
+     * the button rendered when `downloadButton` is true. Defaults to
+     * "Download".
      */
     downloadMenuLink?: string;
+    /**
+     * Render a visible "Download" button beneath the table instead of
+     * exposing the action only via the top-right menu. When enabled, the
+     * menu's Download item is suppressed to avoid duplicate controls.
+     */
+    downloadButton?: boolean;
+    /**
+     * Render a plain text link beneath the table for downloading CSV.
+     * Pass `true` for the default "Download data (CSV)" label, or a
+     * string to customize. When set, the menu's Download item is
+     * suppressed. Mutually exclusive with `downloadButton`; if both are
+     * set, `downloadButton` wins.
+     */
+    downloadLink?: boolean | string;
     /** Stretch the table to fill its container's width. */
     fullWidth?: boolean;
   }>(),
-  { menu: true, fullWidth: false, downloadMenuLink: "Download" },
+  {
+    menu: true,
+    fullWidth: false,
+    downloadMenuLink: "Download",
+    downloadButton: false,
+  },
 );
 
 function columnLabel(name: string): string {
@@ -84,6 +119,20 @@ function columnAlignStyle(name: string): CSSProperties | undefined {
   return { textAlign: align };
 }
 
+/** Classes shared by `<th>` and `<td>` for a column: `columnClass` + wrap flag. */
+function columnSharedClass(name: string): (string | undefined)[] {
+  const cfg = props.columnConfig?.[name];
+  return [cfg?.columnClass, cfg?.wrap ? "cell-wrap" : undefined];
+}
+
+function headerCellClass(name: string): (string | undefined)[] {
+  return columnSharedClass(name);
+}
+
+function bodyCellClass(name: string): (string | undefined)[] {
+  return [...columnSharedClass(name), props.columnConfig?.[name]?.cellClass];
+}
+
 function isModelOutput(d: TableData): d is ModelOutput {
   return typeof (d as ModelOutput).column === "function";
 }
@@ -165,14 +214,30 @@ function toCsv(): string {
   return lines.join("\n");
 }
 
-const menuItems = computed<ChartMenuItem[]>(() => [
-  {
-    label: props.downloadMenuLink,
-    action: () => downloadCsv(toCsv(), menuFilename()),
-  },
-]);
+function triggerDownload() {
+  downloadCsv(toCsv(), menuFilename());
+}
+
+const menuItems = computed<ChartMenuItem[]>(() => {
+  if (props.downloadButton || props.downloadLink) return [];
+  return [{ label: props.downloadMenuLink, action: triggerDownload }];
+});
 
-const showMenu = computed(() => Boolean(props.menu));
+const downloadLinkText = computed<string | null>(() => {
+  if (props.downloadButton) return null;
+  const v = props.downloadLink;
+  if (!v) return null;
+  return typeof v === "string" ? v : "Download data (CSV)";
+});
+
+const csvHref = computed<string | null>(() => {
+  if (!downloadLinkText.value) return null;
+  return `data:text/csv;charset=utf-8,${encodeURIComponent(toCsv())}`;
+});
+
+const showMenu = computed(
+  () => Boolean(props.menu) && menuItems.value.length > 0,
+);
 </script>
 
 <template>
@@ -195,6 +260,7 @@ const showMenu = computed(() => Boolean(props.menu));
             <th
               v-for="col in columns"
               :key="col.name"
+              :class="headerCellClass(col.name)"
               :style="columnAlignStyle(col.name)"
             >
               {{ columnLabel(col.name) }}
@@ -206,7 +272,7 @@ const showMenu = computed(() => Boolean(props.menu));
             <td
               v-for="col in columns"
               :key="col.name"
-              :class="columnConfig?.[col.name]?.cellClass"
+              :class="bodyCellClass(col.name)"
               :style="columnAlignStyle(col.name)"
             >
               {{ cellValue(col, row - 1) }}
@@ -215,6 +281,22 @@ const showMenu = computed(() => Boolean(props.menu));
         </tbody>
       </table>
     </div>
+    <button
+      v-if="downloadButton"
+      type="button"
+      class="data-table-download-button"
+      @click="triggerDownload"
+    >
+      {{ downloadMenuLink }}
+    </button>
+    <a
+      v-else-if="downloadLinkText"
+      class="data-table-download-link"
+      :href="csvHref!"
+      :download="`${menuFilename()}.csv`"
+    >
+      {{ downloadLinkText }}
+    </a>
   </div>
 </template>
 
@@ -257,9 +339,18 @@ const showMenu = computed(() => Boolean(props.menu));
 .Table td {
   padding: 0.75em 1.25em;
   white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
   text-align: left;
 }
 
+.Table th.cell-wrap,
+.Table td.cell-wrap {
+  white-space: normal;
+  overflow: visible;
+  text-overflow: clip;
+}
+
 .Table th {
   font-weight: 600;
   border-bottom: 1px solid var(--color-border-header);
@@ -288,3 +379,34 @@ const showMenu = computed(() => Boolean(props.menu));
   padding-right: 2.5em;
 }
 </style>
+
+<style>
+.data-table-download-button {
+  display: inline-flex;
+  align-items: center;
+  margin-top: 0.75em;
+  padding: 0.5em 1em;
+  border: 1px solid var(--color-border);
+  border-radius: 0.25em;
+  background: var(--color-bg-0, #fff);
+  color: var(--color-text);
+  font-size: var(--font-size-sm);
+  cursor: pointer;
+}
+
+.data-table-download-button:hover {
+  background: var(--color-bg-1, rgba(0, 0, 0, 0.05));
+}
+
+.data-table-download-button:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+}
+
+.data-table-download-link {
+  display: block;
+  text-align: right;
+  font-size: var(--font-size-sm);
+  margin-top: 0.25em;
+}
+</style>

package/charts/LineChart/LineChart.md

@@ -941,7 +941,10 @@ dates, categorical labels, or extra columns that aren't plotted). Use
 `filename` to control the download filename (shared by SVG, PNG and CSV).
 
 Pass `download-link` to also render a plain text link below the chart — set
-it to `true` for the default label, or pass a string to customize it.
+it to `true` for the default label, or pass a string to customize it. Use
+`download-button` instead to render a styled `<button>` (with the class
+`line-chart-download-button`, available for custom CSS) in place of the
+link.
 
 <ComponentDemo>
   <LineChart
@@ -1004,6 +1007,7 @@ until the user clicks Download:
 | `csv` | `string \| (() =&gt; string)` | No | — |
 | `filename` | `string` | No | — |
 | `downloadLink` | `boolean \| string` | No | — |
+| `downloadButton` | `boolean \| string` | No | — |
 | `annotations` | `readonly ChartAnnotation[]` | No | — |
 | `chartPadding` | `ChartPadding` | No | — |
 | `y` | `LineChartData` | No | — |

package/charts/LineChart/LineChart.vue

@@ -929,6 +929,8 @@ const {
   menuItems,
   downloadLinkText,
   csvHref,
+  downloadButtonText,
+  triggerCsvDownload,
   menuFilename,
   isFullscreen,
 } = useChartFoundation({
@@ -944,6 +946,7 @@ const {
   tooltipClamp: () => props.tooltipClamp,
   filename: () => props.filename,
   downloadLink: () => props.downloadLink,
+  downloadButton: () => props.downloadButton,
   chartPadding: () => props.chartPadding,
   inlineLegendLabels: () => inlineLegendLabels.value,
   hasTooltipSlot: () => hasTooltipSlot.value,
@@ -1403,6 +1406,14 @@ const positionedLegendItems = computed(() => {
     >
       {{ downloadLinkText }}
     </a>
+    <button
+      v-if="downloadButtonText"
+      type="button"
+      class="line-chart-download-button"
+      @click="triggerCsvDownload"
+    >
+      {{ downloadButtonText }}
+    </button>
   </div>
 </template>
 
@@ -1438,3 +1449,27 @@ const positionedLegendItems = computed(() => {
   flex-shrink: 0;
 }
 </style>
+
+<style>
+.line-chart-download-button {
+  display: inline-flex;
+  align-items: center;
+  margin-top: 0.5em;
+  padding: 0.5em 1em;
+  border: 1px solid var(--color-border);
+  border-radius: 0.25em;
+  background: var(--color-bg-0, #fff);
+  color: var(--color-text);
+  font-size: var(--font-size-sm);
+  cursor: pointer;
+}
+
+.line-chart-download-button:hover {
+  background: var(--color-bg-1, rgba(0, 0, 0, 0.05));
+}
+
+.line-chart-download-button:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+}
+</style>

package/charts/_shared/chartProps.ts

@@ -141,6 +141,13 @@ export interface ChartCommonProps {
    * for the default label or a string to customize.
    */
   downloadLink?: boolean | string;
+  /**
+   * Show a `<button>` below the chart to download CSV. Pass `true` for
+   * the default label or a string to customize. When set, the CSV menu
+   * item is suppressed. Mutually exclusive with `downloadLink`; if both
+   * are set, `downloadButton` wins.
+   */
+  downloadButton?: boolean | string;
   /** Annotations rendered as the top layer of the chart. */
   annotations?: readonly ChartAnnotation[];
   /**

package/charts/_shared/contrast.ts

@@ -0,0 +1,100 @@
+/**
+ * Color helpers for picking a readable text color against a bar fill.
+ * The luminance math is pure and unit-testable; resolving CSS values
+ * that aren't plain hex/rgb (named colors, `var(--x)`) needs the DOM and
+ * is handled separately by {@link resolveColorToRgb}.
+ */
+
+export type Rgb = [number, number, number];
+
+/**
+ * Parse a hex (`#rgb`, `#rrggbb`, `#rrggbbaa`) or `rgb()/rgba()` string to
+ * `[r, g, b]` in 0..255. Returns null for anything else (named colors,
+ * `var(...)`, `hsl(...)`) — resolve those via {@link resolveColorToRgb}.
+ */
+export function parseRgb(color: string): Rgb | null {
+  const c = color.trim();
+  if (c.startsWith("#")) {
+    let hex = c.slice(1);
+    if (hex.length === 3 || hex.length === 4) {
+      hex = hex
+        .slice(0, 3)
+        .split("")
+        .map((ch) => ch + ch)
+        .join("");
+    } else if (hex.length === 6 || hex.length === 8) {
+      hex = hex.slice(0, 6);
+    } else {
+      return null;
+    }
+    const n = Number.parseInt(hex, 16);
+    if (Number.isNaN(n)) return null;
+    return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+  }
+  const m = c.match(/^rgba?\(([^)]+)\)$/i);
+  if (m) {
+    const parts = m[1].split(/[,/\s]+/).filter(Boolean);
+    if (parts.length < 3) return null;
+    const rgb = parts.slice(0, 3).map((p) => {
+      if (p.endsWith("%")) return Math.round((parseFloat(p) / 100) * 255);
+      return Math.round(parseFloat(p));
+    });
+    if (rgb.some((v) => Number.isNaN(v))) return null;
+    return [rgb[0], rgb[1], rgb[2]];
+  }
+  return null;
+}
+
+/** WCAG relative luminance (0 = black, 1 = white) for an RGB triple. */
+export function relativeLuminance([r, g, b]: Rgb): number {
+  const channel = (v: number) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+let probe: HTMLSpanElement | null = null;
+const resolveCache = new Map<string, Rgb | null>();
+
+/**
+ * Resolve any CSS color string (including named colors and `var(--x)`) to
+ * an RGB triple by letting the browser compute it on a hidden probe
+ * element. Cached per input. Returns null in non-DOM environments or when
+ * the value can't be resolved. Plain hex/rgb shortcut through
+ * {@link parseRgb} without touching the DOM.
+ */
+export function resolveColorToRgb(color: string): Rgb | null {
+  const direct = parseRgb(color);
+  if (direct) return direct;
+  if (resolveCache.has(color)) return resolveCache.get(color) ?? null;
+  if (typeof document === "undefined") return null;
+  if (!probe) {
+    probe = document.createElement("span");
+    probe.style.cssText =
+      "position:absolute;width:0;height:0;visibility:hidden;pointer-events:none";
+    document.body.appendChild(probe);
+  }
+  probe.style.color = "";
+  probe.style.color = color;
+  const computed = getComputedStyle(probe).color;
+  const rgb = parseRgb(computed);
+  resolveCache.set(color, rgb);
+  return rgb;
+}
+
+/**
+ * Pick the more readable of `light`/`dark` text colors for a given fill.
+ * Uses the WCAG luminance threshold (0.179) that maximizes contrast
+ * against black-or-white text. When the fill can't be resolved (e.g. an
+ * unresolvable CSS var in a non-DOM context), falls back to `light`.
+ */
+export function pickContrastColor(
+  fill: string,
+  light = "#ffffff",
+  dark = "#1a1a1a",
+): string {
+  const rgb = resolveColorToRgb(fill);
+  if (!rgb) return light;
+  return relativeLuminance(rgb) > 0.179 ? dark : light;
+}

package/charts/_shared/index.ts

@@ -54,6 +54,13 @@ export type {
   BlendMode,
   LineMarkStyle,
 } from "./chartProps.js";
+export {
+  parseRgb,
+  relativeLuminance,
+  resolveColorToRgb,
+  pickContrastColor,
+  type Rgb,
+} from "./contrast.js";
 export {
   parseDate,
   isDateLike,

package/charts/_shared/useChartFoundation.ts

@@ -25,6 +25,7 @@ export interface ChartFoundationOptions {
   tooltipClamp: () => TooltipClamp | undefined;
   filename: () => string | undefined;
   downloadLink: () => boolean | string | undefined;
+  downloadButton: () => boolean | string | undefined;
   chartPadding: () => ChartPadding | undefined;
   // Chart-specific hooks that the composable can't infer.
   /**
@@ -61,6 +62,8 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
     items: menuItems,
     downloadLinkText,
     csvHref,
+    downloadButtonText,
+    triggerCsvDownload,
     resolvedFilename: menuFilename,
     isFullscreen,
   } = useChartMenu({
@@ -68,6 +71,7 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
     legacyMenuLabel: opts.menu,
     getCsv: opts.getCsv,
     downloadLink: opts.downloadLink,
+    downloadButton: opts.downloadButton,
     fullscreen: true,
   });
 
@@ -130,6 +134,8 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
     menuItems,
     downloadLinkText,
     csvHref,
+    downloadButtonText,
+    triggerCsvDownload,
     menuFilename,
     isFullscreen,
     measuredHeight,