@cfasim-ui/components 0.7.8 → 0.8.1

package/src/Icon/Icon.md

@@ -0,0 +1,176 @@
+# 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
+
+### Sizes
+
+<ComponentDemo>
+  <Icon icon="help" size="sm" aria-label="help" />
+  <Icon icon="help" size="md" aria-label="help" />
+  <Icon icon="help" size="lg" aria-label="help" />
+
+<template #code>
+
+```vue
+<Icon icon="help" size="sm" aria-label="help" />
+<Icon icon="help" size="md" aria-label="help" />
+<Icon icon="help" size="lg" aria-label="help" />
+```
+
+  </template>
+</ComponentDemo>
+
+### Filled
+
+<ComponentDemo>
+  <Icon icon="favorite" size="lg" aria-label="favorite" />
+  <Icon icon="favorite" size="lg" :fill="true" aria-label="favorite filled" />
+
+<template #code>
+
+```vue
+<Icon icon="favorite" size="lg" aria-label="favorite" />
+<Icon icon="favorite" size="lg" :fill="true" aria-label="favorite filled" />
+```
+
+  </template>
+</ComponentDemo>
+
+### Inline in text
+
+<ComponentDemo>
+  <p style="margin: 0">Click the <Icon icon="help" size="sm" :inline="true" aria-label="help" /> icon for more info.</p>
+
+<template #code>
+
+```vue
+<p>Click the <Icon icon="help" size="sm" :inline="true" aria-label="help" /> icon for more info.</p>
+```
+
+  </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.
+
+<!--@include: ./_api/icon.md-->

package/src/Icon/Icon.vue

@@ -0,0 +1,104 @@
+<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";
+
+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;
+  inline?: boolean;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  size: "md",
+  fill: false,
+  decorative: true,
+  inline: false,
+});
+
+const sizePreset = computed(() =>
+  typeof props.size === "string" ? props.size : undefined,
+);
+
+const inlineStyle = computed<CSSProperties>(() =>
+  typeof props.size === "number"
+    ? { width: `${props.size}px`, height: `${props.size}px` }
+    : {},
+);
+
+const svg = computed(() => {
+  const component = getIconComponent(props.icon, props.fill);
+  if (!component) warnMissingIcon(props.icon);
+  return component;
+});
+</script>
+
+<template>
+  <span
+    class="Icon"
+    :data-size="sizePreset"
+    :data-inline="inline ? 'true' : undefined"
+    :style="inlineStyle"
+    :aria-hidden="decorative ? true : undefined"
+    :aria-label="decorative ? undefined : ariaLabel"
+    :role="decorative ? undefined : 'img'"
+  >
+    <component :is="svg" v-if="svg" />
+  </span>
+</template>
+
+<style>
+.Icon {
+  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"] {
+  width: 20px;
+  height: 20px;
+}
+.Icon[data-size="md"] {
+  width: 24px;
+  height: 24px;
+}
+.Icon[data-size="lg"] {
+  width: 28px;
+  height: 28px;
+}
+.Icon[data-size="xl"] {
+  width: 32px;
+  height: 32px;
+}
+
+.Icon[data-inline="true"] {
+  width: 1em;
+  height: 1em;
+  vertical-align: -0.125em;
+}
+</style>

package/src/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/src/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/src/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/src/LightDarkToggle/LightDarkToggle.vue

@@ -0,0 +1,49 @@
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import Icon from "../Icon/Icon.vue";
+
+const isDark = ref(window.matchMedia("(prefers-color-scheme: dark)").matches);
+
+function apply(dark: boolean) {
+  document.documentElement.classList.toggle("dark", dark);
+  document.documentElement.classList.toggle("light", !dark);
+}
+
+apply(isDark.value);
+
+watch(isDark, apply);
+</script>
+
+<template>
+  <button
+    class="light-dark-toggle"
+    type="button"
+    :aria-label="isDark ? 'Switch to light mode' : 'Switch to dark mode'"
+    @click="isDark = !isDark"
+  >
+    <Icon :icon="isDark ? 'dark_mode' : 'light_mode'" size="sm" />
+  </button>
+</template>
+
+<style scoped>
+.light-dark-toggle {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  border: 1px solid var(--color-border);
+  border-radius: 0.25em;
+  background: var(--color-bg-0);
+  color: var(--color-text-secondary);
+  cursor: pointer;
+  transition:
+    color var(--transition-fast),
+    background-color var(--transition-fast);
+}
+
+.light-dark-toggle:hover {
+  color: var(--color-text);
+  background: var(--color-bg-1);
+}
+</style>

package/src/MultiSelect/MultiSelect.md

@@ -0,0 +1,142 @@
+---
+keywords:
+  [
+    multiselect,
+    multi-select,
+    autocomplete,
+    combobox,
+    tags,
+    chips,
+    filter,
+    search,
+    typeahead,
+  ]
+---
+
+# MultiSelect
+
+A multi-select combobox with autocomplete. Built on reka-ui's Combobox: type to
+filter the options, click to add them, and selected values appear as removable
+chips. Binds to a `string[]` via `v-model`.
+
+## Examples
+
+<script setup>
+import { ref } from 'vue'
+const states = ref(['ca'])
+const stationery = ref([])
+</script>
+
+<ComponentDemo>
+  <div style="width: 280px">
+    <MultiSelect
+      v-model="states"
+      label="States"
+      placeholder="Search states…"
+      :options="[
+        { value: 'ca', label: 'California' },
+        { value: 'ny', label: 'New York' },
+        { value: 'tx', label: 'Texas' },
+        { value: 'wa', label: 'Washington' },
+        { value: 'fl', label: 'Florida' },
+      ]"
+    />
+  </div>
+
+<template #code>
+
+```vue
+<script setup>
+import { ref } from "vue";
+const states = ref(["ca"]);
+</script>
+
+<MultiSelect
+  v-model="states"
+  label="States"
+  placeholder="Search states…"
+  :options="[
+    { value: 'ca', label: 'California' },
+    { value: 'ny', label: 'New York' },
+    { value: 'tx', label: 'Texas' },
+    { value: 'wa', label: 'Washington' },
+    { value: 'fl', label: 'Florida' },
+  ]"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+Type in the field to filter, click an option to add it, and use a chip's `✕`
+button (or press Backspace in an empty input) to remove a selection.
+
+### Hidden label
+
+Use `hide-label` to visually hide the label while keeping it available to screen
+readers. Prefer this over `aria-label` whenever you have label text.
+
+<ComponentDemo>
+  <div style="width: 280px">
+    <MultiSelect
+      v-model="stationery"
+      label="Supplies"
+      hide-label
+      placeholder="Add supplies…"
+      :options="[
+        { value: 'pen', label: 'Pen' },
+        { value: 'pencil', label: 'Pencil' },
+        { value: 'marker', label: 'Marker' },
+        { value: 'eraser', label: 'Eraser' },
+      ]"
+    />
+  </div>
+
+<template #code>
+
+```vue
+<MultiSelect
+  v-model="supplies"
+  label="Supplies"
+  hide-label
+  placeholder="Add supplies…"
+  :options="[
+    { value: 'pen', label: 'Pen' },
+    { value: 'pencil', label: 'Pencil' },
+    { value: 'marker', label: 'Marker' },
+    { value: 'eraser', label: 'Eraser' },
+  ]"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+## Accessibility
+
+MultiSelect is built on reka-ui's Combobox, which implements the
+[ARIA combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/):
+
+- The text field has `role="combobox"` with `aria-expanded`, `aria-controls`,
+  `aria-autocomplete="list"`, and `aria-activedescendant` tracking the
+  highlighted option as you arrow through the list.
+- The popup is a `role="listbox"` with `aria-multiselectable="true"`; each option
+  is a `role="option"` and reflects its state via `aria-selected`.
+- Keyboard support is handled for you: type to filter, ↑/↓ to move, Enter to
+  toggle the highlighted option, Escape to close, and Backspace in an empty input
+  removes the last chip.
+- Pass `label` so the field is named by a real `<label>` (associated via
+  `aria-labelledby`); use `hide-label` to keep it for screen readers while hiding
+  it visually, or `aria-label` when there's no visible label text.
+- Each chip's remove button has an `aria-label` (e.g. "Remove California").
+
+<!--@include: ./_api/multi-select.md-->
+
+### MultiSelectOption
+
+```ts
+interface MultiSelectOption {
+  value: string;
+  label: string;
+}
+```