@cascivo/mcp 0.1.8 → 0.3.3

package/dist/context/chart/funnel.md

@@ -0,0 +1,87 @@
+# Funnel
+
+**Category:** chart  
+**Description:** Vertical conversion funnel — each stage is a trapezoid narrowing toward the next, with optional conversion labels.
+
+## When to use
+
+- Showing drop-off across the ordered stages of a process (signup, checkout)
+- Communicating stage-to-stage conversion at a glance
+
+## When NOT to use
+
+- Stages are not strictly decreasing — use BarChart
+- Showing a trend over time — use LineChart
+
+## Related components
+
+- **BarChart** (alternative): Use when stages aren’t monotonically decreasing
+
+## Accessibility rationale
+
+Renders with role="img" and requires a title prop for screen reader labeling.
+
+## Props
+
+| Name             | Type            | Required | Default | Description                                                |
+| ---------------- | --------------- | -------- | ------- | ---------------------------------------------------------- |
+| `data`           | `FunnelStage[]` | Yes      | —       | Ordered stages (descending): { id, label, value, color? }. |
+| `title`          | `string`        | Yes      | —       | Chart title (also used as aria-label).                     |
+| `description`    | `string`        | No       | —       | Subtitle below the title.                                  |
+| `width`          | `number`        | No       | —       | Width of the component.                                    |
+| `height`         | `number`        | No       | 320     | Height of the component.                                   |
+| `showConversion` | `boolean`       | No       | false   | Append each stage’s % of the first stage to its label.     |
+| `tooltip`        | `boolean`       | No       | —       | Enable hover tooltip.                                      |
+| `className`      | `string`        | No       | —       | Additional CSS class names merged onto the root element.   |
+| `plain`          | `boolean`       | No       | false   | Marks only — no labels. For micro/inline charts.           |
+
+## Tokens
+
+- `--cascivo-chart-1`
+- `--cascivo-chart-2`
+- `--cascivo-chart-3`
+- `--cascivo-chart-4`
+- `--cascivo-chart-5`
+- `--cascivo-chart-6`
+- `--cascivo-chart-7`
+- `--cascivo-chart-8`
+
+## Examples
+
+### Signup conversion funnel
+
+```jsx
+import { Funnel } from '@cascivo/charts'
+;<Funnel
+  title="Signup funnel"
+  showConversion
+  data={[
+    { id: 'visit', label: 'Visited', value: 8200 },
+    { id: 'signup', label: 'Signed up', value: 3100 },
+    { id: 'active', label: 'Activated', value: 1400 },
+    { id: 'paid', label: 'Paid', value: 520 },
+  ]}
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Funnel component (chart). Vertical conversion funnel — each stage is a trapezoid narrowing toward the next, with optional conversion labels.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Funnel is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1, --cascivo-chart-2, --cascivo-chart-3, --cascivo-chart-4, --cascivo-chart-5, --cascivo-chart-6, --cascivo-chart-7, --cascivo-chart-8
+
+Accessibility: role "img", WCAG 2.1-AA, keyboard: Tab (focus chart)/ArrowLeft/ArrowRight (navigate stages)/Escape (clear focus). Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/gauge.md

@@ -0,0 +1,87 @@
+# Gauge
+
+**Category:** chart  
+**Description:** A speedometer gauge — a value arc over a min–max sweep with threshold zones, ticks, and a needle.
+
+## When to use
+
+- A single value against a range with a needle and threshold zones
+- Dashboard KPIs where a speedometer metaphor aids quick reading
+
+## When NOT to use
+
+- Several progress values — use RadialBar
+- A simple bar against thresholds — use Meter
+
+## Related components
+
+- **Meter** (alternative): Use a linear bar for a single value against thresholds
+- **RadialBar** (alternative): Use concentric rings for multiple progress values
+
+## Accessibility rationale
+
+Renders with role="img"; the value and range are in the fallback table.
+
+## Props
+
+| Name          | Type                                | Required | Default | Description                                                |
+| ------------- | ----------------------------------- | -------- | ------- | ---------------------------------------------------------- |
+| `value`       | `number`                            | Yes      | —       | The value the needle points to.                            |
+| `min`         | `number`                            | No       | 0       | Minimum allowed value.                                     |
+| `max`         | `number`                            | No       | 100     | Maximum allowed value.                                     |
+| `thresholds`  | `{ upTo: number; color: string }[]` | No       | —       | Coloured zones from min upward; the last should reach max. |
+| `unit`        | `string`                            | No       | —       | Suffix after the centre value.                             |
+| `sweep`       | `number`                            | No       | 270     | Total sweep angle in degrees (270 = a speedometer arc).    |
+| `ticks`       | `number`                            | No       | 5       | Major tick count.                                          |
+| `title`       | `string`                            | Yes      | —       | Chart title (also aria-label).                             |
+| `description` | `string`                            | No       | —       | Supporting description text.                               |
+| `width`       | `number`                            | No       | —       | Width of the component.                                    |
+| `height`      | `number`                            | No       | 240     | Height of the component.                                   |
+| `className`   | `string`                            | No       | —       | Additional CSS class names merged onto the root element.   |
+| `plain`       | `boolean`                           | No       | false   | Marks only — no ticks/labels. For micro/inline charts.     |
+
+## Tokens
+
+- `--cascivo-color-accent`
+- `--cascivo-color-foreground`
+- `--cascivo-chart-grid`
+
+## Examples
+
+### Speedometer with zones
+
+```jsx
+import { Gauge } from '@cascivo/charts'
+;<Gauge
+  title="CPU load"
+  value={72}
+  unit="%"
+  thresholds={[
+    { upTo: 50, color: 'var(--cascivo-chart-2)' },
+    { upTo: 80, color: 'var(--cascivo-chart-3)' },
+    { upTo: 100, color: 'var(--cascivo-chart-4)' },
+  ]}
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Gauge component (chart). A speedometer gauge — a value arc over a min–max sweep with threshold zones, ticks, and a needle.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Gauge is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-accent, --cascivo-color-foreground, --cascivo-chart-grid
+
+Accessibility: role "img", WCAG 2.1-AA, keyboard: Tab (focus chart). Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/heatmap.md

@@ -0,0 +1,77 @@
+# Heatmap
+
+**Category:** chart  
+**Description:** Two-dimensional heatmap with band scales and color-mix cell interpolation.
+
+## When to use
+
+- Showing magnitude across two categorical dimensions as a color-coded matrix
+- Spotting patterns, clusters, or hotspots in dense grid data
+
+## When NOT to use
+
+- Reading precise values — color encoding is approximate
+- A single-dimension comparison — use BarChart
+
+## Related components
+
+- **Treemap** (alternative): Use for part-to-whole hierarchical magnitude rather than a grid
+
+## Accessibility rationale
+
+Renders with role="img" and requires a title prop for screen reader labeling.
+
+## Props
+
+| Name          | Type                                        | Required | Default | Description                                                                                                               |
+| ------------- | ------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `data`        | `{ x: string; y: string; value: number }[]` | Yes      | —       | Array of x/y/value triples                                                                                                |
+| `title`       | `string`                                    | Yes      | —       | Title text for the component.                                                                                             |
+| `description` | `string`                                    | No       | —       | Supporting description text.                                                                                              |
+| `width`       | `number`                                    | No       | —       | Width of the component.                                                                                                   |
+| `height`      | `number`                                    | No       | 320     | Height of the component.                                                                                                  |
+| `className`   | `string`                                    | No       | —       | Additional CSS class names merged onto the root element.                                                                  |
+| `plain`       | `boolean`                                   | No       | false   | Marks only — no axes, grid lines, or legend. For micro/inline charts.                                                     |
+| `visualMap`   | `VisualMapOptions`                          | No       | —       | Map cell value → CVD-safe colour (continuous or piecewise) via a keyboard-operable legend that filters the visible range. |
+| `toolbox`     | `boolean \| ToolboxOptions`                 | No       | —       | Render a keyboard-reachable toolbox — PNG/SVG export, a data-view table toggle, and restore (reset the visualMap filter). |
+
+## Tokens
+
+- `--cascivo-chart-1`
+- `--cascivo-color-neutral-100`
+
+## Examples
+
+### Basic heatmap
+
+```jsx
+import { Heatmap } from '@cascivo/charts'
+
+const data = [
+  {x:'Mon',y:'AM',value:10},{x:'Mon',y:'PM',value:20},
+  {x:'Tue',y:'AM',value:15},{x:'Tue',y:'PM',value:5},
+]
+<Heatmap data={data} title="Activity" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Heatmap component (chart). Two-dimensional heatmap with band scales and color-mix cell interpolation.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Heatmap is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1, --cascivo-color-neutral-100
+
+Accessibility: role "img", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/histogram.md

@@ -0,0 +1,74 @@
+# Histogram
+
+**Category:** chart  
+**Description:** Frequency histogram using Freedman–Diaconis binning with hover tooltips.
+
+## When to use
+
+- Showing the frequency distribution of a single continuous variable
+- Revealing the shape, spread, and skew of binned numeric data
+
+## When NOT to use
+
+- Comparing discrete labelled categories — use BarChart
+- Comparing distribution summaries across groups — use Boxplot
+
+## Related components
+
+- **BarChart** (alternative): Use for discrete categorical values, not binned ranges
+- **Boxplot** (alternative): Use to compare distribution summaries across multiple groups
+
+## Accessibility rationale
+
+Renders with role="img" and requires a title prop for screen reader labeling.
+
+## Props
+
+| Name          | Type       | Required | Default | Description                                                           |
+| ------------- | ---------- | -------- | ------- | --------------------------------------------------------------------- |
+| `data`        | `number[]` | Yes      | —       | Array of numeric values to bin                                        |
+| `bins`        | `number`   | No       | —       | Explicit bin count (defaults to Freedman–Diaconis)                    |
+| `title`       | `string`   | Yes      | —       | Title text for the component.                                         |
+| `label`       | `string`   | Yes      | —       | X-axis label                                                          |
+| `description` | `string`   | No       | —       | Supporting description text.                                          |
+| `width`       | `number`   | No       | —       | Width of the component.                                               |
+| `height`      | `number`   | No       | 300     | Height of the component.                                              |
+| `className`   | `string`   | No       | —       | Additional CSS class names merged onto the root element.              |
+| `plain`       | `boolean`  | No       | false   | Marks only — no axes, grid lines, or legend. For micro/inline charts. |
+
+## Tokens
+
+- `--cascivo-chart-1`
+
+## Examples
+
+### Basic histogram
+
+```jsx
+import { Histogram } from '@cascivo/charts'
+
+const data = Array.from({length:100}, () => Math.random() * 100)
+<Histogram data={data} title="Distribution" label="Value" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Histogram component (chart). Frequency histogram using Freedman–Diaconis binning with hover tooltips.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Histogram is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1
+
+Accessibility: role "img", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/kpi.md

@@ -0,0 +1,70 @@
+# Kpi
+
+**Category:** chart  
+**Description:** KPI card showing a primary metric with optional delta indicator, icon, and sparkline.
+
+## When to use
+
+- Highlighting a single headline metric with an optional change delta
+- Building dashboard summary tiles with an embedded sparkline trend
+
+## When NOT to use
+
+- Showing a value against a target or range — use Bullet or Meter
+- Comparing multiple values — use a chart
+
+## Related components
+
+- **Sparkline** (contains): Embeds a micro-trend alongside the metric value
+- **Bullet** (alternative): Use when the metric must be shown against a target
+
+## Accessibility rationale
+
+Renders with role="figure" and a labeled metric for screen reader context.
+
+## Props
+
+| Name         | Type               | Required | Default | Description                                              |
+| ------------ | ------------------ | -------- | ------- | -------------------------------------------------------- |
+| `value`      | `string \| number` | Yes      | —       | Primary metric value                                     |
+| `label`      | `string`           | Yes      | —       | Metric label                                             |
+| `delta`      | `number`           | No       | —       | Change value (positive = up, negative = down)            |
+| `deltaLabel` | `string`           | No       | —       | Delta context label (e.g. "vs last week")                |
+| `icon`       | `ReactNode`        | No       | —       | Icon element rendered in the component.                  |
+| `sparkline`  | `number[]`         | No       | —       | Trend data for embedded sparkline                        |
+| `className`  | `string`           | No       | —       | Additional CSS class names merged onto the root element. |
+
+## Tokens
+
+- `--cascivo-chart-1`
+
+## Examples
+
+### Basic KPI card
+
+```jsx
+import { Kpi } from '@cascivo/charts'
+;<Kpi value="$12,400" label="Monthly revenue" delta={8.2} deltaLabel="vs last month" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Kpi component (chart). KPI card showing a primary metric with optional delta indicator, icon, and sparkline.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Kpi is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1
+
+Accessibility: role "figure", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/line-chart.md

@@ -0,0 +1,113 @@
+# LineChart
+
+**Category:** chart  
+**Description:** Time-series or numeric line chart with multi-series support, hover tooltip, and legend.
+
+## When to use
+
+- Showing trends and precise values over continuous time or a numeric range
+- Comparing the trajectory of multiple series on a shared scale
+
+## When NOT to use
+
+- Comparing discrete categories — use BarChart
+- Emphasising cumulative volume — use AreaChart
+
+## Related components
+
+- **AreaChart** (alternative): Use when filled cumulative volume matters more than precise values
+- **BarChart** (alternative): Use for discrete categorical comparison
+
+## Accessibility rationale
+
+Renders with role="img" and requires a title prop for screen reader labeling.
+
+## Props
+
+| Name            | Type                                                                                                                    | Required | Default  | Description                                                                                                                |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `series`        | `LineChartSeries<Datum>[]`                                                                                              | Yes      | —        | Array of data series                                                                                                       |
+| `x`             | `(d: Datum) => number \| Date`                                                                                          | Yes      | —        | X-value accessor                                                                                                           |
+| `y`             | `(d: Datum) => number`                                                                                                  | Yes      | —        | Y-value accessor                                                                                                           |
+| `title`         | `string`                                                                                                                | Yes      | —        | Chart title (also used as aria-label)                                                                                      |
+| `description`   | `string`                                                                                                                | No       | —        | Subtitle shown below title                                                                                                 |
+| `curve`         | `'linear' \| 'monotone' \| 'step' \| 'stepBefore' \| 'stepAfter' \| 'natural' \| 'basis' \| 'cardinal' \| 'catmullRom'` | No       | monotone | Line interpolation curve                                                                                                   |
+| `width`         | `number`                                                                                                                | No       | —        | Fixed SVG width (defaults to container width)                                                                              |
+| `height`        | `number`                                                                                                                | No       | 300      | SVG height in px                                                                                                           |
+| `xTicks`        | `number`                                                                                                                | No       | 5        | Approximate number of X-axis ticks                                                                                         |
+| `yTicks`        | `number`                                                                                                                | No       | 5        | Approximate number of Y-axis ticks                                                                                         |
+| `legend`        | `boolean`                                                                                                               | No       | —        | Show series legend                                                                                                         |
+| `tooltip`       | `boolean`                                                                                                               | No       | —        | Enable hover tooltip                                                                                                       |
+| `formatTooltip` | `(datum: Datum, series: LineChartSeries<Datum>) => string`                                                              | No       | —        | Custom tooltip formatter                                                                                                   |
+| `className`     | `string`                                                                                                                | No       | —        | Additional CSS class names merged onto the root element.                                                                   |
+| `plain`         | `boolean`                                                                                                               | No       | false    | Marks only — no axes, grid lines, or legend. For micro/inline charts.                                                      |
+| `annotations`   | `Annotation[]`                                                                                                          | No       | —        | Reference lines, shaded bands, and markers drawn over the plot (e.g. a target/threshold line).                             |
+| `labels`        | `boolean \| { format?: (v: number) => string; position?: string }`                                                      | No       | —        | Print each value as a label on the mark (collision-aware, decorative/aria-hidden).                                         |
+| `connectNulls`  | `boolean`                                                                                                               | No       | false    | Bridge non-finite y gaps instead of breaking the line at them.                                                             |
+| `onSelect`      | `(point: ChartPoint) => void`                                                                                           | No       | —        | Fired when a point is clicked or activated (Enter/Space) — for drill-down.                                                 |
+| `brush`         | `boolean`                                                                                                               | No       | false    | Show a keyboard-operable Brush below the plot to subset (zoom) the series to a window.                                     |
+| `dataZoom`      | `boolean`                                                                                                               | No       | false    | Show a DataZoom slider below the plot — a Brush whose body also pans the window.                                           |
+| `zoom`          | `boolean`                                                                                                               | No       | false    | Enable in-plot wheel/drag/keyboard zoom-pan (+/-/0) over the series index window, with a reset control and re-ticked axes. |
+| `syncId`        | `string`                                                                                                                | No       | —        | Connect this chart to others sharing the same id — they mirror the zoom window and hovered x.                              |
+| `tooltipMode`   | `'item' \| 'axis'`                                                                                                      | No       | item     | Tooltip trigger — item (nearest point) or axis (a crosshair + a shared tooltip listing every series at the hovered x).     |
+| `decimate`      | `boolean \| { method?: 'lttb' \| 'minmax'; threshold?: number }`                                                        | No       | —        | Downsample dense series before drawing (LTTB or min-max). Visual only — the fallback table keeps the full data.            |
+| `toolbox`       | `boolean \| ToolboxOptions`                                                                                             | No       | —        | Render a keyboard-reachable toolbox — PNG/SVG export, a data-view table toggle, and restore (reset zoom).                  |
+| `transition`    | `boolean \| { duration?: number; easing?: string; properties?: string[] }`                                              | No       | —        | Tune the reduced-motion-gated enter/update transitions (false disables). Always suppressed under prefers-reduced-motion.   |
+| `onBeforeDraw`  | `(ctx: { width: number; height: number }) => ReactNode`                                                                 | No       | —        | Render custom SVG behind the marks (watermark/region) — a lightweight extension seam.                                      |
+| `onAfterDraw`   | `(ctx: { width: number; height: number }) => ReactNode`                                                                 | No       | —        | Render custom SVG over the marks (overlay/extra series) — a lightweight extension seam.                                    |
+
+## Tokens
+
+- `--cascivo-chart-1`
+- `--cascivo-chart-2`
+- `--cascivo-chart-3`
+- `--cascivo-chart-4`
+- `--cascivo-chart-5`
+- `--cascivo-chart-6`
+- `--cascivo-chart-7`
+- `--cascivo-chart-8`
+
+## Examples
+
+### Basic line chart
+
+```jsx
+import { LineChart } from '@cascivo/charts'
+
+const series = [{ id: 'a', label: 'Revenue', data: [{x:1,y:10},{x:2,y:20},{x:3,y:15}] }]
+<LineChart series={series} x={d => d.x} y={d => d.y} title="Revenue" />
+```
+
+### With an SLO target line
+
+```jsx
+<LineChart
+  series={series}
+  x={(d) => d.x}
+  y={(d) => d.y}
+  title="Latency"
+  annotations={[{ kind: 'line', axis: 'y', value: 200, label: 'SLO' }]}
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo LineChart component (chart). Time-series or numeric line chart with multi-series support, hover tooltip, and legend.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+LineChart is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1, --cascivo-chart-2, --cascivo-chart-3, --cascivo-chart-4, --cascivo-chart-5, --cascivo-chart-6, --cascivo-chart-7, --cascivo-chart-8
+
+Accessibility: role "img", WCAG 2.1-AA, keyboard: Tab (focus chart)/ArrowLeft/ArrowRight (navigate points)/Home/End (first/last point)/Escape (clear focus). Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/meter.md

@@ -0,0 +1,71 @@
+# Meter
+
+**Category:** chart  
+**Description:** Progress meter in bar or gauge variant with threshold coloring.
+
+## When to use
+
+- Showing a rated or gauged value within a known min/max range
+- Surfacing threshold-based status (e.g. CPU, disk, score) as a bar or gauge
+
+## When NOT to use
+
+- Showing task completion progress — use a ProgressBar
+- Comparing a value against a target with range bands — use Bullet
+
+## Related components
+
+- **Bullet** (alternative): Use when a target marker and qualitative bands are needed
+- **Kpi** (alternative): Use for a headline metric without a bounded range
+
+## Accessibility rationale
+
+Renders with role="meter" exposing min, max, and current value to assistive tech.
+
+## Props
+
+| Name         | Type               | Required | Default | Description                       |
+| ------------ | ------------------ | -------- | ------- | --------------------------------- |
+| `value`      | `number`           | Yes      | —       | Current value                     |
+| `label`      | `string`           | Yes      | —       | Text label for the control.       |
+| `min`        | `number`           | No       | 0       | Minimum allowed value.            |
+| `max`        | `number`           | No       | 100     | Maximum allowed value.            |
+| `variant`    | `'bar' \| 'gauge'` | No       | bar     | Selects the visual style variant. |
+| `thresholds` | `MeterThresholds`  | No       | —       | Color breakpoints                 |
+| `width`      | `number`           | No       | —       | Width of the component.           |
+| `height`     | `number`           | No       | —       | Height of the component.          |
+
+## Tokens
+
+- `--cascivo-chart-1`
+
+## Examples
+
+### Basic meter
+
+```jsx
+import { Meter } from '@cascivo/charts'
+;<Meter value={72} label="CPU usage" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Meter component (chart). Progress meter in bar or gauge variant with threshold coloring.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Meter is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1
+
+Accessibility: role "meter", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```