@cfasim-ui/components 0.7.7 → 0.8.0

package/docs/Expander.md

@@ -0,0 +1,34 @@
+# Expander
+
+A collapsible section that toggles content visibility.
+
+## Examples
+
+<ComponentDemo>
+  <Expander label="Show advanced options">
+    <p style="margin: 0">Here is the hidden content.</p>
+  </Expander>
+
+<template #code>
+
+```vue
+<Expander label="Show advanced options">
+  <p>Here is the hidden content.</p>
+</Expander>
+```
+
+  </template>
+</ComponentDemo>
+
+## Model
+
+| Name | Type |
+|------|------|
+| `v-model:open` | `boolean` |
+
+## Props
+
+| Prop | Type | Required | Default |
+|------|------|----------|---------|
+| `label` | `string` | No | — |
+

package/docs/Grid.md

@@ -0,0 +1,170 @@
+# Grid
+
+A CSS-grid wrapper for arranging elements in equal, proportional, or auto-fitting columns.
+
+For single-direction stacks (vertical or a flex row that wraps), use [Container](./container) instead.
+
+## Examples
+
+### Equal columns
+
+Pass a number for N equal-width columns.
+
+<ComponentDemo>
+  <Grid :cols="3" gap="medium">
+    <Box variant="info">Column 1</Box>
+    <Box variant="info">Column 2</Box>
+    <Box variant="info">Column 3</Box>
+  </Grid>
+
+<template #code>
+
+```vue
+<Grid :cols="3" gap="medium">
+  <Box variant="info">Column 1</Box>
+  <Box variant="info">Column 2</Box>
+  <Box variant="info">Column 3</Box>
+</Grid>
+```
+
+  </template>
+</ComponentDemo>
+
+### Proportional widths
+
+Pass an array of `fr` weights for asymmetric layouts.
+
+<ComponentDemo>
+  <Grid :cols="[2, 3, 1]" gap="medium">
+    <Box variant="info">2fr</Box>
+    <Box variant="success">3fr</Box>
+    <Box variant="warning">1fr</Box>
+  </Grid>
+
+<template #code>
+
+```vue
+<Grid :cols="[2, 3, 1]" gap="medium">
+  <Box variant="info">2fr</Box>
+  <Box variant="success">3fr</Box>
+  <Box variant="warning">1fr</Box>
+</Grid>
+```
+
+  </template>
+</ComponentDemo>
+
+### Mixed track sizes
+
+Strings pass through unchanged, so you can combine fixed and flexible tracks.
+
+<ComponentDemo>
+  <Grid :cols="['200px', '1fr']" gap="medium">
+    <Box variant="info">Fixed 200px</Box>
+    <Box variant="info">Fills remaining space</Box>
+  </Grid>
+
+<template #code>
+
+```vue
+<Grid :cols="['200px', '1fr']" gap="medium">
+  <Box variant="info">Fixed 200px</Box>
+  <Box variant="info">Fills remaining space</Box>
+</Grid>
+```
+
+  </template>
+</ComponentDemo>
+
+### Small-width breakpoint
+
+`colsSmall` overrides `cols` when the grid's own width is at or below `breakpoint`. The default breakpoint is `640px` unless you specify it. The check is a CSS container query against the grid itself, so it triggers based on the grid's available width (e.g. when nested inside a sidebar), not the viewport.
+
+<ComponentDemo>
+  <Grid :cols="3" :cols-small="1" breakpoint="480px" gap="small">
+    <Box variant="info">Card 1</Box>
+    <Box variant="info">Card 2</Box>
+    <Box variant="info">Card 3</Box>
+  </Grid>
+
+<template #code>
+
+```vue
+<Grid :cols="3" :cols-small="1" breakpoint="480px" gap="small">
+  <Box variant="info">Card 1</Box>
+  <Box variant="info">Card 2</Box>
+  <Box variant="info">Card 3</Box>
+</Grid>
+```
+
+  </template>
+</ComponentDemo>
+
+### Responsive auto-fit
+
+`minColWidth` switches to `repeat(auto-fit, minmax(...))` so items reflow to fit the viewport without media queries. Great for metric tiles and card grids.
+
+<ComponentDemo>
+  <Grid min-col-width="180px" gap="medium">
+    <Box variant="info">Card 1</Box>
+    <Box variant="info">Card 2</Box>
+    <Box variant="info">Card 3</Box>
+    <Box variant="info">Card 4</Box>
+    <Box variant="info">Card 5</Box>
+  </Grid>
+
+<template #code>
+
+```vue
+<Grid min-col-width="180px" gap="medium">
+  <Box variant="info">Card 1</Box>
+  <Box variant="info">Card 2</Box>
+  <Box variant="info">Card 3</Box>
+  <Box variant="info">Card 4</Box>
+  <Box variant="info">Card 5</Box>
+</Grid>
+```
+
+  </template>
+</ComponentDemo>
+
+### Nested grids
+
+<ComponentDemo>
+  <Grid :cols="2" gap="medium">
+    <Box variant="info">Left</Box>
+    <Grid :cols="2" gap="small">
+      <Box variant="success">a</Box>
+      <Box variant="success">b</Box>
+      <Box variant="success">c</Box>
+      <Box variant="success">d</Box>
+    </Grid>
+  </Grid>
+
+<template #code>
+
+```vue
+<Grid :cols="2" gap="medium">
+  <Box variant="info">Left</Box>
+  <Grid :cols="2" gap="small">
+    <Box variant="success">a</Box>
+    <Box variant="success">b</Box>
+    <Box variant="success">c</Box>
+    <Box variant="success">d</Box>
+  </Grid>
+</Grid>
+```
+
+  </template>
+</ComponentDemo>
+
+## Props
+
+| Prop | Type | Required | Default |
+|------|------|----------|---------|
+| `cols` | `GridCols` | No | — |
+| `colsSmall` | `GridCols` | No | — |
+| `breakpoint` | `string` | No | — |
+| `gap` | `GridGap \| string` | No | — |
+| `minColWidth` | `string` | No | — |
+

package/docs/Hint.md

@@ -0,0 +1,29 @@
+# Hint
+
+An info icon that shows a tooltip on hover. Used alongside form labels to provide additional context.
+
+## Examples
+
+<ComponentDemo>
+  <span style="display: flex; align-items: center; gap: 8px;">
+    Population size <Hint text="The total number of individuals in the simulation." />
+  </span>
+
+<template #code>
+
+```vue
+<span style="display: flex; align-items: center; gap: 8px;">
+  Population size
+  <Hint text="The total number of individuals in the simulation." />
+</span>
+```
+
+  </template>
+</ComponentDemo>
+
+## Props
+
+| Prop | Type | Required | Default |
+|------|------|----------|---------|
+| `text` | `string` | Yes | — |
+

package/docs/Icon.md

@@ -0,0 +1,188 @@
+# 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.
+
+## Props
+
+| Prop | Type | Required | Default |
+|------|------|----------|---------|
+| `icon` | `string` | Yes | — |
+| `size` | `IconSize \| number` | No | `"md"` |
+| `fill` | `boolean` | No | `false` |
+| `weight` | `number` | No | — |
+| `grade` | `number` | No | — |
+| `decorative` | `boolean` | No | `true` |
+| `ariaLabel` | `string` | No | — |
+| `inline` | `boolean` | No | `false` |
+

package/docs/MultiSelect.md

@@ -0,0 +1,143 @@
+# 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").
+
+## Model
+
+| Name | Type |
+|------|------|
+| `v-model` | `string[]` |
+
+## Props
+
+| Prop | Type | Required | Default |
+|------|------|----------|---------|
+| `label` | `string` | No | — |
+| `hideLabel` | `boolean` | No | — |
+| `ariaLabel` | `string` | No | — |
+| `hint` | `string` | No | — |
+| `options` | `MultiSelectOption[]` | Yes | — |
+| `placeholder` | `string` | No | — |
+
+
+### MultiSelectOption
+
+```ts
+interface MultiSelectOption {
+  value: string;
+  label: string;
+}
+```