yukit-web 0.5.0 → 0.6.0

package/README.md

@@ -17,16 +17,17 @@ Angular UI component library for Yurest web applications. Built on [Spartan](htt
 
 ## Requirements
 
-| Dependency                                                        | Version | Notes                          |
-| :---------------------------------------------------------------- | :------ | :----------------------------- |
-| [Angular](https://angular.dev/)                                   | 21+     | Standalone APIs, signal inputs |
-| [Tailwind CSS](https://tailwindcss.com/)                          | v4      | Required — see [Setup](#setup) |
-| [`@spartan-ng/brain`](https://spartan.ng)                         | ^1.3.0  | Headless primitives            |
-| [`@angular/cdk`](https://material.angular.dev/cdk/categories)     | ^21.0.0 | Overlays, a11y                 |
-| [`@ng-icons/core`](https://ng-icons.github.io/ng-icons/) + lucide | ^32.2.0 | Icons                          |
-| [`@tanstack/angular-table`](https://tanstack.com/table)           | ^9.0.0  | `<yuw-datatable>`              |
-| `embla-carousel-angular`                                          | ^21.0.0 | Carousel primitives            |
-| `ngx-scrollbar`                                                   | ^19.1.5 | Scroll areas                   |
+| Dependency                                                        | Version | Notes                            |
+| :---------------------------------------------------------------- | :------ | :------------------------------- |
+| [Angular](https://angular.dev/)                                   | 21+     | Standalone APIs, signal inputs   |
+| [Tailwind CSS](https://tailwindcss.com/)                          | v4      | Required — see [Setup](#setup)   |
+| [`@spartan-ng/brain`](https://spartan.ng)                         | ^1.3.0  | Headless primitives              |
+| [`@angular/cdk`](https://material.angular.dev/cdk/categories)     | ^21.0.0 | Overlays, a11y                   |
+| [`@ng-icons/core`](https://ng-icons.github.io/ng-icons/) + lucide | ^32.2.0 | Icons                            |
+| [`@tanstack/angular-table`](https://tanstack.com/table)           | ^9.0.0  | `<yuw-datatable>`                |
+| `embla-carousel-angular`                                          | ^21.0.0 | Carousel primitives              |
+| `ngx-scrollbar`                                                   | ^19.1.5 | Scroll areas                     |
+| `d3-scale` + `d3-shape`                                           | ^4 / ^3 | Optional, only for `<yuw-chart>` |
 
 ## Installation
 
@@ -44,6 +45,12 @@ npm install -D tailwindcss @tailwindcss/postcss tw-animate-css
 
 `tw-animate-css` is required because `@spartan-ng/brain/hlm-tailwind-preset.css` imports it.
 
+Apps that draw [charts](#chart) also install their two geometry packages, which no other component needs:
+
+```bash
+npm install d3-scale d3-shape
+```
+
 ## Setup
 
 `yukit-web` does **not** ship compiled component CSS. Its templates carry Tailwind utility classes,
@@ -163,6 +170,7 @@ behave like any other Tailwind color:
 | `--warning` / `--warning-foreground` | `bg-warning`, `text-warning-foreground`, …                                                                                                                |
 | `--info` / `--info-foreground`       | `bg-info`, `text-info-foreground`, …                                                                                                                      |
 | `--destructive-foreground`           | `text-destructive-foreground` — Spartan defines only `--destructive` and hardcodes `text-white`; Yurest names a contrast color, so the pair is completed. |
+| `--chart-1` … `--chart-8`            | `bg-chart-1`, `fill-chart-3`, … — the series palette of [`<yuw-chart>`](#chart), each at least 3:1 against the page in light and dark mode.               |
 
 To override a token, redefine it in your own `:root` _after_ importing the theme.
 
@@ -297,6 +305,7 @@ neither source silently overrides the other.
 | [Empty](#empty)                   | `[yuwEmpty]`              | `YuwEmptyImports`                          |
 | [Skeleton](#skeleton)             | `[yuwSkeleton]`           | `YuwSkeletonDirective`                     |
 | [Spinner](#spinner)               | `yuw-spinner`             | `YuwSpinnerComponent`                      |
+| [Chart](#chart)                   | `yuw-chart`               | `YuwChartComponent` (`yukit-web/chart`)    |
 | **Navigation**                    |                           |                                            |
 | [Accordion](#accordion)           | `yuw-accordion`           | `YuwAccordionImports`                      |
 | [Breadcrumb](#breadcrumb)         | `yuw-breadcrumb`          | `YuwBreadcrumbComponent`                   |
@@ -1068,6 +1077,84 @@ The spinner inherits its size from the container's font size — wrap it in `tex
 
 ---
 
+### Chart
+
+Bar, line, area, pie and donut charts drawn as SVG, modelled on shadcn/ui's chart: a `config` names
+each series, gives it a label and a color token, and the tooltip and legend read the same config.
+It lives in its own entry point, so apps that draw no chart never load it nor its `d3-scale` /
+`d3-shape` peers:
+
+```ts
+import { YuwChartComponent, type YuwChartConfigDto, yuwChartColorAt } from 'yukit-web/chart';
+```
+
+```ts
+protected readonly config: YuwChartConfigDto = {
+  food: { label: this.translate('purchases.food'), color: 'chart-1' },
+  drinks: { label: this.translate('purchases.drinks'), color: 'chart-2' },
+};
+protected readonly rows = [
+  { month: '2026-01-01', food: 4200, drinks: 1800 },
+  { month: '2026-02-01', food: 3900, drinks: 1650 },
+];
+protected readonly euros = (value: number) => this.currency.format(value);
+protected readonly month = (value: unknown) => this.monthFormat.format(new Date(String(value)));
+```
+
+```html
+<yuw-chart
+  kind="bar-stacked"
+  class="h-80"
+  ariaLabel="Purchases per month"
+  emptyText="No purchases in this period"
+  categoryKey="month"
+  categoryLabel="Month"
+  [config]="config"
+  [data]="rows"
+  [valueFormat]="euros"
+  [categoryFormat]="month"
+/>
+
+<yuw-chart kind="donut" ariaLabel="Purchases by provider" emptyText="No purchases" [config]="config" [data]="rows" />
+```
+
+- **Kinds** (`YuwChartKindDto`): `bar`, `bar-stacked`, `bar-horizontal`, `bar-horizontal-stacked`,
+  `line`, `area`, `area-stacked`, `pie`, `donut`. Bars group their series unless the kind is
+  stacked. Pie and donut draw one slice per series, summing it across every row, so the rows of a
+  stacked bar chart give the donut of its totals; for a distribution, pass one row.
+- **Colors** are the `chart-1` … `chart-8` theme tokens, applied as `var(--chart-n)`, so dark mode
+  recolors with no redraw. `yuwChartColorAt(index)` cycles through them for a config built from
+  data, such as one series per provider.
+- **Formatting is yours.** `valueFormat` and `categoryFormat` turn numbers and categories into the
+  text of axes, tooltips and the accessible table; the library hardcodes no locale or currency.
+- **Missing values** (anything that is not a finite number) are gaps, never zeros.
+- **Size**: the chart fills its root, `h-72` by default; set the height with `class`. It redraws
+  when its box resizes and draws nothing on the server, where only the accessible table renders.
+- **Accessibility**: the chart is a named figure (`ariaLabel`, optional `description`) with a
+  visually hidden data table. The plot is focusable: the arrow keys, Home and End move the tooltip
+  across categories or slices, Escape hides it, and the active one is announced politely.
+  Transitions respect `prefers-reduced-motion`.
+
+#### Inputs
+
+| Input            | Type                                                        | Default     |
+| :--------------- | :---------------------------------------------------------- | :---------- |
+| `ariaLabel`      | `string` — **required**, the accessible name                | —           |
+| `config`         | `YuwChartConfigDto` — **required**                          | —           |
+| `data`           | `YuwChartRowDto[]` — **required**                           | —           |
+| `emptyText`      | `string` — **required**                                     | —           |
+| `kind`           | `YuwChartKindDto`                                           | `'bar'`     |
+| `categoryKey`    | `string｜undefined` — cartesian kinds                       | `undefined` |
+| `categoryLabel`  | `string｜undefined` — category column header, for the table | `undefined` |
+| `categoryFormat` | `(category: unknown) => string` — cartesian kinds           | `String`    |
+| `valueFormat`    | `(value: number) => string`                                 | `String`    |
+| `description`    | `string｜undefined` — accessible description                | `undefined` |
+| `legend`         | `boolean`                                                   | `true`      |
+| `loading`        | `boolean` — renders a skeleton and sets `aria-busy`         | `false`     |
+| `class`          | `string` — merged last onto the root                        | `''`        |
+
+---
+
 ### Accordion
 
 ```html