iryx-ui 0.8.0 → 0.10.1

package/README.md

@@ -199,21 +199,20 @@ For a static re-brand, plain CSS works too — tokens are just variables:
 
 ### Typeface
 
-The library ships **no webfont** — that would put font files, a licence and a
-network request into every app whether it wanted them or not. It reads one
-variable, defaulting to the system stack. Point it at your own family and
-everything follows, including Tailwind's `font-sans`:
+Set `--iryx-font-sans` and everything follows, including Tailwind's
+`font-sans`. Load the family however you like — a package, a `<link>`, or
+self-hosted:
 
 ```css
-@import "@fontsource-variable/instrument-sans"; /* or a <link>, or self-hosted */
+@import "@fontsource-variable/instrument-sans";
 
 :root {
   --iryx-font-sans: "Instrument Sans", ui-sans-serif, system-ui, sans-serif;
 }
 ```
 
-Unlike the colour tokens, this one is not mode-specific — there is no `.dark`
-counterpart to keep in sync.
+Leave it unset to use the system stack. There is no `.dark` counterpart for
+this one.
 
 Available tokens, each usable as a Tailwind color (`bg-primary`,
 `text-muted-foreground`, …):
@@ -290,6 +289,9 @@ app.use(createIryxUi({ unstyled: true }))
 | `IFormField` | Label, description, hint, help and error text around a control |
 | `IInput` | Text field with `sm`/`md`/`lg` sizes, `invalid` state, `v-model`, `leading`/`trailing` slots, `clearable`, `loading`, `debounce` |
 | `INumberInput` | Decimal-safe numeric field — the model is a **string**, with `min`/`max`/`step`, `precision` and locale-aware display |
+| `ISparkline` | Tiny inline trend chart — pure SVG, no charting dependency |
+| `IBarChart` | Categorical bar chart with a round-number axis, hover tooltip and a table view |
+| `ILineChart` | Line or area chart with a crosshair, hover marker and a table view |
 | `IFileUpload` | Drag-and-drop file field with `accept` / `maxSize` / `maxFiles`, thumbnails and a remove action |
 | `IDatePicker` | Calendar in a popover; the model is an ISO `YYYY-MM-DD` **string** |
 | `IDateRangePicker` | Two-month range calendar; the model is `{ start, end }` ISO strings |
@@ -481,6 +483,276 @@ chrome; use `ui` to reach the parts (`root`, `input`, `leading`, `trailing`,
 forwarded to the `<input>` itself. `ref` exposes the element as `.input` for
 focus management.
 
+#### Multiple series
+
+Both charts take plain rows plus a `series` descriptor — the same shape
+`ITable` uses. Omit `series` for the single-measure case.
+
+```vue
+<IBarChart
+  :data="[
+    { label: 'Jan', revenue: 4200, expenses: 3100 },
+    { label: 'Feb', revenue: 5600, expenses: 3400 },
+  ]"
+  :series="[
+    { key: 'revenue', name: 'Revenue', slot: 0 },
+    { key: 'expenses', name: 'Expenses', slot: 1 },
+  ]"
+  label="Cashflow by month"
+/>
+```
+
+Bars group inside their category; lines draw one path each. One hover reports
+**every** series for that category in a single tooltip, so the reader compares
+in one place instead of chasing marks.
+
+**`slot` pins a series to a palette colour.** Without it, colour follows array
+position — so filtering a series out repaints the survivors and the reader has
+to relearn the chart. Pin the slots whenever series can be toggled.
+
+**The legend is mandatory from two series up.** `legend: false` only silences
+the single-series case, where the title already names what is plotted. Colour
+alone is never a dependable identity channel, so this is not configurable.
+
+Past eight series the colours stop identifying anything; the chart warns in
+development and you should fold the tail into "Other" or switch to small
+multiples.
+
+`variant="area"` is ignored for multiple series — overlapping washes muddy into
+a colour that belongs to neither.
+
+#### Annotations, and why there is no plugin API
+
+Chart.js has plugins because canvas is opaque — once painted you cannot select
+or style anything, so the only way in is an imperative draw hook. SVG has no
+such problem, so these charts hand you the layout and let you write ordinary
+markup into it:
+
+```vue
+<ILineChart :data="revenue" label="Revenue against target">
+  <template #overlay="{ plot, value }">
+    <line
+      :x1="plot.left" :y1="value(7000)"
+      :x2="plot.left + plot.width" :y2="value(7000)"
+      stroke="var(--iryx-warning)" stroke-width="2" stroke-dasharray="4 4"
+    />
+  </template>
+</ILineChart>
+```
+
+`#underlay` renders behind the marks — target bands, shaded regions. `#overlay`
+renders in front — reference lines, callouts. Both sit below the hit targets,
+so hovering keeps working through whatever you draw.
+
+Both receive the `CartesianLayout`:
+
+| Prop | What it gives you |
+| --- | --- |
+| `plot` | `{ left, top, width, height }` of the plot rectangle, in px |
+| `value(n)` | A data value to its pixel on the value axis |
+| `bandCentre(i)` | The centre of category `i`, in px |
+| `bandWidth` | Size of one category slot |
+| `ticks` | The axis values actually drawn |
+| `orientation` | `'vertical'` or `'horizontal'` |
+
+That's strictly more capable than a draw hook: it's declarative, reactive, and
+type-checked, with no lifecycle or registration order to learn.
+
+For a chart type that doesn't exist here, the same primitives are exported —
+`cartesianLayout`, `linearScale`, `niceTicks`, `seriesColor` — so you can build
+one on the same spine rather than starting over.
+
+#### Chart colours
+
+Eight categorical slots, `--iryx-chart-1` … `--iryx-chart-8`, usable as Tailwind
+colours (`text-chart-3`, `fill-chart-5`). They encode **identity** — which
+series a mark belongs to — never magnitude.
+
+```vue
+<!-- One series per slot, assigned in order. -->
+<ISparkline :data="revenue" class="text-chart-1" />
+
+<ISparkline :data="expenses" class="text-chart-2" />
+```
+
+Three rules, and they are not stylistic:
+
+- **Assign in order, never cycle.** A ninth series is not a generated ninth
+  hue — fold it into "Other", or switch to small multiples. A generated colour
+  hasn't been checked for separation against its neighbours.
+- **Status colours are never series colours.** A series that happens to land in
+  slot 4 must not read as a warning. `success`/`warning`/`danger`/`info` stay
+  reserved.
+- **Colour follows the entity, not its rank.** If a filter removes a series,
+  the survivors keep their slots rather than shifting up.
+
+Tailwind scans source text, so a class name assembled at runtime is never
+generated — write the slots out, or reach for the variable:
+
+```vue
+<!-- Silently unstyled: Tailwind never sees this string -->
+<ISparkline :class="`text-chart-${index + 1}`" />
+
+<!-- Either of these works -->
+<ISparkline :class="['text-chart-1', 'text-chart-2'][index]" />
+
+<ISparkline :style="{ color: `var(--iryx-chart-${index + 1})` }" />
+```
+
+The steps are not eyeballed. Each clears a lightness band, a chroma floor, and
+protanopia/deuteranopia separation against its own surface, checked with a
+validator rather than by eye. **Dark has its own steps**, validated against the
+dark background — not an automatic flip of the light ones.
+
+Two caps worth knowing before you design around them:
+
+| Chart form | Max series |
+| --- | --- |
+| Bars, lines, stacks — only neighbours touch | **8** |
+| Scatter, bubble, small multiples — any two marks can sit side by side | **3** |
+
+Past those, the answer is fewer series or facets, not more colours. If you
+re-step any slot, re-run the validator for **both** modes.
+
+#### Line charts
+
+```vue
+<ILineChart
+  :data="[
+    { label: 'Jan', value: 4200 },
+    { label: 'Feb', value: null },
+    { label: 'Mar', value: 5600 },
+  ]"
+  variant="area"
+  label="Revenue by month"
+/>
+```
+
+Same `data`, `height`, `ticks`, `axis`, `locale`, `format` and `label` props as
+`IBarChart`, plus:
+
+| Prop | Effect |
+| --- | --- |
+| `variant` | `line` (default) or `area`, which adds a wash beneath the line |
+| `zero` | Force zero onto the axis. **Off by default** |
+
+**`zero` is off here and always on for bars, deliberately.** A bar is read by
+length, so a truncated baseline lies about the comparison. A line is read by
+its *shape*, and a series hovering around 8,000 flattens into a straight edge
+once the axis starts at nothing. Turn it on when the distance from zero is the
+point.
+
+`null` breaks the line rather than bridging it, so a missing reading never
+draws a slope that didn't happen.
+
+Hovering shows a crosshair and a single ringed marker on the reading under the
+cursor — not a dot on every point, which is noise the axis and tooltip already
+cover.
+
+#### Bar charts
+
+```vue
+<IBarChart
+  :data="[
+    { label: 'Jan', value: 4200 },
+    { label: 'Feb', value: 5600 },
+    { label: 'Mar', value: null },
+  ]"
+  label="Revenue by month"
+  locale="de-DE"
+  :format="{ style: 'currency', currency: 'EUR', maximumFractionDigits: 0 }"
+/>
+```
+
+| Prop | Effect |
+| --- | --- |
+| `data` | `{ label, value }[]`. `value: null` is a **missing reading** — no bar, which is not a zero |
+| `height` | Rendered height in px (default 240). Width fills the container |
+| `ticks` | Target tick count. A hint — the axis lands on round numbers first |
+| `axis` | Set `false` to drop the value axis and gridlines |
+| `locale` / `format` | `Intl.NumberFormat` settings, applied to ticks and tooltip alike |
+| `label` | Accessible name for the figure |
+
+**The axis picks the domain, not the data.** Values are snapped outwards to a
+1/2/5 step, so an axis reads `0 / 2,000 / 4,000` rather than `0 / 1,726.8`.
+Zero is always included, because bars are compared by length and a truncated
+baseline makes that comparison a lie.
+
+Bars are capped at 24px and never fill their slot — the gap between them is
+what separates them. They're rounded at the data end and square at the
+baseline, so the rounding reads as the tip of the value.
+
+Hovering a bar dims the rest and shows a tooltip; hit targets span the full
+band and plot height, so a short bar is no harder to hit than a tall one.
+
+**Accessibility:** the SVG is `aria-hidden` and the data is exposed as a
+visually-hidden table instead, so a screen reader gets the actual numbers
+rather than a blank graphic. That table renders even before the container has
+been measured — the data is never gated behind layout.
+
+**`orientation="horizontal"`** runs the categories down the side:
+
+```vue
+<IBarChart :data="spend" orientation="horizontal" label="Spend by category" />
+```
+
+Vertical charts thin colliding labels to every *n*th, which is fine for `Jan`
+/ `Feb` and lossy for `Travel and accommodation`. Turn the chart and the names
+get real width, so nothing is dropped — that's the case horizontal is for.
+Everything else behaves the same: grouped series, the tooltip, the round-number
+axis anchored at zero.
+
+#### Sparklines
+
+A trend at a glance, for a stat tile or a table cell. Plain SVG — no charting
+library, no canvas, nothing to install.
+
+```vue
+<ISparkline
+  :data="[4200, 4600, 4100, 5200, 5800, 6300]"
+  variant="area"
+  end-dot
+  label="Revenue over six months, trending up"
+/>
+```
+
+Because it is SVG, colour comes from `currentColor`: recolour it with a text
+utility, and it follows your theme preset and light/dark automatically with no
+JavaScript. A canvas chart cannot read CSS variables, so it would need a
+re-render on every theme change.
+
+| Prop | Effect |
+| --- | --- |
+| `data` | Values, oldest first. `null` is a **gap**, not a zero — the line breaks |
+| `variant` | `line` (default) or `area`, which adds a wash beneath the line |
+| `endDot` | Marks the most recent point |
+| `baseline` | Lower edge of the `area` wash: `min` (default) or `zero` |
+| `min` / `max` | Pin the domain — set both to put several sparklines on one scale |
+| `muted` | Draw in muted ink, for a de-emphasised trend |
+| `height` | Rendered height in px (default 32). Width always fills the container |
+
+Width is fluid and the stroke never distorts: the drawing stretches via
+`preserveAspectRatio="none"`, while every stroke carries
+`vector-effect="non-scaling-stroke"`, so a 2px line stays 2px and the end dot
+stays circular at any aspect ratio.
+
+`label` sets an accessible description. **Without one the sparkline is hidden
+from assistive tech as decorative** — which is correct when it sits beside a
+value that already states the number, and wrong if it is the only thing
+carrying the information.
+
+Edge cases behave: an empty series draws nothing, a flat series draws through
+the middle rather than collapsing to an edge, and a single reading is a dot.
+
+The scale helpers are exported for building your own marks:
+
+```ts
+import { extent, linearScale } from 'iryx-ui'
+
+extent([3, null, 9, 1]) // [1, 9] — gaps ignored
+linearScale([0, 10], [100, 0])(10) // 0 — ranges may be inverted for SVG's y-axis
+```
+
 #### Files
 
 ```vue

package/dist/component-names.d.ts

@@ -3,5 +3,5 @@
  * Consumed by the Vue plugin (global registration) and the Nuxt module
  * (auto-imports). Keep in sync with `src/components/index.ts`.
  */
-export declare const componentNames: readonly ["Alert", "App", "Badge", "Banner", "Breadcrumb", "Button", "ButtonGroup", "Card", "Checkbox", "Combobox", "ConfirmDialog", "DatePicker", "DateRangePicker", "Dialog", "DropdownMenu", "EmptyState", "FileUpload", "Form", "FormField", "Input", "Label", "NumberInput", "Pagination", "PasswordInput", "Progress", "RadioGroup", "Select", "Separator", "Skeleton", "Stat", "Stepper", "Switch", "Table", "Tabs", "Textarea", "Toaster", "Tooltip"];
+export declare const componentNames: readonly ["Alert", "App", "Badge", "BarChart", "Banner", "Breadcrumb", "Button", "ButtonGroup", "Card", "ChartLegend", "Checkbox", "Combobox", "ConfirmDialog", "DatePicker", "DateRangePicker", "Dialog", "DropdownMenu", "EmptyState", "FileUpload", "Form", "FormField", "Input", "Label", "LineChart", "NumberInput", "Pagination", "PasswordInput", "Progress", "RadioGroup", "Select", "Separator", "Skeleton", "Sparkline", "Stat", "Stepper", "Switch", "Table", "Tabs", "Textarea", "Toaster", "Tooltip"];
 export type ComponentName = (typeof componentNames)[number];

package/dist/component-names.js

@@ -0,0 +1,4 @@
+//#region src/component-names.ts
+var e = /* @__PURE__ */ "Alert.App.Badge.BarChart.Banner.Breadcrumb.Button.ButtonGroup.Card.ChartLegend.Checkbox.Combobox.ConfirmDialog.DatePicker.DateRangePicker.Dialog.DropdownMenu.EmptyState.FileUpload.Form.FormField.Input.Label.LineChart.NumberInput.Pagination.PasswordInput.Progress.RadioGroup.Select.Separator.Skeleton.Sparkline.Stat.Stepper.Switch.Table.Tabs.Textarea.Toaster.Tooltip".split(".");
+//#endregion
+export { e as componentNames };

package/dist/{packages/iryx-ui/src/components → components}/Alert.vue_vue_type_script_setup_true_lang.js

@@ -1,4 +1,4 @@
-import { Alert02Icon as e, AlertCircleIcon as t, Cancel01Icon as n, CheckmarkCircle02Icon as r, InformationCircleIcon as i } from "../../../../node_modules/.pnpm/@hugeicons_core-free-icons@4.2.3/node_modules/@hugeicons/core-free-icons/dist/esm/index.js";
+import { Alert02Icon as e, AlertCircleIcon as t, Cancel01Icon as n, CheckmarkCircle02Icon as r, InformationCircleIcon as i } from "../node_modules/.pnpm/@hugeicons_core-free-icons@4.2.3/node_modules/@hugeicons/core-free-icons/dist/esm/index.js";
 import { useIryxUiConfig as a } from "../config.js";
 import { alertTheme as o } from "../theme/alert.js";
 import s from "./Icon.js";

package/dist/{packages/iryx-ui/src/components → components}/Banner.vue_vue_type_script_setup_true_lang.js

@@ -1,4 +1,4 @@
-import { Cancel01Icon as e } from "../../../../node_modules/.pnpm/@hugeicons_core-free-icons@4.2.3/node_modules/@hugeicons/core-free-icons/dist/esm/index.js";
+import { Cancel01Icon as e } from "../node_modules/.pnpm/@hugeicons_core-free-icons@4.2.3/node_modules/@hugeicons/core-free-icons/dist/esm/index.js";
 import { useIryxUiConfig as t } from "../config.js";
 import n from "./Icon.js";
 import { bannerTheme as r } from "../theme/banner.js";

package/dist/components/BarChart.js

@@ -0,0 +1,5 @@
+import e from "./BarChart.vue_vue_type_script_setup_true_lang.js";
+//#region src/components/BarChart.vue
+var t = e;
+//#endregion
+export { t as default };

package/dist/components/BarChart.vue.d.ts

@@ -0,0 +1,95 @@
+import type { ChartSeries } from '../composables/cartesian';
+import type { SparseValue } from '../composables/scale';
+/**
+ * A row. `value` is the single-series shortcut; with `series` set, each entry
+ * reads its own key off the row instead — plain objects and a descriptor, the
+ * same shape `ITable` uses.
+ */
+export interface BarChartDatum {
+    label: string;
+    /** `null` is a missing reading — no bar is drawn, which is not the same as 0. */
+    value?: SparseValue;
+    [key: string]: unknown;
+}
+export interface BarChartProps {
+    data?: readonly BarChartDatum[];
+    /** Two or more measures per category. Omit for the single-series case. */
+    series?: readonly ChartSeries[];
+    /**
+     * `horizontal` runs the categories down the side, where a long name has room
+     * to be read. Vertical charts thin their labels to avoid collisions, so long
+     * or numerous category names are the case to turn the chart for.
+     */
+    orientation?: 'vertical' | 'horizontal';
+    /** Rendered height in px. Width always fills the container. */
+    height?: number;
+    /** Target tick count. The axis lands on round numbers, so this is a hint. */
+    ticks?: number;
+    /** Drop the value axis and its gridlines. */
+    axis?: boolean;
+    /** Drop the legend. Only honoured for a single series — see below. */
+    legend?: boolean;
+    /** Locale and options for every number shown — ticks and tooltip alike. */
+    locale?: string;
+    format?: Intl.NumberFormatOptions;
+    /**
+     * Accessible name for the figure. The bars are hidden from assistive tech
+     * and the data is exposed as a table instead, so this names what that is.
+     */
+    label?: string;
+    /** Skip built-in classes; you take over styling entirely. */
+    unstyled?: boolean;
+    class?: string;
+    ui?: Partial<Record<'root' | 'svg' | 'grid' | 'tick' | 'category' | 'bar' | 'tooltip' | 'tooltipLabel' | 'tooltipValue' | 'table', string>>;
+}
+declare var __VLS_6: {
+    orientation: import("..").ChartOrientation;
+    ticks: number[];
+    plot: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    value: (value: number) => number;
+    y: (value: number) => number;
+    bandWidth: number;
+    labelStep: number;
+    bandCentre: (index: number) => number;
+}, __VLS_8: {
+    orientation: import("..").ChartOrientation;
+    ticks: number[];
+    plot: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    value: (value: number) => number;
+    y: (value: number) => number;
+    bandWidth: number;
+    labelStep: number;
+    bandCentre: (index: number) => number;
+};
+type __VLS_Slots = {} & {
+    underlay?: (props: typeof __VLS_6) => any;
+} & {
+    overlay?: (props: typeof __VLS_8) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<BarChartProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<BarChartProps> & Readonly<{}>, {
+    unstyled: boolean;
+    data: readonly BarChartDatum[];
+    legend: boolean;
+    orientation: "vertical" | "horizontal";
+    height: number;
+    ticks: number;
+    axis: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};