@cfasim-ui/docs 0.6.0 → 0.6.2

package/charts/ChoroplethMap/ChoroplethMap.md

@@ -258,6 +258,8 @@ Use an array of `CategoricalStop` objects to map string values to colors. Each s
 
 Set `geoType="counties"` to render county-level data using 5-digit FIPS codes. State borders are drawn on top for context. Use `pan` and `zoom` props to enable interactive navigation — useful for dense county data.
 
+On touch devices, add `two-finger-pan` so a single finger scrolls the page (the map sets `touch-action: pan-y`) and two fingers pan/pinch-zoom the map — tap-to-select still works with one finger.
+
 <ComponentDemo>
   <ChoroplethMap
     :topology="countiesTopo"
@@ -356,6 +358,58 @@ Set `geoType="hsas"` to render Health Service Area boundaries. HSAs are dissolve
   </template>
 </ComponentDemo>
 
+### Single-state map (`state`)
+
+Set the `state` prop to render just one state's outline with its `counties` or
+`hsas` inside it — no surrounding states — and the projection zooms to fit it.
+Accepts a state **name** (`"California"`) or a 2-digit **FIPS code** (`"06"`).
+This needs a counties topology (the same `us-atlas/counties-10m.json`). `data`
+can stay national; only features inside the selected state are drawn and
+colored.
+
+<ComponentDemo>
+  <ChoroplethMap
+    :topology="countiesTopo"
+    geo-type="counties"
+    state="California"
+    :data="[
+      { id: '06037', value: 100 },
+      { id: '06073', value: 80 },
+      { id: '06059', value: 65 },
+      { id: '06065', value: 55 },
+      { id: '06001', value: 45 },
+      { id: '06085', value: 40 },
+    ]"
+    title="California cases by county"
+    :legend-title="'Cases'"
+    :height="400"
+  />
+
+<template #code>
+
+```vue
+<ChoroplethMap
+  :topology="countiesTopo"
+  geo-type="counties"
+  state="California"
+  :data="[
+    { id: '06037', value: 100 }, // Los Angeles
+    { id: '06073', value: 80 }, // San Diego
+    { id: '06059', value: 65 }, // Orange
+  ]"
+  title="California cases by county"
+  :legend-title="'Cases'"
+  :height="400"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+Switch `geo-type="hsas"` to fill the same state with Health Service Areas
+instead. An unrecognized `state` value logs a warning and falls back to the
+full national map.
+
 ### Click to focus (`v-model:focus`)
 
 Bind the `focus` prop to pan and zoom to a specific feature. Pass a feature
@@ -365,6 +419,10 @@ the focused feature toggles back off. If a tooltip is configured, focusing
 shows that feature's tooltip. Users can pan/zoom freely around the focused
 area; the built-in **Reset** button clears focus and snaps back.
 
+Set `:focus-zoom="false"` to highlight (and draw cross-geoType overlays)
+**without** panning or zooming — useful for a click-to-select interaction
+where the map should stay put while a side panel shows the details.
+
 Selection works on touch too: a single-finger **tap** on a feature emits
 `stateClick` and toggles focus, while drags (pan) and pinches (zoom) are left
 to the map. Hover tooltips stay off on touch for performance.
@@ -695,6 +753,7 @@ set `tooltip-trigger`.
 | `data` | `StateData[]` | No | — |
 | `geoType` | `GeoType` | No | `"states"` |
 | `dataGeoType` | `GeoType` | No | — |
+| `state` | `string` | No | — |
 | `width` | `number` | No | — |
 | `height` | `number` | No | — |
 | `colorScale` | `ChoroplethColorScale \| ThresholdStop[] \| CategoricalStop[]` | No | — |
@@ -709,6 +768,7 @@ set `tooltip-trigger`.
 | `legendTitle` | `string` | No | — |
 | `zoom` | `boolean` | No | `false` |
 | `pan` | `boolean` | No | `false` |
+| `twoFingerPan` | `boolean` | No | `false` |
 | `tooltipTrigger` | `"hover" \| "click"` | No | — |
 | `tooltipFormat` | `(data: {
       id: string` | No | — |
@@ -718,6 +778,7 @@ set `tooltip-trigger`.
 | `tooltipClamp` | `"none" \| "chart" \| "window"` | No | `"chart"` |
 | `focus` | `FocusValue` | No | — |
 | `focusZoomLevel` | `number` | No | `4` |
+| `focusZoom` | `boolean` | No | `true` |
 | `fullscreenTarget` | `string \| HTMLElement` | No | — |
 
 

package/charts/ChoroplethMap/ChoroplethMap.vue

@@ -8,7 +8,7 @@ import {
   toRaw,
   useSlots,
 } from "vue";
-import { geoPath, geoAlbersUsa } from "d3-geo";
+import { geoPath, geoAlbersUsa, geoMercator } from "d3-geo";
 import { zoom as d3Zoom, zoomIdentity } from "d3-zoom";
 import { select } from "d3-selection";
 // Side-effect import: enables `selection.transition()` on d3 selections so
@@ -107,6 +107,15 @@ const props = withDefaults(
      * When unset, data ids must match the base `geoType`.
      */
     dataGeoType?: GeoType;
+    /**
+     * Scope the map to a single state: render only that state's outline with
+     * its `counties` or `hsas` inside it (no surrounding states), and refit
+     * the projection to zoom to it. Accepts a state name ("California") or a
+     * 2-digit FIPS code ("06"). Requires a counties topology when `geoType`
+     * is `"counties"` or `"hsas"`. If the value matches no state, the full
+     * national map is rendered and a warning is logged.
+     */
+    state?: string;
     width?: number;
     height?: number;
     colorScale?: ChoroplethColorScale | ThresholdStop[] | CategoricalStop[];
@@ -131,6 +140,14 @@ const props = withDefaults(
     zoom?: boolean;
     /** Enable click-and-drag panning. Default: false */
     pan?: boolean;
+    /**
+     * Require two fingers to pan/zoom on touch devices. Default `false`.
+     * When `true`, a single finger scrolls the page (the map sets
+     * `touch-action: pan-y` and ignores one-finger drags) while two fingers
+     * pan and pinch-zoom the map. Single-finger tap-to-select still works.
+     * Has no effect with a mouse.
+     */
+    twoFingerPan?: boolean;
     /** Tooltip activation mode */
     tooltipTrigger?: "hover" | "click";
     /**
@@ -174,6 +191,14 @@ const props = withDefaults(
     focus?: FocusValue;
     /** Scale factor applied when `focus` is set. Default: 4 */
     focusZoomLevel?: number;
+    /**
+     * Whether setting `focus` pans/zooms to fit the focused feature.
+     * Default `true`. Set `false` to highlight (and draw cross-geoType
+     * overlays) without changing the current pan/zoom — useful for a
+     * click-to-select interaction where the map should stay put. The
+     * built-in Reset button is unaffected.
+     */
+    focusZoom?: boolean;
     /**
      * Where to teleport the map while expanded (the Expand menu item). A
      * CSS selector or element; defaults to `body`. Moving it to the
@@ -193,8 +218,10 @@ const props = withDefaults(
     legend: true,
     zoom: false,
     pan: false,
+    twoFingerPan: false,
     tooltipClamp: "chart",
     focusZoomLevel: 4,
+    focusZoom: true,
   },
 );
 
@@ -425,16 +452,28 @@ function setupZoom() {
   // Dynamic filter: re-evaluated per event, so toggling `focus`,
   // `zoom`, or `pan` doesn't require tearing down the zoom behavior.
   // When focus is active we always allow drag + wheel so users can
-  // explore away from the focused area regardless of `zoom`/`pan`.
+  // explore away from the focused area regardless of `zoom`/`pan` — but
+  // not in highlight-only mode (`focusZoom=false`), where focus is purely
+  // visual and shouldn't grant interaction the props didn't ask for.
   // Programmatic `.transform()` calls bypass this filter entirely.
   zoomBehavior.filter((event) => {
-    const focused = normalizedFocus.value.length > 0;
+    const focused =
+      normalizedFocus.value.length > 0 && props.focusZoom !== false;
     const allowZoom = !!props.zoom || focused;
     const allowPan = !!props.pan || focused;
     if (event.type === "wheel" || event.type === "dblclick") {
       if (!allowZoom) return false;
     } else if (event.type === "mousedown" || event.type === "touchstart") {
       if (!allowPan) return false;
+      // Two-finger-only mode: ignore single-finger touches so the page can
+      // scroll; a second finger drives the map (pan + pinch-zoom).
+      if (
+        props.twoFingerPan &&
+        event.type === "touchstart" &&
+        (event as TouchEvent).touches.length < 2
+      ) {
+        return false;
+      }
     } else if (!allowZoom && !allowPan) {
       return false;
     }
@@ -541,6 +580,13 @@ function applyFocus() {
     return;
   }
 
+  // Highlight-only mode: the strokes + overlays above are applied; skip the
+  // pan/zoom transform so the current view stays put (click-to-select).
+  if (props.focusZoom === false) {
+    focusApplied = true;
+    return;
+  }
+
   const svg = select(svgRef.value);
   // Always cancel any in-flight transition first — d3-transition queues
   // same-named transitions rather than replacing them, so rapid focus
@@ -667,6 +713,19 @@ watch(
   },
 );
 
+// Switching the scoped `state` refits the projection to a different region,
+// so any leftover pan/zoom transform would leave the new map off-center.
+// Reset it instantly (no animation) when the region changes.
+watch(
+  () => props.state,
+  () => {
+    if (!svgRef.value || !zoomBehavior) return;
+    const svg = select(svgRef.value);
+    svg.interrupt();
+    zoomBehavior.transform(svg, zoomIdentity);
+  },
+);
+
 // Canonical internal coordinate system. All layout (projection, legend,
 // title) is computed at this size; the SVG's viewBox makes the browser
 // scale the entire canvas to whatever the container provides, so there's no
@@ -692,6 +751,58 @@ type CountiesTopo = Topology<{
   states: NamedGeometry;
 }>;
 
+type StateFeature = GeoJSON.Feature<GeoJSON.Geometry | null, { name?: string }>;
+
+// ─── Single-state scoping (`state` prop) ─────────────────────────────────
+//
+// Resolved directly from the topology's `states` object (not from
+// featuresByGeoType) so it stays free of the featuresGeo → featuresById →
+// featuresByGeoType chain — that chain reads `stateFips`, so depending on it
+// here would form a reactive cycle.
+const statesFeatures = computed<StateFeature[]>(() => {
+  const topo = toRaw(props.topology) as unknown as {
+    objects?: { states?: NamedGeometry };
+  };
+  const statesObj = topo?.objects?.states;
+  if (!statesObj) return [];
+  const fc = feature(topo as unknown as Topology, statesObj) as
+    | GeoJSON.FeatureCollection<GeoJSON.Geometry | null, { name?: string }>
+    | StateFeature;
+  return fc.type === "FeatureCollection" ? fc.features : [fc];
+});
+
+// 2-digit FIPS for the active `state` prop, or null when unset/unresolved.
+const stateFips = computed<string | null>(() => {
+  const s = props.state?.trim();
+  if (!s) return null;
+  if (/^\d{1,2}$/.test(s)) return s.padStart(2, "0");
+  const match = statesFeatures.value.find((f) => f.properties?.name === s);
+  return match?.id != null ? String(match.id).padStart(2, "0") : null;
+});
+
+// The single state's GeoJSON feature — drives the outline path and the
+// projection fit in single-state mode.
+const stateOutlineFeature = computed<StateFeature | null>(() => {
+  const fips = stateFips.value;
+  if (!fips) return null;
+  return (
+    statesFeatures.value.find((f) => String(f.id).padStart(2, "0") === fips) ??
+    null
+  );
+});
+
+watch(
+  () => [props.state, stateFips.value] as const,
+  ([state, fips]) => {
+    if (state && state.trim() && !fips) {
+      console.warn(
+        `[ChoroplethMap] state="${state}" matched no state name or FIPS code; rendering the full map.`,
+      );
+    }
+  },
+  { immediate: true },
+);
+
 // HSA mapping is loaded lazily — it's ~25KB gzipped and only needed when
 // geoType or dataGeoType is "hsas". Keeps the main bundle small for users
 // who only need states/counties maps.
@@ -727,10 +838,14 @@ const hsaFeaturesGeo = computed(() => {
   const { fipsToHsa, hsaNames } = mod;
   const topo = toRaw(props.topology) as unknown as CountiesTopo;
   const countyGeometries = topo.objects.counties.geometries;
+  const scopeFips = stateFips.value;
   const groups = new Map<string, typeof countyGeometries>();
 
   for (const geom of countyGeometries) {
     const fips = String(geom.id).padStart(5, "0");
+    // Single-state mode: drop counties outside the state before grouping, so
+    // the resulting HSAs only cover the selected state.
+    if (scopeFips && fips.slice(0, 2) !== scopeFips) continue;
     const hsaCode = fipsToHsa[fips];
     if (!hsaCode) continue;
     if (!groups.has(hsaCode)) groups.set(hsaCode, []);
@@ -751,30 +866,71 @@ const hsaFeaturesGeo = computed(() => {
 });
 
 const featuresGeo = computed(() => {
+  // hsaFeaturesGeo already honors `state` (it scopes the source counties).
   if (props.geoType === "hsas") return hsaFeaturesGeo.value;
+  const scopeFips = stateFips.value;
   if (props.geoType === "counties") {
     const topo = toRaw(props.topology) as unknown as CountiesTopo;
-    return feature(topo, topo.objects.counties);
+    const fc = feature(topo, topo.objects.counties);
+    if (!scopeFips) return fc;
+    return {
+      type: "FeatureCollection" as const,
+      features: fc.features.filter(
+        (f) => String(f.id).padStart(5, "0").slice(0, 2) === scopeFips,
+      ),
+    };
   }
   const topo = toRaw(props.topology) as unknown as StatesTopo;
-  return feature(topo, topo.objects.states);
+  const fc = feature(topo, topo.objects.states);
+  if (!scopeFips) return fc;
+  return {
+    type: "FeatureCollection" as const,
+    features: fc.features.filter(
+      (f) => String(f.id).padStart(2, "0") === scopeFips,
+    ),
+  };
 });
 
 const stateBordersPath = computed(() => {
   if (props.geoType !== "counties" && props.geoType !== "hsas") return null;
+  // Single-state mode: trace just the selected state's outline instead of
+  // the full national state-border mesh.
+  if (stateFips.value) return stateOutlineFeature.value;
   const topo = toRaw(props.topology) as unknown as CountiesTopo;
   return mesh(topo, topo.objects.states, (a, b) => a !== b);
 });
 
-const projection = computed(() =>
-  geoAlbersUsa().fitExtent(
+// Breathing room (canonical px) around a single state so its outline isn't
+// flush against the SVG edge. Only applied in single-state mode.
+const STATE_FIT_INSET = 12;
+
+const projection = computed(() => {
+  const outline = stateOutlineFeature.value;
+  if (stateFips.value && outline) {
+    const extent: [[number, number], [number, number]] = [
+      [STATE_FIT_INSET, STATE_FIT_INSET],
+      [width.value - STATE_FIT_INSET, height.value - STATE_FIT_INSET],
+    ];
+    const albers = geoAlbersUsa().fitExtent(extent, outline);
+    // geoAlbersUsa only covers the 50 states + DC (it handles Alaska and
+    // Hawaii via insets). The island territories — Puerto Rico, Guam, the
+    // US Virgin Islands, American Samoa, the N. Mariana Islands — fall
+    // outside it and project to null, so fitExtent yields a NaN transform
+    // and every path renders as "MNaN,NaN…". Detect that by projecting the
+    // outline's centroid and fall back to a plain Mercator that can render
+    // any region.
+    const c = geoPath(albers).centroid(outline);
+    if (Number.isFinite(c[0]) && Number.isFinite(c[1])) return albers;
+    return geoMercator().fitExtent(extent, outline);
+  }
+  return geoAlbersUsa().fitExtent(
     [
       [0, 0],
       [width.value, height.value],
     ],
     featuresGeo.value,
-  ),
-);
+  );
+});
 
 const pathGenerator = computed(() => geoPath(projection.value));
 
@@ -1481,9 +1637,12 @@ const menuItems = computed<ChartMenuItem[]>(() => {
 // Registered last so the eagerly-evaluated source getters can read every
 // computed defined above without hitting a TDZ.
 
-// Geometry / projection / tooltip-mode → full rebuild.
+// Geometry / projection / tooltip-mode → full rebuild. `featuresGeo` is
+// watched explicitly because in single-state mode the projection is pinned
+// to the static state outline, so an async change to the feature set (e.g.
+// the lazy HSA module resolving) wouldn't otherwise change `pathGenerator`.
 watch(
-  () => [pathGenerator.value, hasInteractiveTooltip.value],
+  () => [featuresGeo.value, pathGenerator.value, hasInteractiveTooltip.value],
   () => rebuildPaths(),
 );
 
@@ -1596,6 +1755,7 @@ watch(
         ref="svgRef"
         :viewBox="`0 0 ${width} ${height}`"
         preserveAspectRatio="xMidYMid meet"
+        :style="twoFingerPan ? { touchAction: 'pan-y' } : undefined"
       >
         <!--
         Path elements are created imperatively in `rebuildPaths()`; Vue never

package/charts/LineChart/LineChart.md

@@ -180,6 +180,68 @@ grows automatically for additional lines.
   </template>
 </ComponentDemo>
 
+### Font sizes
+
+Every text element on the chart has its own style prop and default size (in px). The text-styling props (`axisLabelStyle`, `tickLabelStyle`, `legendStyle`) take a `LabelStyle` — `{ fontSize?, color?, fontWeight? }` — and `titleStyle` adds `lineHeight` and `align`. Unset fields fall back to the defaults below.
+
+| Chart part                                  | Prop / field                         | Type         | Default size |
+| ------------------------------------------- | ------------------------------------ | ------------ | -----------: |
+| Title                                       | `titleStyle`                         | `TitleStyle` |           14 |
+| Axis labels (`xLabel` / `yLabel`)           | `axisLabelStyle`                     | `LabelStyle` |           13 |
+| Axis tick labels (the numbers on each axis) | `tickLabelStyle`                     | `LabelStyle` |           10 |
+| Inline legend                               | `legendStyle`                        | `LabelStyle` |           11 |
+| Area section label                          | `areaSection.inlineLabelStyle`       | `LabelStyle` |           11 |
+| Area section description                    | `areaSection.inlineDescriptionStyle` | `LabelStyle` |           11 |
+| Annotation text                             | `annotation.fontSize`                | `number`     |           13 |
+
+These are single styles applied to both axes — there's no separate x vs y font size. The same props (except the LineChart-only area-section fields) exist on `BarChart`, since both compose `ChartCommonProps`.
+
+<ComponentDemo>
+  <LineChart
+    :series="[
+      { data: [0, 12, 28, 45, 60, 55, 40, 25, 12], color: '#0057b7', legend: 'No interventions' },
+      { data: [0, 8, 18, 30, 40, 35, 25, 14, 6], color: '#ef4444', legend: 'Masking + distancing' },
+    ]"
+    :height="240"
+    title="Daily ED visits"
+    x-label="Days"
+    y-label="Cases"
+    :title-style="{ fontSize: 18 }"
+    :axis-label-style="{ fontSize: 15, fontWeight: 700 }"
+    :tick-label-style="{ fontSize: 13 }"
+    :legend-style="{ fontSize: 14 }"
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :series="[
+    {
+      data: [0, 12, 28, 45, 60, 55, 40, 25, 12],
+      color: '#0057b7',
+      legend: 'No interventions',
+    },
+    {
+      data: [0, 8, 18, 30, 40, 35, 25, 14, 6],
+      color: '#ef4444',
+      legend: 'Masking + distancing',
+    },
+  ]"
+  :height="240"
+  title="Daily ED visits"
+  x-label="Days"
+  y-label="Cases"
+  :title-style="{ fontSize: 18 }"
+  :axis-label-style="{ fontSize: 15, fontWeight: 700 }"
+  :tick-label-style="{ fontSize: 13 }"
+  :legend-style="{ fontSize: 14 }"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Multiple series
 
 <ComponentDemo>
@@ -628,7 +690,9 @@ inverts. The white `outline`, if any, is unaffected.
 Use the `areas` prop to fill a band between two y-series — useful for
 confidence intervals or min/max envelopes around a mean line. Each `Area`
 takes parallel `upper` and `lower` arrays (and an optional `x` array, just
-like `Series`).
+like `Series`). Set `blendMode` on an `Area` to apply a CSS
+`mix-blend-mode` to its fill so overlapping bands combine their colors
+(e.g. `"multiply"`) instead of the later one obscuring the earlier.
 
 <ComponentDemo>
   <LineChart
@@ -1103,6 +1167,7 @@ interface Area {
   x?: LineChartData; // optional parallel x-values
   color?: string;
   opacity?: number;
+  blendMode?: BlendMode; // CSS mix-blend-mode for the fill
 }
 ```
 

package/charts/LineChart/LineChart.vue

@@ -114,6 +114,12 @@ export interface Area {
   x?: LineChartXInput;
   color?: string;
   opacity?: number;
+  /**
+   * CSS `mix-blend-mode` applied to the area fill. Lets overlapping
+   * areas (e.g. confidence bands) combine their colors instead of one
+   * obscuring the other.
+   */
+  blendMode?: BlendMode;
 }
 
 export interface AreaSection {
@@ -1218,6 +1224,7 @@ const positionedLegendItems = computed(() => {
           :fill="a.color ?? 'currentColor'"
           :fill-opacity="a.opacity ?? 0.2"
           stroke="none"
+          :style="a.blendMode ? { mixBlendMode: a.blendMode } : undefined"
         />
         <!-- data lines and dots -->
         <template v-for="(s, i) in allSeries" :key="i">

package/components/SelectBox/SelectBox.md

@@ -1,12 +1,15 @@
 # SelectBox
 
-A dropdown select built on reka-ui.
+A single-select dropdown built on reka-ui. Set `autocomplete` to turn it into a
+filterable single-select combobox: type to narrow the options, just like
+[MultiSelect](./multi-select) but bound to a single `string`.
 
 ## Examples
 
 <script setup>
 import { ref } from 'vue'
 const interval = ref('weekly')
+const state = ref('')
 </script>
 
 <ComponentDemo>
@@ -83,6 +86,73 @@ DOM.
   </template>
 </ComponentDemo>
 
+### Autocomplete
+
+Add `autocomplete` to make the field filterable. Type to narrow the list; the
+selected option's label fills the input. `v-model` is still a single `string`.
+
+<ComponentDemo>
+  <div style="width: 240px">
+    <SelectBox
+      v-model="state"
+      autocomplete
+      label="State"
+      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 state = ref("");
+</script>
+
+<SelectBox
+  v-model="state"
+  autocomplete
+  label="State"
+  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>
+
+## Accessibility
+
+In the default mode the field is a reka-ui Select; with `autocomplete` it's a
+reka-ui Combobox following the
+[ARIA combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/):
+
+- The input has `role="combobox"` with `aria-expanded`, `aria-controls`, and
+  `aria-autocomplete="list"`; the popup is a `role="listbox"` and each option a
+  `role="option"` that reflects its state via `aria-selected`.
+- Keyboard support is handled for you: type to filter, ↑/↓ to move through the
+  list, Enter to select the highlighted option, and Escape to close.
+- Pass `label` so the field is named by a real `<label>`. In autocomplete mode
+  the label is also wired to the input via `for`/`id`, so clicking it focuses
+  the field; use `hide-label` to keep the label for screen readers while hiding
+  it visually, or `aria-label` when there's no visible label text.
+- The chevron is a labelled toggle (`aria-label="Toggle options"`) kept out of
+  the tab order, and native browser autofill is disabled so it can't cover the
+  option list.
+
 ## Model
 
 | Name | Type |
@@ -98,6 +168,7 @@ DOM.
 | `ariaLabel` | `string` | No | — |
 | `options` | `SelectOption[]` | Yes | — |
 | `placeholder` | `string` | No | — |
+| `autocomplete` | `boolean` | No | — |
 
 
 ### SelectOption

package/components/SelectBox/SelectBox.vue

@@ -1,5 +1,15 @@
 <script setup lang="ts">
 import {
+  ComboboxAnchor,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxItemIndicator,
+  ComboboxPortal,
+  ComboboxRoot,
+  ComboboxTrigger,
+  ComboboxViewport,
   SelectContent,
   SelectItem,
   SelectItemIndicator,
@@ -25,9 +35,16 @@ const props = defineProps<{
   ariaLabel?: string;
   options: SelectOption[];
   placeholder?: string;
+  /** Turn the field into a filterable single-select autocomplete (combobox). */
+  autocomplete?: boolean;
 }>();
 
 const id = useId();
+
+// Shows the selected option's label in the combobox input when not filtering.
+function displayValue(value: string) {
+  return props.options.find((o) => o.value === value)?.label ?? "";
+}
 </script>
 
 <template>
@@ -35,11 +52,81 @@ const id = useId();
     <label
       v-if="label"
       :id="`${id}-label`"
+      :for="autocomplete ? `${id}-input` : undefined"
       class="select-label"
       :class="{ 'visually-hidden': hideLabel }"
       >{{ label }}</label
     >
-    <SelectRoot v-model="model">
+
+    <ComboboxRoot
+      v-if="autocomplete"
+      v-model="model"
+      open-on-click
+      class="select-combobox-root"
+    >
+      <ComboboxAnchor class="select-anchor">
+        <ComboboxInput
+          :id="`${id}-input`"
+          class="select-input"
+          :display-value="displayValue"
+          :placeholder="placeholder"
+          :aria-labelledby="props.label ? `${id}-label` : undefined"
+          :aria-label="!props.label ? props.ariaLabel : undefined"
+        />
+        <ComboboxTrigger class="select-icon-button" aria-label="Toggle options">
+          <span class="select-icon" aria-hidden="true">
+            <svg
+              width="12"
+              height="12"
+              viewBox="0 0 12 12"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+            >
+              <path d="M3 4.5L6 7.5L9 4.5" />
+            </svg>
+          </span>
+        </ComboboxTrigger>
+      </ComboboxAnchor>
+      <ComboboxPortal>
+        <ComboboxContent
+          class="select-content select-content-autocomplete"
+          position="popper"
+          :side-offset="4"
+          :body-lock="false"
+        >
+          <ComboboxViewport class="select-viewport">
+            <ComboboxEmpty class="select-empty">No matches</ComboboxEmpty>
+            <ComboboxItem
+              v-for="opt in options"
+              :key="opt.value"
+              :value="opt.value"
+              class="select-item"
+            >
+              <span>{{ opt.label }}</span>
+              <ComboboxItemIndicator class="select-indicator">
+                <svg
+                  width="12"
+                  height="12"
+                  viewBox="0 0 12 12"
+                  fill="none"
+                  stroke="currentColor"
+                  stroke-width="2"
+                  stroke-linecap="round"
+                  stroke-linejoin="round"
+                >
+                  <path d="M2 6L5 9L10 3" />
+                </svg>
+              </ComboboxItemIndicator>
+            </ComboboxItem>
+          </ComboboxViewport>
+        </ComboboxContent>
+      </ComboboxPortal>
+    </ComboboxRoot>
+
+    <SelectRoot v-else v-model="model">
       <SelectTrigger
         class="select-trigger"
         :aria-labelledby="props.label ? `${id}-label` : undefined"
@@ -140,6 +227,62 @@ const id = useId();
   color: var(--color-text-secondary);
 }
 
+/* Autocomplete (combobox) field */
+.select-anchor {
+  display: flex;
+  align-items: center;
+  gap: 0.5em;
+  height: 2.5em;
+  padding: 0 0.5em 0 0.75em;
+  font-size: var(--font-size-sm);
+  background: var(--color-bg-0);
+  border: 1px solid var(--color-border);
+  border-radius: 0.375em;
+  transition:
+    border-color var(--transition-fast),
+    box-shadow var(--transition-fast);
+}
+
+.select-anchor:hover {
+  border-color: var(--color-border-hover);
+}
+
+.select-anchor:focus-within {
+  outline: none;
+  border-color: var(--color-border-focus);
+  box-shadow: var(--shadow-focus);
+}
+
+.select-input {
+  flex: 1;
+  min-width: 0;
+  height: 100%;
+  padding: 0;
+  border: none;
+  background: none;
+  color: inherit;
+  font: inherit;
+}
+
+.select-input:focus {
+  outline: none;
+}
+
+.select-input::placeholder {
+  color: var(--color-text-secondary);
+}
+
+.select-icon-button {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  color: inherit;
+  cursor: pointer;
+}
+
 .select-icon {
   display: flex;
   align-items: center;
@@ -160,10 +303,23 @@ const id = useId();
   max-height: var(--reka-select-content-available-height);
 }
 
+/* Combobox exposes the anchor width under its own custom property. */
+.select-content-autocomplete {
+  width: var(--reka-combobox-trigger-width);
+  max-height: var(--reka-combobox-content-available-height);
+}
+
 .select-viewport {
   padding: 0.25em;
 }
 
+.select-empty {
+  padding: 0.5em;
+  font-size: var(--font-size-sm);
+  color: var(--color-text-secondary);
+  text-align: center;
+}
+
 .select-item {
   display: flex;
   align-items: center;

package/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0",
+  "version": "0.6.2",
   "package": "@cfasim-ui/docs",
   "content": {
     "components": [
@@ -136,7 +136,15 @@
         "slug": "select-box",
         "docs": "components/SelectBox/SelectBox.md",
         "source": "components/SelectBox/SelectBox.vue",
-        "keywords": []
+        "keywords": [
+          "select",
+          "dropdown",
+          "autocomplete",
+          "combobox",
+          "filter",
+          "search",
+          "typeahead"
+        ]
       },
       {
         "name": "SidebarLayout",

package/package.json

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