@cfasim-ui/docs 0.4.15 → 0.5.0

package/charts/_shared/useChartMenu.ts

@@ -11,6 +11,8 @@ export interface ChartMenuOptions {
   getCsv: () => string;
   /** Whether a separate download link is rendered (and the CSV menu item should be hidden). */
   downloadLink: () => boolean | string | undefined;
+  /** 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
@@ -56,7 +58,8 @@ export function useChartMenu(opts: ChartMenuOptions) {
         },
       },
     );
-    if (!opts.downloadLink()) {
+    const buttonOn = opts.downloadButton?.();
+    if (!opts.downloadLink() && !buttonOn) {
       out.push({
         label: "Download CSV",
         action: () => downloadCsv(opts.getCsv(), fname),
@@ -66,21 +69,35 @@ export function useChartMenu(opts: ChartMenuOptions) {
   });
 
   const downloadLinkText = computed<string | null>(() => {
+    if (opts.downloadButton?.()) return null;
     const v = opts.downloadLink();
     if (!v) return null;
     return typeof v === "string" ? v : "Download data (CSV)";
   });
 
   const csvHref = computed<string | null>(() => {
+    if (opts.downloadButton?.()) return null;
     if (!opts.downloadLink()) return null;
     return `data:text/csv;charset=utf-8,${encodeURIComponent(opts.getCsv())}`;
   });
 
+  const downloadButtonText = computed<string | null>(() => {
+    const v = opts.downloadButton?.();
+    if (!v) return null;
+    return typeof v === "string" ? v : "Download data (CSV)";
+  });
+
+  function triggerCsvDownload() {
+    downloadCsv(opts.getCsv(), resolvedFilename());
+  }
+
   return {
     svgRef: svgRef as Ref<SVGSVGElement | null>,
     items,
     downloadLinkText,
     csvHref,
+    downloadButtonText,
+    triggerCsvDownload,
     resolvedFilename,
     isFullscreen: fullscreen?.isFullscreen ?? ref(false),
   };

package/charts/env.d.ts

@@ -0,0 +1,4 @@
+// Ambient declaration for side-effect CSS imports (e.g. `import "./x.css"`).
+// Required since TypeScript 6, which errors (TS2882) on side-effect imports
+// without a module declaration.
+declare module "*.css";

package/components/Icon/Icon.md

@@ -1,6 +1,14 @@
 # Icon
 
-Renders a [Material Symbols Outlined](https://fonts.google.com/icons) icon.
+Renders a [Material Symbols](https://fonts.google.com/icons) icon as an inline
+SVG. Icons are resolved from a registry by name, so you reference them exactly as
+before — `<Icon icon="help" />` — but no webfont is loaded: only the SVGs you
+actually use end up in your bundle.
+
+A [base set](#base-set) of common icons is pre-registered and works with zero
+setup. These SVGs are bundled inside `cfasim-ui`, so they need no extra install
+or config — just `<Icon icon="help" />`. To use any other icon,
+[register it](#registering-icons).
 
 ## Examples
 
@@ -52,6 +60,119 @@ Renders a [Material Symbols Outlined](https://fonts.google.com/icons) icon.
   </template>
 </ComponentDemo>
 
+## Base set
+
+These icons are bundled with `cfasim-ui` and need no install or registration —
+just pass the name to `icon`. Anything not listed here must be
+[registered](#registering-icons).
+
+<script setup>
+const baseIcons = [
+  "help", "favorite", "dark_mode", "light_mode",
+  "chevron_left", "chevron_right", "keyboard_arrow_up", "keyboard_arrow_down",
+  "keyboard_double_arrow_left", "keyboard_double_arrow_right",
+  "arrow_upward", "arrow_downward", "arrow_back", "arrow_forward",
+  "menu", "more_vert", "more_horiz",
+  "add", "edit", "delete", "close", "check", "search", "tune", "download",
+  "github",
+];
+</script>
+
+<Grid class="base-icons" :cols="4" :colsSmall="2" gap="sm">
+  <div v-for="name in baseIcons" :key="name" class="base-icons__cell">
+    <Icon :icon="name" size="lg" :aria-label="name" />
+    <code>{{ name }}</code>
+  </div>
+</Grid>
+
+<style>
+.base-icons__cell {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.75rem 0.5rem;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  text-align: center;
+}
+.base-icons__cell code {
+  font-size: 0.65rem;
+  word-break: break-word;
+}
+</style>
+
+`favorite` also has a filled variant via `:fill="true"`.
+
+## Registering icons
+
+The base set above is bundled with `cfasim-ui` and needs none of the steps below
+— this section is only for additional icons. `cfasim-ui` does not depend on
+`@material-symbols/svg-400`, so you install the icons yourself; each one you
+import is inlined into _your_ bundle (still no webfont).
+
+### 1. Install the icons and the Vite SVG loader
+
+```sh
+pnpm add -D @material-symbols/svg-400 vite-svg-loader
+```
+
+### 2. Add `svgLoader` to your Vite config
+
+Add it to your existing `plugins` array — leave the other plugins in place:
+
+```ts
+// vite.config.ts
+import svgLoader from "vite-svg-loader";
+
+export default defineConfig({
+  plugins: [
+    // ...your existing plugins
+    svgLoader(),
+  ],
+});
+```
+
+### 3. Register the icons once at startup
+
+Import each SVG from the `outlined` style with the `?component` query, then pass
+them to `registerIcons`. The key you register is the name you pass to `icon`.
+
+```ts
+// main.ts
+import rocket from "@material-symbols/svg-400/outlined/rocket.svg?component";
+import settings from "@material-symbols/svg-400/outlined/settings.svg?component";
+import { registerIcons } from "@cfasim-ui/components";
+
+registerIcons({ rocket, settings });
+```
+
+### 4. Use them by name
+
+```vue
+<Icon icon="rocket" />
+<Icon icon="settings" size="lg" />
+```
+
+An unregistered name renders nothing and logs a one-time console warning with the
+exact code to register it.
+
+### Filled variants
+
+To support `:fill="true"` on a registered icon, register both the outline and
+`-fill` files:
+
+```ts
+import favorite from "@material-symbols/svg-400/outlined/favorite.svg?component";
+import favoriteFill from "@material-symbols/svg-400/outlined/favorite-fill.svg?component";
+
+registerIcons({ favorite: { outline: favorite, fill: favoriteFill } });
+```
+
+> The `weight` and `grade` props are deprecated no-ops — static SVGs ship at
+> weight 400, grade 0. `size`, `fill`, `inline`, and color (`currentColor`) work
+> as before.
+
 ## Props
 
 | Prop | Type | Required | Default |

package/components/Icon/Icon.vue

@@ -1,6 +1,12 @@
 <script setup lang="ts">
 import type { CSSProperties } from "vue";
 import { computed } from "vue";
+import { getIconComponent, warnMissingIcon } from "./registry";
+import { registerDefaultIcons } from "./defaultIcons";
+
+// Driven from setup (a retained code path) so the base set survives
+// tree-shaking; idempotent, so the per-instance call is effectively free.
+registerDefaultIcons();
 
 export type IconSize = "sm" | "md" | "lg" | "xl";
 
@@ -8,7 +14,9 @@ interface Props {
   icon: string;
   size?: IconSize | number;
   fill?: boolean;
+  /** @deprecated No effect — SVG icons ship at weight 400. */
   weight?: number;
+  /** @deprecated No effect — SVG icons ship at grade 0. */
   grade?: number;
   decorative?: boolean;
   ariaLabel?: string;
@@ -25,23 +33,17 @@ const props = withDefaults(defineProps<Props>(), {
 const sizePreset = computed(() =>
   typeof props.size === "string" ? props.size : undefined,
 );
-const numericSize = computed(() =>
-  typeof props.size === "number" ? props.size : undefined,
+
+const inlineStyle = computed<CSSProperties>(() =>
+  typeof props.size === "number"
+    ? { width: `${props.size}px`, height: `${props.size}px` }
+    : {},
 );
 
-const inlineStyle = computed<CSSProperties>(() => {
-  const style: CSSProperties = {};
-  if (numericSize.value !== undefined) {
-    style.fontSize = `${numericSize.value}px`;
-    (style as Record<string, unknown>)["--icon-opsz"] = numericSize.value;
-  }
-  if (props.weight !== undefined) {
-    (style as Record<string, unknown>)["--icon-weight"] = props.weight;
-  }
-  if (props.grade !== undefined) {
-    (style as Record<string, unknown>)["--icon-grade"] = props.grade;
-  }
-  return style;
+const svg = computed(() => {
+  const component = getIconComponent(props.icon, props.fill);
+  if (!component) warnMissingIcon(props.icon);
+  return component;
 });
 </script>
 
@@ -49,64 +51,54 @@ const inlineStyle = computed<CSSProperties>(() => {
   <span
     class="Icon"
     :data-size="sizePreset"
-    :data-fill="fill ? 'true' : undefined"
     :data-inline="inline ? 'true' : undefined"
     :style="inlineStyle"
     :aria-hidden="decorative ? true : undefined"
     :aria-label="decorative ? undefined : ariaLabel"
     :role="decorative ? undefined : 'img'"
-    >{{ icon }}</span
   >
+    <component :is="svg" v-if="svg" />
+  </span>
 </template>
 
 <style>
 .Icon {
-  font-family: "Material Symbols Outlined", sans-serif;
-  font-weight: normal;
-  font-style: normal;
-  font-size: 24px;
-  line-height: 1;
-  letter-spacing: normal;
-  text-transform: none;
-  display: inline-block;
-  white-space: nowrap;
-  word-wrap: normal;
-  direction: ltr;
-  font-feature-settings: "liga";
-  -webkit-font-smoothing: antialiased;
-  font-variation-settings:
-    "FILL" var(--icon-fill, 0),
-    "wght" var(--icon-weight, 400),
-    "GRAD" var(--icon-grade, 0),
-    "opsz" var(--icon-opsz, 24);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 24px;
+  height: 24px;
   color: inherit;
 }
 
+.Icon svg {
+  display: block;
+  width: 100%;
+  height: 100%;
+  fill: currentColor;
+}
+
 .Icon[data-size="sm"] {
-  font-size: 20px;
-  --icon-opsz: 20;
+  width: 20px;
+  height: 20px;
 }
 .Icon[data-size="md"] {
-  font-size: 24px;
-  --icon-opsz: 24;
+  width: 24px;
+  height: 24px;
 }
 .Icon[data-size="lg"] {
-  font-size: 28px;
-  --icon-opsz: 28;
+  width: 28px;
+  height: 28px;
 }
 .Icon[data-size="xl"] {
-  font-size: 32px;
-  --icon-opsz: 32;
-}
-
-.Icon[data-fill="true"] {
-  --icon-fill: 1;
+  width: 32px;
+  height: 32px;
 }
 
 .Icon[data-inline="true"] {
-  font-size: inherit;
-  vertical-align: middle;
-  transform: scale(1.2) translateY(-0.05em);
-  transform-origin: 50% 50%;
+  width: 1em;
+  height: 1em;
+  vertical-align: -0.125em;
 }
 </style>

package/components/Icon/defaultIcons.ts

@@ -0,0 +1,92 @@
+// The base icon set, registered on first use of <Icon> so `icon="..."` works
+// with zero setup. These are bundled into the published package (each import
+// inlines a ~0.3-0.6 KB SVG at build time), so consumers need no install.
+//
+// Registration is driven from Icon.vue's setup (a used code path) rather than a
+// bare side-effect import, so it survives tree-shaking of this side-effect-free
+// package.
+//
+// Keep this list and the "Base set" table in Icon.md in sync.
+import help from "@material-symbols/svg-400/outlined/help.svg?component";
+import favorite from "@material-symbols/svg-400/outlined/favorite.svg?component";
+import favorite_fill from "@material-symbols/svg-400/outlined/favorite-fill.svg?component";
+import dark_mode from "@material-symbols/svg-400/outlined/dark_mode.svg?component";
+import light_mode from "@material-symbols/svg-400/outlined/light_mode.svg?component";
+// chevrons / navigation
+import chevron_left from "@material-symbols/svg-400/outlined/chevron_left.svg?component";
+import chevron_right from "@material-symbols/svg-400/outlined/chevron_right.svg?component";
+import keyboard_arrow_up from "@material-symbols/svg-400/outlined/keyboard_arrow_up.svg?component";
+import keyboard_arrow_down from "@material-symbols/svg-400/outlined/keyboard_arrow_down.svg?component";
+import keyboard_double_arrow_left from "@material-symbols/svg-400/outlined/keyboard_double_arrow_left.svg?component";
+import keyboard_double_arrow_right from "@material-symbols/svg-400/outlined/keyboard_double_arrow_right.svg?component";
+// arrows (all directions)
+import arrow_upward from "@material-symbols/svg-400/outlined/arrow_upward.svg?component";
+import arrow_downward from "@material-symbols/svg-400/outlined/arrow_downward.svg?component";
+import arrow_back from "@material-symbols/svg-400/outlined/arrow_back.svg?component";
+import arrow_forward from "@material-symbols/svg-400/outlined/arrow_forward.svg?component";
+// menus
+import menu from "@material-symbols/svg-400/outlined/menu.svg?component";
+import more_vert from "@material-symbols/svg-400/outlined/more_vert.svg?component";
+import more_horiz from "@material-symbols/svg-400/outlined/more_horiz.svg?component";
+// actions
+import add from "@material-symbols/svg-400/outlined/add.svg?component";
+import edit from "@material-symbols/svg-400/outlined/edit.svg?component";
+import deleteIcon from "@material-symbols/svg-400/outlined/delete.svg?component";
+import close from "@material-symbols/svg-400/outlined/close.svg?component";
+import check from "@material-symbols/svg-400/outlined/check.svg?component";
+import search from "@material-symbols/svg-400/outlined/search.svg?component";
+import tune from "@material-symbols/svg-400/outlined/tune.svg?component";
+import download from "@material-symbols/svg-400/outlined/download.svg?component";
+// brand logos (not part of Material Symbols)
+import github from "./github.svg?component";
+import type { IconRegistration } from "./registry";
+import { registerIcons, hasIcon } from "./registry";
+
+const defaults: Record<string, IconRegistration> = {
+  // status / theme
+  help,
+  favorite: { outline: favorite, fill: favorite_fill },
+  dark_mode,
+  light_mode,
+  // chevrons / navigation
+  chevron_left,
+  chevron_right,
+  keyboard_arrow_up,
+  keyboard_arrow_down,
+  keyboard_double_arrow_left,
+  keyboard_double_arrow_right,
+  // arrows (all directions)
+  arrow_upward,
+  arrow_downward,
+  arrow_back,
+  arrow_forward,
+  // menus
+  menu,
+  more_vert,
+  more_horiz,
+  // actions
+  add,
+  edit,
+  delete: deleteIcon,
+  close,
+  check,
+  search,
+  tune,
+  download,
+  // brand logos
+  github,
+};
+
+let registered = false;
+
+/**
+ * Register the base icon set once. A name already registered by the consumer is
+ * left untouched, so explicit `registerIcons` calls always win over defaults.
+ */
+export function registerDefaultIcons(): void {
+  if (registered) return;
+  registered = true;
+  for (const [name, reg] of Object.entries(defaults)) {
+    if (!hasIcon(name)) registerIcons({ [name]: reg });
+  }
+}

package/components/Icon/github.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>

package/components/Icon/registry.ts

@@ -0,0 +1,68 @@
+import type { Component } from "vue";
+
+/** A registered icon. Provide a bare component (outline only) or both variants. */
+export interface IconVariants {
+  outline: Component;
+  fill?: Component;
+}
+
+export type IconRegistration = Component | IconVariants;
+
+const registry = new Map<string, IconVariants>();
+
+function toVariants(reg: IconRegistration): IconVariants {
+  return typeof reg === "object" && reg !== null && "outline" in reg
+    ? (reg as IconVariants)
+    : { outline: reg as Component };
+}
+
+/**
+ * Register icons for use with `<Icon icon="name" />`. Call once at app startup.
+ * Re-registering a name overwrites the previous entry.
+ */
+export function registerIcons(icons: Record<string, IconRegistration>): void {
+  for (const [name, reg] of Object.entries(icons)) {
+    registry.set(name, toVariants(reg));
+  }
+}
+
+/** Resolve the component for an icon name, preferring the fill variant when asked. */
+export function getIconComponent(
+  name: string,
+  fill = false,
+): Component | undefined {
+  const entry = registry.get(name);
+  if (!entry) return undefined;
+  return fill && entry.fill ? entry.fill : entry.outline;
+}
+
+/** Whether an icon name has been registered. */
+export function hasIcon(name: string): boolean {
+  return registry.has(name);
+}
+
+const warned = new Set<string>();
+
+function importSnippet(name: string): string {
+  const validIdent = /^[a-zA-Z_$][\w$]*$/.test(name);
+  const ident = validIdent ? name : `icon_${name.replace(/[^\w$]/g, "_")}`;
+  const reg = validIdent ? `{ ${name} }` : `{ "${name}": ${ident} }`;
+  return (
+    `  import ${ident} from "@material-symbols/svg-400/outlined/${name}.svg?component";\n` +
+    `  import { registerIcons } from "@cfasim-ui/components";\n` +
+    `  registerIcons(${reg});`
+  );
+}
+
+/** Warn once per unregistered icon name with copy-pasteable registration code. */
+export function warnMissingIcon(name: string): void {
+  if (warned.has(name)) return;
+  warned.add(name);
+  console.warn(
+    `[cfasim-ui] Icon "${name}" is not registered — nothing will render.\n` +
+      `Register it once at startup:\n\n` +
+      `${importSnippet(name)}\n\n` +
+      `Requires dev deps "@material-symbols/svg-400" + "vite-svg-loader".\n` +
+      `Docs: https://cdcgov.github.io/cfa-simulator/docs/cfasim-ui/components/icon#registering-icons`,
+  );
+}

package/components/ParamEditor/ParamEditorImpl.vue

@@ -74,15 +74,18 @@ const isMac =
   /Mac|iPhone|iPad/.test(navigator.platform);
 const applyShortcut = isMac ? "⌘S" : "Ctrl+S";
 
-// External value updates (e.g., parent Reset) re-seed the editor. The
-// inequality check keeps the post-apply re-render a no-op: when the
-// parent absorbs the user's apply, `props.value` re-serializes back
-// to the same string the user just typed, so we leave `text` untouched.
+// External value updates (e.g., parent Reset) re-seed the editor. We
+// compare against the last value we sourced from the parent — not
+// against the live editor text — so a parent re-render that hands us a
+// fresh object ref with the same contents doesn't clobber whatever the
+// user is currently typing.
+let lastSeeded = text.value;
 watch(
   () => props.value,
   (v) => {
     const next = serialize(v, format.value);
-    if (next === text.value) return;
+    if (next === lastSeeded) return;
+    lastSeeded = next;
     text.value = next;
     error.value = "";
   },

package/components/index.ts

@@ -8,6 +8,9 @@ export { default as Grid } from "./Grid/Grid.vue";
 export type { GridCols, GridGap } from "./Grid/Grid.vue";
 export { default as Hint } from "./Hint/Hint.vue";
 export { default as Icon } from "./Icon/Icon.vue";
+export type { IconSize } from "./Icon/Icon.vue";
+export { registerIcons, hasIcon } from "./Icon/registry";
+export type { IconRegistration, IconVariants } from "./Icon/registry";
 export { default as LightDarkToggle } from "./LightDarkToggle/LightDarkToggle.vue";
 export { default as NumberInput } from "./NumberInput/NumberInput.vue";
 export type { NumberRange } from "./NumberInput/NumberInput.vue";

package/components/svg.d.ts

@@ -0,0 +1,5 @@
+declare module "*.svg?component" {
+  import type { DefineComponent } from "vue";
+  const component: DefineComponent;
+  export default component;
+}

package/index.json

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

package/package.json

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