# @jcsoftdev/ui - full documentation

> Token-driven React 19 component library (Radix, Tailwind CSS v4, no runtime CSS-in-JS): atoms, forms, containers, overlays, about one hundred pure-SVG charts, a spreadsheet-grade DataGrid, an AI chat kit, rich text, XLSX and brand tools, themed by data-style, data-density, data-radius, data-accent and data-theme attributes.

Every documentation page below is also available on its own at <page URL>.md. Index: https://ui.jcsoftdev.com/llms.txt

---

# Introduction

> What @jcsoftdev/ui is, what it ships and how this documentation is organised.

Source: https://ui.jcsoftdev.com/docs/index

`@jcsoftdev/ui` is a token-driven React 19 component library built on Radix primitives and Tailwind CSS v4. There is no runtime CSS-in-JS: the whole look comes from one tokens file that is compiled to CSS variables, and a handful of `data-*` attributes restyle everything at runtime.

## What is inside

- **Atoms, forms, containers, overlays, navigation, states, shell**: the everyday building blocks, including a DataGrid with formulas, undo, XLSX export and integrated charts.
- **Charts**: about one hundred pure React and SVG charts and chart parts (line, bar, donut, radar, gauge, heatmap, treemap, sankey, stock, globe, maps, crossfilter...) with no chart dependency.
- **AI kit** (`@jcsoftdev/ui/ai`): conversation, streaming-friendly messages, markdown, code blocks, prompt input and tool calls.
- **Rich text**, **XLSX** writer, **brand** tools (Logo Forge), calendar views and a command palette.

Everything adapts to the width of its **container**, not the viewport, so a component behaves the same in a sidebar, a card or a dialog.

## How to read these docs

1. [Getting started](/docs/getting-started/) installs the package and wires the CSS.
2. [Theming and presets](/docs/theming/) explains `data-style`, `data-density`, `data-radius`, `data-accent` and `data-theme`.
3. Each page under **Components** is generated from the library source: import path, props with types and defaults, accessibility notes, a live example and links to Storybook.
4. Language models can read the same content as plain Markdown: see [Docs for LLMs](/docs/llms/).

## Conventions

- Documentation and identifiers are in English. Sample data in examples is Spanish (a barbershop), because that is the product the library was built for.
- Component pages are regenerated from `packages/ui/src` on every build, so props and import paths never drift from the code.

---

# Getting started

> Install @jcsoftdev/ui, import the token stylesheets and render your first component in Next.js, Astro or Vite.

Source: https://ui.jcsoftdev.com/docs/getting-started

## Install

```bash
pnpm add @jcsoftdev/ui
```

Peer dependencies are `react` and `react-dom` (19) and `tailwindcss` v4. Radix, `lucide-react`, `cmdk` and `sonner` are regular dependencies of the package.

## Import the styles

The package ships its default theme already compiled. Import the three stylesheets after Tailwind and point Tailwind at the package so it can see the class names used by the components:

```css
/* app/globals.css */
@import "tailwindcss";
@import "@jcsoftdev/ui/styles/tokens.css"; /* CSS variables: colors, radii, shadows, presets */
@import "@jcsoftdev/ui/styles/theme.css"; /* Tailwind v4 @theme mapping: bg-surface, text-ink, rounded-card... */
@import "@jcsoftdev/ui/styles/base.css"; /* focus ring, reduced motion, body defaults */
@source "../node_modules/@jcsoftdev/ui/dist"; /* lets Tailwind generate the utilities the components use */
```

`@jcsoftdev/ui/styles/fonts.css` is optional: it imports Figtree from Google Fonts. Skip it when your app loads fonts itself and override `--font-sans`.

## Use a component

```tsx
import { Button } from "@jcsoftdev/ui/atoms";
import { Kpi } from "@jcsoftdev/ui/containers";

export function Today() {
  return (
    <div className="grid gap-3">
      <Kpi label="Citas hoy" value="18" />
      <Button variant="primary">Reservar corte</Button>
    </div>
  );
}
```

Every component is also a single entry point, for example `@jcsoftdev/ui/atoms/button`. See [Tree-shaking and subpaths](/docs/subpaths/).

## Next.js

Components that hold state are marked `"use client"`, so they work from Server Components as long as you pass serializable props. The package is plain ESM; no `transpilePackages` is required.

```tsx
// app/layout.tsx
import { Figtree } from "next/font/google";
import "./globals.css";

const figtree = Figtree({ subsets: ["latin"], variable: "--font-figtree" });

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="es" className={figtree.variable} suppressHydrationWarning>
      <body>{children}</body>
    </html>
  );
}
```

```css
/* globals.css, after the imports */
:root {
  --font-sans: var(--font-figtree), ui-sans-serif, system-ui, sans-serif;
}
```

## Astro

Add `@astrojs/react` and the Tailwind Vite plugin, import the same stylesheets in a global CSS file and render components as islands (`client:visible` for heavy ones such as charts). This site is built that way.

## Vite

Use `@tailwindcss/vite`, import the stylesheets in your entry CSS and import components as usual. Nothing else is needed.

## Switch the look at runtime

Set attributes on `<html>` (or on any element, to restyle just its subtree):

```html
<html data-theme="dark" data-style="glass" data-accent="menta" data-density="compact"></html>
```

Read [Theming and presets](/docs/theming/) for every value and the precedence rules.

---

# Tree-shaking and subpaths

> Every @jcsoftdev/ui subpath and single-component entry point, and how to keep bundles small.

Source: https://ui.jcsoftdev.com/docs/subpaths

The package is unbundled ESM with `"sideEffects": ["**/*.css"]`: one output file per source file, so a bundler can reduce an import to the component you use and its own dependencies.

## Subpaths

| Import path | Components |
| --- | --- |
| `@jcsoftdev/ui/ai` | 15 |
| `@jcsoftdev/ui/atoms` | 17 |
| `@jcsoftdev/ui/brand` | 2 |
| `@jcsoftdev/ui/calendar` | 5 |
| `@jcsoftdev/ui/charts` | 95 |
| `@jcsoftdev/ui/containers` | 51 |
| `@jcsoftdev/ui/forms` | 21 |
| `@jcsoftdev/ui/navigation` | 8 |
| `@jcsoftdev/ui/overlays` | 39 |
| `@jcsoftdev/ui/palette` | 1 |
| `@jcsoftdev/ui/rich-text` | 2 |
| `@jcsoftdev/ui/shell` | 3 |
| `@jcsoftdev/ui/states` | 5 |
| `@jcsoftdev/ui/utils` | 0 |
| `@jcsoftdev/ui/xlsx` | 0 |

Also available: `@jcsoftdev/ui/styles/*` (CSS) and `@jcsoftdev/ui/tokens/*` (the tokens JSON).

## Single-component entries

Inside a group, components that live in their own folder also have an entry point. 155 are available, for example:

```ts
import {} from "@jcsoftdev/ui/ai/attachment";
import {} from "@jcsoftdev/ui/ai/chain-of-thought";
import {} from "@jcsoftdev/ui/ai/chat-list";
import {} from "@jcsoftdev/ui/ai/chat-message";
import {} from "@jcsoftdev/ui/ai/code-block";
import {} from "@jcsoftdev/ui/ai/conversation";
```

## Rules of thumb

- Prefer the group entry (`@jcsoftdev/ui/atoms`) in application code: it tree-shakes and reads well.
- Use a single-component entry when you need the smallest possible import graph, for example in an island that ships to the browser.
- Heavy features load lazily: the DataGrid chart panel and the XLSX writer are imported on demand.
- Add `@source` for the package `dist` folder so Tailwind generates the classes the components use.
- Compile the TypeScript yourself with the `source` export condition, which points at `src/*/index.ts`.

---

# Container queries

> Components respond to the width of their container, not the viewport, so they behave the same in a sidebar, a card or a dialog.

Source: https://ui.jcsoftdev.com/docs/container-queries

Every component adapts to the width of the box it is placed in. The library uses Tailwind v4 container queries (`@container`, `@sm:`, `@md:`...) and never viewport breakpoints (`sm:`, `md:`) inside components.

## Why it matters

A `KpiGroup` in a narrow sidebar and the same `KpiGroup` across a wide dashboard are the same component. No prop and no media query decides the layout; the container does.

```tsx
<div className="w-80">
  <KpiGroup items={items} /> {/* stacks */}
</div>
<div className="w-full">
  <KpiGroup items={items} /> {/* lays out in a row */}
</div>
```

## Charts measure their container

Charts use a `ResizeObserver` through `ChartFrame` and also adapt: fewer ticks, rotated or skipped labels, a legend that moves below, tooltips that stay inside the frame and data labels that hide when they do not fit. A chart fills its parent exactly, so give the parent a size:

```tsx
<div className="h-72">
  <LineChart series={series} categories={categories} height="fill" />
</div>
```

## Guarantees

- Nothing overflows horizontally at 320 px: long text truncates or wraps, tables scroll inside their own wrapper and toolbars wrap.
- Nested containers are named (for example `@container/kpi`) so they do not clash.
- The live examples on every component page have a width control (320, 480, 768, full) to check this.

## In your own layouts

Mark a wrapper as a container and style its children with container variants:

```tsx
<section className="@container">
  <div className="grid gap-3 @md:grid-cols-2 @3xl:grid-cols-4">...</div>
</section>
```

---

# Accessibility

> Keyboard support, focus management, reduced motion, contrast and data alternatives built into the components.

Source: https://ui.jcsoftdev.com/docs/accessibility

Accessibility is part of each component, not an add-on.

## Keyboard and semantics

- Interactive primitives (dialogs, menus, popovers, tabs, radio groups, switches, checkboxes) come from Radix, which implements the WAI-ARIA patterns.
- `DataGrid` follows the ARIA grid pattern with a roving tabindex and full keyboard navigation (arrows, Home/End, Enter/F2 to edit, Escape to cancel, Ctrl+Z/Y for undo and redo, Ctrl+V and Ctrl+D/R to paste and fill).
- Overlays return focus to the element that opened them.
- The AI `Conversation` is a `role="log"` region that follows new content until the user scrolls up, then offers a "jump to latest" button.

## Focus

A single token-driven focus ring is applied with `focus-visible` (`--focus-ring-width`, `--focus-ring-color`, `--focus-ring-offset`), so it follows every style preset. Controls never remove it.

## Motion

All animations (entrances, shimmer, streaming caret, chart transitions) honor `prefers-reduced-motion`. The base stylesheet also collapses animation and transition durations for users who ask for less motion.

## Color and contrast

Text and interactive tokens are chosen for contrast on their intended surfaces (the token notes list the measured ratios). Color is never the only signal: charts offer patterns, legends are toggleable buttons and series can be read as a data table.

## Charts

Charts expose an accessible name, an optional data table (`ChartDataTable`) and keyboard navigation across data points where the chart supports it. Tooltips are available on focus as well as hover.

## Labels and language

Every visible string and ARIA label is a prop, with English defaults. Pass translated strings for other locales.

## Testing

Stories run with the Storybook accessibility addon; component-level notes appear in the **Accessibility** section of a component page whenever the source documents them with `@a11y`, `@keyboard` or `@accessibility` JSDoc tags.

---

# Docs for LLMs

> llms.txt, llms-full.txt and a Markdown version of every page, generated from the same source as the HTML docs.

Source: https://ui.jcsoftdev.com/docs/llms

This site is readable by language models and coding agents without scraping HTML.

| URL                                | What it is                                                                                                                            |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| [`/llms.txt`](/llms.txt)           | Index in the [llms.txt](https://llmstxt.org) format: a title, a one-line summary and sections of links to Markdown pages.             |
| [`/llms-full.txt`](/llms-full.txt) | Every documentation page concatenated into one file, including all components with their props.                                       |
| `/docs/<page>.md`                  | The Markdown of a single page, for example [`/docs/getting-started.md`](/docs/getting-started.md) or `/docs/components/data-grid.md`. |
| `/manifest.json`                   | Machine-readable list of every component: name, category, import path, props and Storybook story ids.                                 |

Every page has **Copy page as Markdown** and **Open .md** buttons under its title.

## Same source as the human docs

The Markdown is produced from the same files as the HTML pages. Component pages are generated from the TypeScript source of `@jcsoftdev/ui` (exports, prop types, defaults, JSDoc) on every build, so an agent never sees stale props.

## Tips for agents

- Start from `/llms.txt`, then fetch only the component pages you need.
- Import path rule: a component is imported from its category, for example `@jcsoftdev/ui/containers`, or from a single-component entry such as `@jcsoftdev/ui/containers/data-grid`.
- Theming is attribute driven: `data-theme`, `data-accent`, `data-style`, `data-density`, `data-radius` on `<html>` or any element.
- Use semantic Tailwind utilities (`bg-surface-card`, `text-ink`, `rounded-card`) instead of literal colors.

---

# Theming and presets

> Zero-runtime theming with data-style, data-density, data-radius, data-accent and data-theme, plus precedence and custom token files.

Source: https://ui.jcsoftdev.com/docs/theming

The whole look comes from one tokens file, `tokens/default.json`. A build step turns it into CSS custom properties (`tokens.css`) and a Tailwind v4 theme (`theme.css`). At runtime nothing is computed in JavaScript: five attributes only remap CSS variables.

| Attribute      | Values                                                        | Default (no attribute)         |
| -------------- | ------------------------------------------------------------- | ------------------------------ |
| `data-theme`   | `light`, `dark`                                               | follows `prefers-color-scheme` |
| `data-accent`  | `durazno`, `menta`, `cielo`, `lavanda`, `orquidea`, `grafito` | Coral                          |
| `data-style`   | `soft`, `bordered`, `elevated`, `flat`, `glass`, `brutal`     | `soft`                         |
| `data-density` | `compact` (x0.875), `normal`, `comfortable` (x1.125)          | `normal`                       |
| `data-radius`  | `none`, `sm`, `md`, `lg`, `full`                              | the preset's own radii         |

```html
<html data-theme="dark" data-style="brutal" data-accent="cielo" data-density="comfortable">
  ...
  <section data-style="glass">only this subtree is glass</section>
</html>
```

## Style presets

Each preset changes shape, edge and elevation, not the palette:

- `soft`: hairline shadows instead of borders, pill buttons (the default).
- `bordered`: crisp 1px borders, no shadows, tighter radii.
- `elevated`: real shadows and a lifted card surface; has light and dark variants.
- `flat`: no shadows and no borders; surfaces separate by tone only.
- `glass`: translucent surfaces with backdrop blur; has light and dark variants.
- `brutal`: thick borders, hard offset shadows, square corners.

## Precedence

On a single element the order is source order at equal specificity: theme, then accent, then `data-style`, then `data-density`, then `data-radius`. `data-radius` also wins over a preset set on a descendant, because presets read `var(--radius-card-override, <own radius>)`. Presets never touch density tokens. There is no `!important` anywhere.

## Density

Density is a unitless `--density` that scales control heights, control and card padding and the `gap-density*` scale with `calc()`. Tailwind's global `--spacing` scale is not scaled.

## Using tokens in your own code

Use the semantic utilities so your UI follows the presets too:

| Concern          | Utilities                                                                               |
| ---------------- | --------------------------------------------------------------------------------------- |
| Radius           | `rounded-button`, `rounded-input`, `rounded-card`, `rounded-popover`, `rounded-chip`... |
| Edge             | `border-card`, `border-control`                                                         |
| Shadow           | `shadow-card`, `shadow-raised`, `shadow-overlay`, `shadow-control`                      |
| Surface          | `bg-surface-card`, `bg-surface-control`, `bg-surface-overlay`, `bg-surface-sunken`      |
| Density          | `h-control`, `h-input`, `px-control-x`, `p-card`, `gap-density`                         |
| Focus and motion | `focus-visible:focus-ring`, `pressable`, `ease-style`                                   |

The complete list of tokens, with light and dark values and usage notes, is generated on the [Design tokens](/docs/theming/tokens/) page.

## Your own tokens

Copy `tokens/default.json`, edit values (keep the same names) and run the CLI:

```bash
npx ui-theme build my-tokens.json --out src/theme
```

It writes `tokens.css`, `theme.css`, `fonts.css` and a Compose `Theme.kt` so a Kotlin app can share the tokens. Import your generated files instead of the shipped ones.

## Runtime switching with persistence

```ts
const root = document.documentElement;
root.dataset.style = "glass";
root.dataset.accent = "menta";
localStorage.setItem("preset", JSON.stringify({ style: "glass", accent: "menta" }));
```

Restore it from an inline script in `<head>` before first paint to avoid a flash. This site does exactly that.

---

# Design tokens

> Every design token of the default theme, generated from tokens/default.json.

Source: https://ui.jcsoftdev.com/docs/theming/tokens

Generated from `tokens/default.json` ("Barbershop default", schema v2). Usage notes are kept in the language of the token file (Spanish).

## Color

| Token | CSS variable | Light / dark | Usage |
| --- | --- | --- | --- |
| `bg` | `--bg` | `#f4f4f8` / `#000000` | Fondo de la página. En oscuro es negro puro: en pantallas AMOLED esos píxeles quedan apagados. |
| `surface` | `--surface` | `#ffffff` / `#0e0e10` | Tarjetas, barra lateral, campos y filas. En oscuro va apenas encendida sobre el negro. |
| `surface-2` | `--surface-2` | `#eeeef1` / `#1a1a1d` | Fila en hover, chip neutro y relleno de controles dentro de una tarjeta. |
| `sunken` | `--sunken` | `#e7e7ed` / `#232327` | Fondo hundido: avatar neutro y zonas de arrastre. |
| `float` | `--float` | `#ffffff` / `#141417` | Lo que flota sobre la página: diálogos, hojas, menús y la barra inferior de la app. En oscuro va un paso más clara que surface, porque ahí no hay sombras. |
| `line` | `--line` | `#e3e3e6` / `#1f1f23` | Líneas divisorias, borde de chips sin relleno y de bloques apagados. Decorativa: no delimita controles. |
| `line-strong` | `--line-strong` | `#d2d2dc` / `#303036` | Borde de bloques de cita y de botones de muestra. No llega a 3:1: el elemento se distingue por su relleno y su texto. |
| `line-control` | `--line-control` | `#85858f` / `#6e6e7a` | Borde de campos de texto, selects y casillas. Da 3.7:1 sobre surface en claro y 3.8:1 en oscuro. |
| `hair` | `--hair` | `rgba(0,0,0,.11)` / `rgba(255,255,255,.10)` | Filete de 0.67 px que rodea tarjetas y botones secundarios. Va dentro de shadow-flat y shadow-hero. |
| `track` | `--track` | `#dedee2` / `#232327` | Pista de barras de avance y de nivel de stock. |
| `seg-track` | `--seg-track` | `#e7e7ed` / `#151518` | Bandeja del control segmentado. |
| `seg-on` | `--seg-on` | `#ffffff` / `#2b2b30` | Opción elegida del control segmentado. Es neutra: el color de marca no se usa para selectores. |
| `ink` | `--ink` | `#000000` / `#f2f2f5` | Texto principal. En oscuro es un blanco roto para que no deslumbre sobre negro. |
| `ink-2` | `--ink-2` | `#4b4b57` / `#b6b6c1` | Texto secundario y etiquetas, sobre cualquier superficie. |
| `ink-3` | `--ink-3` | `#6d6d7a` / `#8c8c98` | Metadatos y encabezados de tabla, sobre bg y surface (4.6:1 sobre bg en claro). Sobre surface-2 usa ink-2. |
| `accent` | `--accent` | `#faa2a2` / `#faa2a2` | Relleno de marca: la acción principal y lo elegido (día, hora, turno que sigue). Es un pastel y no sirve como color de texto. Por defecto es Coral. |
| `on-accent` | `--on-accent` | `#3f191a` / `#3f191a` | Texto e iconos sobre un relleno accent: el tono profundo del mismo matiz (7.9:1). Igual en claro y en oscuro. |
| `accent-ink` | `--accent-ink` | `#a43a41` / `#ffb4b3` | Texto e iconos en color de marca, foco de teclado y elemento activo de navegación. Da 6.4:1 sobre surface en claro y 11.4:1 en oscuro. |
| `accent-word` | `--accent-word` | `#dc5d63` / `#faa2a2` | La palabra en color de un título grande y el interruptor encendido. Da 3.3:1 sobre bg: solo para texto de 24 px o más. |
| `accent-soft` | `--accent-soft` | `#ffebea` / `#261112` | Fondo suave de marca: cita en atención, ítem activo de navegación, aviso informativo. |
| `accent-line` | `--accent-line` | `#f6c2c1` / `#5b2e2f` | Filete de marca: borde de la cita en atención y de la tarjeta que resume lo que se está reservando. |
| `accent-2` | `--accent-2` | `#fec79e` / `#fec79e` | Tono vecino, 38° más allá en el círculo de color. Solo para el degradado detrás de la rueda de hora. |
| `pal-durazno-fill` | `--pal-durazno-fill` | `#efae75` / `#efae75` | Paleta Durazno: relleno. Reemplaza a accent con data-accent="durazno". |
| `pal-durazno-deep` | `--pal-durazno-deep` | `#3b1f02` / `#3b1f02` | Paleta Durazno: texto sobre el relleno. Reemplaza a on-accent con data-accent="durazno". |
| `pal-durazno-ink` | `--pal-durazno-ink` | `#905203` / `#f6be8e` | Paleta Durazno: texto en color. Reemplaza a accent-ink con data-accent="durazno". |
| `pal-durazno-word` | `--pal-durazno-word` | `#c97405` / `#efae75` | Paleta Durazno: palabra de título. Reemplaza a accent-word con data-accent="durazno". |
| `pal-durazno-soft` | `--pal-durazno-soft` | `#ffecde` / `#241406` | Paleta Durazno: fondo suave. Reemplaza a accent-soft con data-accent="durazno". |
| `pal-durazno-line` | `--pal-durazno-line` | `#eec9a9` / `#553515` | Paleta Durazno: filete. Reemplaza a accent-line con data-accent="durazno". |
| `pal-durazno-2` | `--pal-durazno-2` | `#e1d695` / `#e1d695` | Paleta Durazno: tono vecino. Reemplaza a accent-2 con data-accent="durazno". |
| `pal-menta-fill` | `--pal-menta-fill` | `#77d3ad` / `#77d3ad` | Paleta Menta: relleno. Reemplaza a accent con data-accent="menta". |
| `pal-menta-deep` | `--pal-menta-deep` | `#002f1f` / `#002f1f` | Paleta Menta: texto sobre el relleno. Reemplaza a on-accent con data-accent="menta". |
| `pal-menta-ink` | `--pal-menta-ink` | `#047554` / `#91debc` | Paleta Menta: texto en color. Reemplaza a accent-ink con data-accent="menta". |
| `pal-menta-word` | `--pal-menta-word` | `#03a578` / `#77d3ad` | Paleta Menta: palabra de título. Reemplaza a accent-word con data-accent="menta". |
| `pal-menta-soft` | `--pal-menta-soft` | `#e0f7eb` / `#061d14` | Paleta Menta: fondo suave. Reemplaza a accent-soft con data-accent="menta". |
| `pal-menta-line` | `--pal-menta-line` | `#addec7` / `#134834` | Paleta Menta: filete. Reemplaza a accent-line con data-accent="menta". |
| `pal-menta-2` | `--pal-menta-2` | `#8ee5ed` / `#8ee5ed` | Paleta Menta: tono vecino. Reemplaza a accent-2 con data-accent="menta". |
| `pal-cielo-fill` | `--pal-cielo-fill` | `#76c9f8` / `#76c9f8` | Paleta Cielo: relleno. Reemplaza a accent con data-accent="cielo". |
| `pal-cielo-deep` | `--pal-cielo-deep` | `#002a3e` / `#002a3e` | Paleta Cielo: texto sobre el relleno. Reemplaza a on-accent con data-accent="cielo". |
| `pal-cielo-ink` | `--pal-cielo-ink` | `#006c97` / `#8fd5fd` | Paleta Cielo: texto en color. Reemplaza a accent-ink con data-accent="cielo". |
| `pal-cielo-word` | `--pal-cielo-word` | `#0097d2` / `#76c9f8` | Paleta Cielo: palabra de título. Reemplaza a accent-word con data-accent="cielo". |
| `pal-cielo-soft` | `--pal-cielo-soft` | `#e1f3fe` / `#061b26` | Paleta Cielo: fondo suave. Reemplaza a accent-soft con data-accent="cielo". |
| `pal-cielo-line` | `--pal-cielo-line` | `#abd8f3` / `#12425a` | Paleta Cielo: filete. Reemplaza a accent-line con data-accent="cielo". |
| `pal-cielo-2` | `--pal-cielo-2` | `#c6d2ff` / `#c6d2ff` | Paleta Cielo: tono vecino. Reemplaza a accent-2 con data-accent="cielo". |
| `pal-lavanda-fill` | `--pal-lavanda-fill` | `#bab3fe` / `#bab3fe` | Paleta Lavanda: relleno. Reemplaza a accent con data-accent="lavanda". |
| `pal-lavanda-deep` | `--pal-lavanda-deep` | `#252142` / `#252142` | Paleta Lavanda: texto sobre el relleno. Reemplaza a on-accent con data-accent="lavanda". |
| `pal-lavanda-ink` | `--pal-lavanda-ink` | `#6152ad` / `#c7c2ff` | Paleta Lavanda: texto en color. Reemplaza a accent-ink con data-accent="lavanda". |
| `pal-lavanda-word` | `--pal-lavanda-word` | `#8979e6` / `#bab3fe` | Paleta Lavanda: palabra de título. Reemplaza a accent-word con data-accent="lavanda". |
| `pal-lavanda-soft` | `--pal-lavanda-soft` | `#efeeff` / `#171627` | Paleta Lavanda: fondo suave. Reemplaza a accent-soft con data-accent="lavanda". |
| `pal-lavanda-line` | `--pal-lavanda-line` | `#cecbf7` / `#3c375d` | Paleta Lavanda: filete. Reemplaza a accent-line con data-accent="lavanda". |
| `pal-lavanda-2` | `--pal-lavanda-2` | `#f2c1f3` / `#f2c1f3` | Paleta Lavanda: tono vecino. Reemplaza a accent-2 con data-accent="lavanda". |
| `pal-orquidea-fill` | `--pal-orquidea-fill` | `#eaa3d5` / `#eaa3d5` | Paleta Orquídea: relleno. Reemplaza a accent con data-accent="orquidea". |
| `pal-orquidea-deep` | `--pal-orquidea-deep` | `#391a31` / `#391a31` | Paleta Orquídea: texto sobre el relleno. Reemplaza a on-accent con data-accent="orquidea". |
| `pal-orquidea-ink` | `--pal-orquidea-ink` | `#933e7f` / `#f2b4df` | Paleta Orquídea: texto en color. Reemplaza a accent-ink con data-accent="orquidea". |
| `pal-orquidea-word` | `--pal-orquidea-word` | `#c861ad` / `#eaa3d5` | Paleta Orquídea: palabra de título. Reemplaza a accent-word con data-accent="orquidea". |
| `pal-orquidea-soft` | `--pal-orquidea-soft` | `#fee9f7` / `#23121e` | Paleta Orquídea: fondo suave. Reemplaza a accent-soft con data-accent="orquidea". |
| `pal-orquidea-line` | `--pal-orquidea-line` | `#ecc2df` / `#532f49` | Paleta Orquídea: filete. Reemplaza a accent-line con data-accent="orquidea". |
| `pal-orquidea-2` | `--pal-orquidea-2` | `#fec2c5` / `#fec2c5` | Paleta Orquídea: tono vecino. Reemplaza a accent-2 con data-accent="orquidea". |
| `pal-grafito-fill` | `--pal-grafito-fill` | `#26262b` / `#ececf0` | Paleta Grafito: relleno. Reemplaza a accent con data-accent="grafito". |
| `pal-grafito-deep` | `--pal-grafito-deep` | `#ffffff` / `#1a1a1e` | Paleta Grafito: texto sobre el relleno. Reemplaza a on-accent con data-accent="grafito". |
| `pal-grafito-ink` | `--pal-grafito-ink` | `#26262b` / `#ececf0` | Paleta Grafito: texto en color. Reemplaza a accent-ink con data-accent="grafito". |
| `pal-grafito-word` | `--pal-grafito-word` | `#8a8a94` / `#a3a3ad` | Paleta Grafito: palabra de título. Reemplaza a accent-word con data-accent="grafito". |
| `pal-grafito-soft` | `--pal-grafito-soft` | `#ececf0` / `#1d1d21` | Paleta Grafito: fondo suave. Reemplaza a accent-soft con data-accent="grafito". |
| `pal-grafito-line` | `--pal-grafito-line` | `#c6c6cf` / `#3a3a42` | Paleta Grafito: filete. Reemplaza a accent-line con data-accent="grafito". |
| `pal-grafito-2` | `--pal-grafito-2` | `#b9b9c6` / `#5a5a66` | Paleta Grafito: tono vecino. Reemplaza a accent-2 con data-accent="grafito". |
| `danger` | `--danger` | `#c51f1c` / `#ff9689` | Error, ausencia y stock bajo el mínimo. Como texto, sobre surface y danger-soft. Más saturado que Coral para no confundirse con la marca. |
| `danger-soft` | `--danger-soft` | `#ffebe8` / `#300f0b` | Fondo de la cita con ausencia y del chip de error. |
| `warning` | `--warning` | `#865900` / `#ebc166` | Algo que pide atención hoy: cliente que llegó y espera, stock cerca del mínimo. |
| `warning-soft` | `--warning-soft` | `#feefcf` / `#241900` | Fondo de la cita cuyo cliente ya llegó y del chip de aviso. |
| `success` | `--success` | `#0b7643` / `#80dba2` | Terminado y en nivel. Solo comunica estado. |
| `success-soft` | `--success-soft` | `#dff8e6` / `#062111` | Fondo del chip de éxito y del aviso de proceso cerrado. |
| `hatch` | `--hatch` | `#e6e6ec` / `#1b1b1f` | Trama diagonal: tiempo que no se puede reservar (fuera de horario, descanso, hora ocupada, reposo de un servicio). |
| `scrim` | `--scrim` | `rgba(0,0,0,.2)` / `rgba(0,0,0,.72)` | Velo detrás de diálogos y hojas. |
| `toast-bg` | `--toast-bg` | `#000000` / `#222226` | Fondo del aviso breve. En oscuro es un gris, no blanco: sería lo más brillante de la pantalla. |
| `toast-ink` | `--toast-ink` | `#ffffff` / `#f2f2f5` | Texto y botón del aviso breve. |
| `chart-cat-1` | `--chart-cat-1` | `#2f7fc1` / `#6db8f2` | Gráficos: color de la serie 2 (Azul cielo). La serie 1 siempre usa accent-word; las demás siguen este orden. |
| `chart-cat-2` | `--chart-cat-2` | `#12936f` / `#5fd0a6` | Gráficos: color de la serie 3 (Verde menta). La serie 1 siempre usa accent-word; las demás siguen este orden. |
| `chart-cat-3` | `--chart-cat-3` | `#c7820f` / `#f0b85a` | Gráficos: color de la serie 4 (Ámbar). La serie 1 siempre usa accent-word; las demás siguen este orden. |
| `chart-cat-4` | `--chart-cat-4` | `#6d5bd8` / `#aea3fb` | Gráficos: color de la serie 5 (Lavanda). La serie 1 siempre usa accent-word; las demás siguen este orden. |
| `chart-cat-5` | `--chart-cat-5` | `#bd4b95` / `#ee9bd2` | Gráficos: color de la serie 6 (Orquídea). La serie 1 siempre usa accent-word; las demás siguen este orden. |
| `chart-cat-6` | `--chart-cat-6` | `#5f6b7d` / `#a5aebb` | Gráficos: color de la serie 7 (Pizarra). La serie 1 siempre usa accent-word; las demás siguen este orden. |
| `chart-cat-7` | `--chart-cat-7` | `#788f22` / `#bcd56b` | Gráficos: color de la serie 8 (Oliva). La serie 1 siempre usa accent-word; las demás siguen este orden. |
| `chart-cat-reserve` | `--chart-cat-reserve` | `#dc5d63` / `#f48f93` | Color de categoría de reserva: reemplaza al color de categoría que se parece al acento activo (ver chartSwaps). |
| `chart-grid` | `--chart-grid` | `rgba(0,0,0,.06)` / `rgba(255,255,255,.07)` | Gráficos: líneas guía del fondo. Más suaves que line para que los datos manden. |
| `chart-crosshair` | `--chart-crosshair` | `rgba(0,0,0,.30)` / `rgba(255,255,255,.34)` | Gráficos: línea vertical que sigue al puntero y franja de la categoría en barras. |
| `chart-up` | `--chart-up` | `#0f8a55` / `#5fd69b` | Gráficos: valor que sube (vela alcista, aumento en cascada, línea ascendente). Verde propio, distinto de la serie Verde menta. |
| `chart-down` | `--chart-down` | `#d23b35` / `#ff8f82` | Gráficos: valor que baja (vela bajista, disminución en cascada, línea descendente). |
| `chart-total` | `--chart-total` | `#3e4656` / `#c3cad6` | Gráficos: totales y subtotales de cascada, y valores sin cambio. |

## Spacing

| Token | CSS variable | Value | Usage |
| --- | --- | --- | --- |
| `space-2` | `--space-2` | `2px` | Separación dentro de un control segmentado. |
| `space-4` | `--space-4` | `4px` | Margen interior de un bloque de cita. |
| `space-6` | `--space-6` | `6px` | Entre icono y texto en un botón o chip. |
| `space-8` | `--space-8` | `8px` | Entre botones de una barra de acciones. |
| `space-10` | `--space-10` | `10px` | Entre icono y texto en la navegación. |
| `space-12` | `--space-12` | `12px` | Relleno vertical de filas y cabeceras de tarjeta. |
| `space-14` | `--space-14` | `14px` | Relleno del cuerpo de tarjeta y separación de campos en un formulario. |
| `space-16` | `--space-16` | `16px` | Relleno horizontal de tarjetas, filas y celdas; separación entre tarjetas. |
| `space-18` | `--space-18` | `18px` | Separación entre bloques de una vista. |
| `space-28` | `--space-28` | `28px` | Margen lateral del contenido en escritorio. En móvil baja a space-16. |

## Radius

| Token | CSS variable | Value | Usage |
| --- | --- | --- | --- |
| `radius-xs` | `--radius-xs` | `4px` | Rótulo sobre una trama y tecla. |
| `radius-chip` | `--radius-chip` | `6px` | Chip cuadrado de tipo. |
| `radius-event` | `--radius-event` | `10px` | Bloque de cita y botón de hora en el panel. |
| `radius-control` | `--radius-control` | `12px` | Campos de texto, ítems de navegación y días de la semana. |
| `radius-tile` | `--radius-tile` | `12px` | Marca del negocio y botón de usuario. |
| `radius-banner` | `--radius-banner` | `14px` | Avisos dentro de la página. |
| `radius-card` | `--radius-card` | `16px` | Tarjetas, chips altos de la app y bloques de la línea de tiempo. |
| `radius-dialog` | `--radius-dialog` | `20px` | Diálogos del panel. |
| `radius-sheet` | `--radius-sheet` | `36px` | Hoja inferior flotante de la app, a 8 px de los bordes. |
| `radius-pill` | `--radius-pill` | `999px` | Botones, chips, bandejas y avatares. |

## Shadow

| Token | CSS variable | Value | Usage |
| --- | --- | --- | --- |
| `shadow-flat` | `--shadow-flat` | `0 0 0 .67px rgba(0,0,0,.11),0 1px 2px rgba(0,0,0,.04)` / `0 0 0 1px rgba(255,255,255,.09)` | Tarjetas y botones secundarios: un filete y casi nada de sombra. |
| `shadow-hero` | `--shadow-hero` | `0 0 0 .67px rgba(0,0,0,.11),0 4px 18px rgba(0,0,0,.10)` / `0 0 0 1px rgba(255,255,255,.10)` | La única tarjeta elevada de una vista: el cliente actual, o quien sigue en la cola. |
| `shadow-cta` | `--shadow-cta` | `0 8px 36px rgba(0,0,0,.065)` / `0 0 0 0 rgba(0,0,0,0)` | Botón principal de 54 px en la app. Gris neutra, nunca teñida del color de marca. |
| `shadow-sel` | `--shadow-sel` | `0 2px 8px rgba(0,0,0,.10)` / `0 0 0 0 rgba(0,0,0,0)` | Píldora elegida: día, hora, opción de un control segmentado. |
| `shadow-pop` | `--shadow-pop` | `0 0 0 .67px rgba(0,0,0,.11),0 18px 48px -12px rgba(0,0,0,.22)` / `0 0 0 1px rgba(255,255,255,.12)` | Diálogos, hojas, menús y avisos. En oscuro no hay sombras: sobre negro no se ven, y la profundidad va en filetes. |

## Size

| Token | CSS variable | Value | Usage |
| --- | --- | --- | --- |
| `side-width` | `--side-width` | `244px` | Ancho de la barra lateral. |
| `top-height` | `--top-height` | `58px` | Alto de la barra superior. |
| `control-height` | `--control-height` | `36px` | Alto de botones del panel. |
| `control-height-sm` | `--control-height-sm` | `30px` | Alto de botones dentro de filas. |
| `input-height` | `--input-height` | `38px` | Alto de campos de texto y de botones de hora. |
| `agenda-hour` | `--agenda-hour` | `48px` | Alto de una hora en la agenda del panel. |
| `agenda-col` | `--agenda-col` | `148px` | Ancho mínimo de la columna de un profesional. |
| `m-button` | `--m-button` | `54px` | Alto del botón principal en la app. |
| `m-tray` | `--m-tray` | `52px` | Alto de una bandeja en la app: control segmentado y muestras de color, con relleno interior de 4 px. |
| `m-chip` | `--m-chip` | `60px` | Alto de un chip de sugerencia en la app. |
| `m-hour` | `--m-hour` | `78px` | Alto de una hora en la línea de tiempo de la app. |

## Typography

### Títulos

| Style | Size / line height | Weight | Usage |
| --- | --- | --- | --- |
| `kpi-number` | `30px / 1.15` | 800 | Cifra de un indicador: citas de hoy, en espera, ítems bajo mínimo. |
| `page-title` | `26px / 1.18` | 800 | Título de página del panel. Uno por vista; puede llevar una palabra en accent-word. |
| `dialog-title` | `16px / 1.4` | 750 | Título de diálogo y de panel lateral. |
| `card-title` | `14px / 1.5` | 700 | Título de tarjeta. |

### Texto

| Style | Size / line height | Weight | Usage |
| --- | --- | --- | --- |
| `lede` | `14.5px / 1.5` | 400 | Frase bajo el título de página, en ink-2. Máximo 68 caracteres por línea. |
| `body` | `14px / 1.5` | 400 | Texto base del panel. |
| `row-title` | `13.5px / 1.5` | 650 | Nombre del cliente, del servicio o del ítem en filas y tablas. |
| `control` | `13px / 1.5` | 650 | Etiqueta de botones. |
| `meta` | `12.5px / 1.5` | 400 | Metadatos bajo un título de fila, en ink-3. |
| `chip-text` | `12px / 1` | 650 | Texto de chips de estado. |
| `overline` | `11px / 1.5` | 700 | Encabezado de tabla y rótulo de grupo en el panel. En mayúsculas y en ink-3. No se usa en la app móvil. |

### Datos

| Style | Size / line height | Weight | Usage |
| --- | --- | --- | --- |
| `clock` | `17px / 1` | 700 | Número del día en la tira de la semana. Cifras tabulares. |
| `data` | `12.5px / 1.6` | 600 | Horas, duraciones, cantidades, precios y códigos. Misma familia, con cifras tabulares (clase mono). |
| `count` | `11px / 1` | 700 | Contador en navegación y pestañas. |

### App móvil

| Style | Size / line height | Weight | Usage |
| --- | --- | --- | --- |
| `m-title` | `34px / 41px` | 800 | Título de pantalla en la app, con una palabra en accent-word. |
| `m-card-title` | `26px / 1.1` | 800 | Nombre del cliente en la tarjeta principal. |
| `m-row-title` | `15.5px / 1.3` | 700 | Nombre en un bloque de la línea de tiempo y en filas. |
| `m-body` | `15px / 1.45` | 400 | Texto bajo el título de pantalla. |
| `m-button` | `15.5px / 1` | 700 | Etiqueta del botón principal de 54 px. |
| `m-meta` | `13px / 1.4` | 400 | Segunda línea de un bloque o fila. |

## Style presets

Selected with `data-style` on any element. Each preset remaps the style tokens below.

| Preset | Attribute | Description |
| --- | --- | --- |
| Suave | `data-style="soft"` | El estilo por defecto: filetes finos en vez de bordes, sombras mínimas, botones píldora. |
| Con bordes | `data-style="bordered"` | Bordes nítidos de 1 px y ninguna sombra. Radios más cerrados. |
| Elevado | `data-style="elevated"` | Sombras en capas y ningún borde. En oscuro las superficies se aclaran por nivel. |
| Plano | `data-style="flat"` | Sin bordes ni sombras: las tarjetas se separan por un relleno teñido. Los overlays conservan un filete para despegarse de la página. |
| Vidrio | `data-style="glass"` | Superficies translúcidas con desenfoque y filetes claros, sobre un fondo de página degradado. |
| Brutal | `data-style="brutal"` | Bordes gruesos de tinta, sombras duras desplazadas y esquinas rectas. |

### Style tokens

| Token | CSS variable | Default (soft) | Usage |
| --- | --- | --- | --- |
| `radius-button` | `--radius-button` | `999px` | Botones. Píldora en el estilo suave. |
| `radius-input` | `--radius-input` | `12px` | Campos de texto, selects y casillas de hora. |
| `radius-badge` | `--radius-badge` | `999px` | Chips y pastillas de estado. |
| `radius-avatar` | `--radius-avatar` | `999px` | Avatares. data-radius no lo cambia: un avatar sigue siendo redondo salvo que el estilo diga otra cosa. |
| `radius-popover` | `--radius-popover` | `14px` | Menús, popovers y tooltips. |
| `border-width-card` | `--border-width-card` | `0px` | Grosor del borde de tarjetas. En suave es 0: el filete va en shadow-card. |
| `border-color-card` | `--border-color-card` | `var(--hair)` | Color del borde de tarjetas. |
| `border-width-control` | `--border-width-control` | `1px` | Grosor del borde de campos y controles. |
| `border-color-control` | `--border-color-control` | `var(--line-control)` | Color del borde de campos y controles. |
| `border-width-divider` | `--border-width-divider` | `1px` | Grosor de las líneas divisorias. |
| `border-color-divider` | `--border-color-divider` | `var(--line)` | Color de las líneas divisorias. |
| `shadow-card` | `--shadow-card` | `var(--shadow-flat)` | Sombra de tarjeta. Va junto a border-card: en suave es el filete de shadow-flat. |
| `shadow-raised` | `--shadow-raised` | `var(--shadow-hero)` | Tarjeta elevada. Incluye su propio filete. |
| `shadow-overlay` | `--shadow-overlay` | `var(--shadow-pop)` | Diálogos, hojas, menús y popovers. Incluye su propio filete. |
| `shadow-control` | `--shadow-control` | `var(--shadow-flat)` | Botón secundario y controles sin borde. |
| `shadow-selected` | `--shadow-selected` | `var(--shadow-sel)` | Opción elegida de un control segmentado, día u hora. |
| `shadow-inset` | `--shadow-inset` | `inset 0 1px 2px rgba(0,0,0,.06)` / `inset 0 0 0 1px rgba(255,255,255,.05)` | Zona hundida: pista, bandeja. |
| `shadow-inset-accent` | `--shadow-inset-accent` | `inset 0 0 0 1px var(--accent-line)` | Filete interior de marca: chip o día destacado. |
| `shadow-pinned-start` | `--shadow-pinned-start` | `6px 0 8px -6px rgba(0,0,0,.28)` / `1px 0 0 rgba(255,255,255,.10),6px 0 10px -6px rgba(0,0,0,.9)` | Borde de una columna fijada al inicio de una tabla cuando hay desplazamiento. |
| `shadow-pinned-end` | `--shadow-pinned-end` | `-6px 0 8px -6px rgba(0,0,0,.28)` / `-1px 0 0 rgba(255,255,255,.10),-6px 0 10px -6px rgba(0,0,0,.9)` | Borde de una columna fijada al final de una tabla cuando hay desplazamiento. |
| `surface-alpha` | `--surface-alpha` | `1` | Opacidad de las superficies (0 a 1). Solo baja en el estilo vidrio. |
| `surface-blur` | `--surface-blur` | `0px` | Desenfoque detrás de superficies translúcidas. |
| `surface-filter` | `--surface-filter` | `none` | backdrop-filter de tarjetas y overlays. none salvo en vidrio: un filtro activo crea un bloque contenedor. |
| `surface-card` | `--surface-card` | `var(--surface)` | Fondo de tarjetas. |
| `surface-control` | `--surface-control` | `var(--surface)` | Fondo de campos y botones secundarios. |
| `surface-overlay` | `--surface-overlay` | `var(--float)` | Fondo de diálogos, hojas, menús y popovers. |
| `surface-sunken` | `--surface-sunken` | `var(--sunken)` | Fondo hundido: pistas, zonas de arrastre. |
| `surface-backdrop` | `--surface-backdrop` | `var(--scrim)` | Velo detrás de diálogos y hojas. |
| `page-backdrop` | `--page-backdrop` | `none` | Imagen de fondo de la página. Solo el estilo vidrio la usa, para que la translucidez se note. |
| `focus-ring-width` | `--focus-ring-width` | `2px` | Grosor del anillo de foco. |
| `focus-ring-offset` | `--focus-ring-offset` | `2px` | Separación del anillo de foco. |
| `focus-ring-color` | `--focus-ring-color` | `var(--accent-ink)` | Color del anillo de foco. |
| `motion-duration` | `--motion-duration` | `180ms` | Duración de transiciones de estado. |
| `motion-ease` | `--motion-ease` | `cubic-bezier(.2,.8,.2,1)` | Curva de las transiciones. |
| `press-scale` | `--press-scale` | `.97` | Escala de un control al presionarlo. |
| `font-scale` | `--font-scale` | `1` | Factor opcional para escalar texto. Ningún token de texto lo usa todavía. |

### Density tokens

| Token | CSS variable | Default | Usage |
| --- | --- | --- | --- |
| `density` | `--density` | `1` | Factor de densidad sin unidad. Lo fija data-density; los altos y rellenos de abajo se multiplican por él. |
| `pad-control-x` | `--pad-control-x` | `16px` | Relleno horizontal de botones y campos. |
| `pad-card` | `--pad-card` | `16px` | Relleno de tarjetas. |
| `gap-density-sm` | `--gap-density-sm` | `8px` | Separación corta entre elementos de un grupo. |
| `gap-density` | `--gap-density` | `12px` | Separación entre elementos de una lista o formulario. |
| `gap-density-lg` | `--gap-density-lg` | `18px` | Separación entre bloques de una vista. |

Density levels (`data-density`):

- `data-density="compact"`: Compacta
- `data-density="normal"`: Normal
- `data-density="comfortable"`: Cómoda

Radius levels (`data-radius`):

- `data-radius="none"`: Sin radio
- `data-radius="sm"`: Pequeño
- `data-radius="md"`: Medio
- `data-radius="lg"`: Grande
- `data-radius="full"`: Completo

---

# Attachment

> File chip or preview tile for prompt attachments, with an optional remove button.

Source: https://ui.jcsoftdev.com/docs/components/attachment

File chip or preview tile for prompt attachments, with an optional remove button.

## Import

```ts
import { Attachment } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/attachment`.

## Usage

```tsx
<Attachment
  name="agenda-sabado.pdf"
  size="240 KB"
  variant="chip"
  status="done"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` * | `string` |  |  |
| `size` | `string` |  | Pre-formatted size, e.g. `240 KB`. |
| `previewSrc` | `string` |  | Image URL (or object URL). Without it a document icon is shown. |
| `status` | `"done" \| "uploading" \| "error"` | `"done"` |  |
| `progress` | `number` |  | 0-100, only for `uploading`. |
| `variant` | `"chip" \| "preview"` | `"chip"` | `chip` is one compact line; `preview` is a tile with a larger thumbnail. |
| `onRemove` | `(() => void)` |  | Shows the remove button. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/ai-attachment--default)
- [Uploading](/storybook/?path=/story/ai-attachment--uploading)
- [Failed](/storybook/?path=/story/ai-attachment--failed)
- [Preview](/storybook/?path=/story/ai-attachment--preview)
- [Narrow](/storybook/?path=/story/ai-attachment--narrow)
- [Preset Brutal](/storybook/?path=/story/ai-attachment--preset-brutal)

## Source

`packages/ui/src/ai/attachment/attachment.tsx`

---

# ChainOfThought

> Collapsible list of reasoning steps with a status rail.

Source: https://ui.jcsoftdev.com/docs/components/chain-of-thought

Collapsible list of reasoning steps with a status rail.

## Import

```ts
import { ChainOfThought } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/chain-of-thought`.

## Usage

```tsx
<ChainOfThought
  title="Razonamiento"
  duration="4 s"
  defaultOpen
  steps={[
      {
        id: "1",
        label: "Entender el pedido",
        detail: "El cliente quiere un turno el sábado por la mañana.",
        status: "done",
      },
      {
        id: "2",
        label: "Consultar la agenda de Diego",
        detail: "Tres huecos libres entre 10:00 y 12:00.",
        status: "done",
      },
      { id: "3", label: "Proponer el horario más cercano", status: "done" },
    ]}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` * | `ThoughtStep[]` |  |  |
| `title` | `string` | `"Razonamiento"` | Header text; while any step is `active` it shimmers. |
| `duration` | `string` |  | Pre-formatted total time shown in the header, e.g. `4 s`. |
| `open` | `boolean` |  |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `((open: boolean) => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/ai-chainofthought--default)
- [Thinking](/storybook/?path=/story/ai-chainofthought--thinking)
- [Collapsed](/storybook/?path=/story/ai-chainofthought--collapsed)
- [Narrow](/storybook/?path=/story/ai-chainofthought--narrow)
- [Preset Brutal](/storybook/?path=/story/ai-chainofthought--preset-brutal)

## Source

`packages/ui/src/ai/chain-of-thought/chain-of-thought.tsx`

---

# ChatList

> Sidebar list of conversations grouped by date (Hoy, Ayer, Últimos 7 días…).

Source: https://ui.jcsoftdev.com/docs/components/chat-list

Sidebar list of conversations grouped by date (Hoy, Ayer, Últimos 7 días…).

## Import

```ts
import { ChatList } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/chat-list`.

## Usage

```tsx
<ChatList items={ITEMS} activeId="2" now={NOW} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` * | `ChatListItem[]` |  |  |
| `activeId` | `string` |  |  |
| `onSelect` | `((id: string) => void)` |  |  |
| `onNew` | `(() => void)` |  |  |
| `onDelete` | `((id: string) => void)` |  | Shows a delete button per row. |
| `now` | `string \| number \| Date` |  | Reference date for the groups; defaults to the current time. Pass it for stable output. |
| `label` | `string` | `"Conversaciones"` | Accessible name of the navigation landmark. |
| `emptyText` | `string` | `"Aún no hay conversaciones."` |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/ai-chatlist--default)
- [Interactive](/storybook/?path=/story/ai-chatlist--interactive)
- [Empty](/storybook/?path=/story/ai-chatlist--empty)
- [Narrow](/storybook/?path=/story/ai-chatlist--narrow)
- [Preset Brutal](/storybook/?path=/story/ai-chatlist--preset-brutal)

## Source

`packages/ui/src/ai/chat-list/chat-list.tsx`

---

# ChatMessage

> One chat turn: avatar, bubble, status, streaming caret and an optional footer slot.

Source: https://ui.jcsoftdev.com/docs/components/chat-message

One chat turn: avatar, bubble, status, streaming caret and an optional footer slot.

## Import

```ts
import { ChatMessage } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/chat-message`.

## Usage

```tsx
<ChatMessage
  author="assistant"
  name="Asistente"
  status="done"
  time="10:42"
  content="Mañana tienes **tres huecos libres** con Diego: `10:00`, `11:30` y `16:00`. ¿Quieres que reserve alguno?"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `author` * | `"user" \| "assistant" \| "system"` |  |  |
| `name` | `string` |  | Display name, also the avatar's accessible name. |
| `avatarSrc` | `string` |  |  |
| `status` | `"done" \| "error" \| "sending" \| "streaming"` | `"done"` | `sending` and `streaming` show activity; `error` shows the failure line. |
| `time` | `string` |  | Time label shown under the bubble (already formatted). |
| `content` | `string` |  | Markdown text. Assistant messages render it as Markdown; user and system as plain text. |
| `children` | `ReactNode` |  | Rich body; replaces `content`. |
| `footer` | `ReactNode` |  | Slot under the bubble (e.g. MessageActions, sources). |
| `errorText` | `string` | `"No se pudo enviar el mensaje."` | Text of the failure line when `status` is `error`. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/ai-chatmessage--default)
- [User](/storybook/?path=/story/ai-chatmessage--user)
- [System](/storybook/?path=/story/ai-chatmessage--system)
- [Streaming](/storybook/?path=/story/ai-chatmessage--streaming)
- [Waiting](/storybook/?path=/story/ai-chatmessage--waiting)
- [Failed](/storybook/?path=/story/ai-chatmessage--failed)
- [With Actions](/storybook/?path=/story/ai-chatmessage--with-actions)
- [Narrow](/storybook/?path=/story/ai-chatmessage--narrow)
- [Preset Brutal](/storybook/?path=/story/ai-chatmessage--preset-brutal)

## Source

`packages/ui/src/ai/chat-message/chat-message.tsx`

---

# CodeBlock

> Code with a language label, a copy button and a dependency-free syntax highlighter.

Source: https://ui.jcsoftdev.com/docs/components/code-block

Code with a language label, a copy button and a dependency-free syntax highlighter.

## Import

```ts
import { CodeBlock } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/code-block`.

## Usage

```tsx
<CodeBlock code={TS} language="ts" wrap={false} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `code` * | `string` |  |  |
| `language` | `string` |  | `ts`, `js`, `json`, `bash`, `go` or `sql` (aliases like `typescript` work); anything else is plain. |
| `filename` | `string` |  | Optional file name shown instead of the language label. |
| `wrap` | `boolean` |  | Wrap long lines instead of scrolling horizontally. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/ai-codeblock--default)
- [Narrow](/storybook/?path=/story/ai-codeblock--narrow)
- [Json](/storybook/?path=/story/ai-codeblock--json)
- [Bash](/storybook/?path=/story/ai-codeblock--bash)
- [Go](/storybook/?path=/story/ai-codeblock--go)
- [Sql](/storybook/?path=/story/ai-codeblock--sql)
- [Preset Brutal](/storybook/?path=/story/ai-codeblock--preset-brutal)

## Source

`packages/ui/src/ai/code-block/code-block.tsx`

---

# Conversation

> Scrollable message log that sticks to the bottom while new content streams in.

Source: https://ui.jcsoftdev.com/docs/components/conversation

Scrollable message log that sticks to the bottom while new content streams in. Scrolling up
pauses the follow behavior and reveals a "jump to latest" button. Fills its parent's height.

## Import

```ts
import { Conversation } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/conversation`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Conversation {...args}>
      <History count={10} />
    </Conversation>
  ),
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Conversación"` | Accessible name of the message log. |
| `jumpLabel` | `string` | `"Ir al último mensaje"` | Label of the "jump to latest" button. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/ai-conversation--default)
- [Growing History](/storybook/?path=/story/ai-conversation--growing-history)
- [Narrow](/storybook/?path=/story/ai-conversation--narrow)
- [Preset Brutal](/storybook/?path=/story/ai-conversation--preset-brutal)

## Source

`packages/ui/src/ai/conversation/conversation.tsx`

---

# Loader

> Animated waiting indicator.

Source: https://ui.jcsoftdev.com/docs/components/loader

Animated waiting indicator. With reduced motion the dots stay still.

## Import

```ts
import { Loader } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/loader`.

## Usage

```tsx
<Loader variant="dots" size="md" label="Escribiendo…" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"dots" \| "typing"` | `"dots"` | `dots` is the bare indicator; `typing` wraps it in a bubble with a label. |
| `size` | `"sm" \| "md"` | `"md"` |  |
| `label` | `string` | `"Escribiendo…"` | Spoken label (`role="status"`); shown as text in the `typing` variant. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/ai-loader--default)
- [Typing](/storybook/?path=/story/ai-loader--typing)
- [Narrow](/storybook/?path=/story/ai-loader--narrow)
- [Preset Brutal](/storybook/?path=/story/ai-loader--preset-brutal)

## Source

`packages/ui/src/ai/loader/loader.tsx`

---

# Markdown

> Safe Markdown renderer: headings, lists, emphasis, inline code, code fences, quotes, tables and links.

Source: https://ui.jcsoftdev.com/docs/components/markdown

Safe Markdown renderer: headings, lists, emphasis, inline code, code fences, quotes, tables
and links. It builds React elements from a parsed AST, so no input ever reaches innerHTML.

## Import

```ts
import { Markdown } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/markdown`.

## Usage

```tsx
<Markdown streaming={false}>
  {SAMPLE}
</Markdown>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` * | `string` |  | Markdown source. Raw HTML is shown as text; only http, https and mailto links are active. |
| `streaming` | `boolean` |  | Shows a blinking caret after the last character, for streaming answers. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/ai-markdown--default)
- [Narrow](/storybook/?path=/story/ai-markdown--narrow)
- [Streaming](/storybook/?path=/story/ai-markdown--streaming)
- [Safe By Default](/storybook/?path=/story/ai-markdown--safe-by-default)
- [Preset Brutal](/storybook/?path=/story/ai-markdown--preset-brutal)

## Source

`packages/ui/src/ai/markdown/markdown.tsx`

---

# MessageActions

> Copy, regenerate, like and dislike for an assistant message.

Source: https://ui.jcsoftdev.com/docs/components/message-actions

Copy, regenerate, like and dislike for an assistant message. Feedback toggles off on re-press.

## Import

```ts
import { MessageActions } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/message-actions`.

## Usage

```tsx
<MessageActions
  text="Tienes tres huecos libres mañana: 10:00, 11:30 y 16:00."
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` * | `string` |  | Text copied by the copy button. |
| `onCopy` | `((text: string) => void)` |  |  |
| `onRegenerate` | `(() => void)` |  | Omit to hide the regenerate button. |
| `onFeedback` | `((value: MessageFeedback) => void)` |  | Omit to hide the like/dislike buttons. |
| `feedback` | `null \| "like" \| "dislike"` |  |  |
| `defaultFeedback` | `null \| "like" \| "dislike"` | `null` |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/ai-messageactions--default)
- [Liked](/storybook/?path=/story/ai-messageactions--liked)
- [Copy Only](/storybook/?path=/story/ai-messageactions--copy-only)
- [Narrow](/storybook/?path=/story/ai-messageactions--narrow)
- [Preset Brutal](/storybook/?path=/story/ai-messageactions--preset-brutal)

## Source

`packages/ui/src/ai/message-actions/message-actions.tsx`

---

# PromptInput

> Composer: autosizing textarea, Enter to send, Shift+Enter for a new line, attachments slot and a stop button while a response streams.

Source: https://ui.jcsoftdev.com/docs/components/prompt-input

Composer: autosizing textarea, Enter to send, Shift+Enter for a new line, attachments slot
and a stop button while a response streams.

## Import

```ts
import { PromptInput } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/prompt-input`.

## Usage

```tsx
<PromptInput
  placeholder="Pregunta por turnos, clientes o ingresos…"
  hint="Enter envía · Shift+Enter agrega una línea"
  streaming={false}
  disabled={false}
  maxRows={6}
  actions={attach}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  |  |
| `defaultValue` | `string` | `""` |  |
| `onValueChange` | `((value: string) => void)` |  |  |
| `onSubmit` | `((value: string) => void)` |  | Called with the trimmed text on Enter or send. Never called when empty. |
| `streaming` | `boolean` |  | While true the send button becomes a stop button. |
| `onStop` | `(() => void)` |  |  |
| `placeholder` | `string` | `"Escribe un mensaje…"` |  |
| `label` | `string` | `"Mensaje"` | Accessible name of the textarea. |
| `disabled` | `boolean` |  |  |
| `maxRows` | `number` | `6` | Rows after which the textarea scrolls instead of growing. |
| `attachments` | `ReactNode` |  | Row above the text (Attachment chips). |
| `actions` | `ReactNode` |  | Left of the send button (attach button, model picker…). |
| `hint` | `ReactNode` |  | Hint line under the field. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/ai-promptinput--default)
- [With Attachments](/storybook/?path=/story/ai-promptinput--with-attachments)
- [Streaming](/storybook/?path=/story/ai-promptinput--streaming)
- [Echo](/storybook/?path=/story/ai-promptinput--echo)
- [Narrow](/storybook/?path=/story/ai-promptinput--narrow)
- [Preset Brutal](/storybook/?path=/story/ai-promptinput--preset-brutal)

## Source

`packages/ui/src/ai/prompt-input/prompt-input.tsx`

---

# PromptSuggestion

> Chip with a suggested prompt.

Source: https://ui.jcsoftdev.com/docs/components/prompt-suggestion

Chip with a suggested prompt. Pressing it hands the text to `onSelect`.

## Import

```ts
import { PromptSuggestion } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/prompt-suggestion`.

## Usage

```tsx
<PromptSuggestion>
  ¿Qué turnos libres hay mañana?
</PromptSuggestion>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSelect` | `((text: string) => void)` |  | Receives the suggestion text when pressed (the visible label is the text). |
| `children` * | `string` |  |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/ai-promptsuggestion--default)
- [List](/storybook/?path=/story/ai-promptsuggestion--list)
- [Narrow](/storybook/?path=/story/ai-promptsuggestion--narrow)
- [Preset Brutal](/storybook/?path=/story/ai-promptsuggestion--preset-brutal)

## Source

`packages/ui/src/ai/prompt-suggestion/prompt-suggestion.tsx`

---

# PromptSuggestionList

> Wrapping group of suggestion chips.

Source: https://ui.jcsoftdev.com/docs/components/prompt-suggestion-list

Wrapping group of suggestion chips.

## Import

```ts
import { PromptSuggestionList } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/prompt-suggestion`.

## Usage

```tsx
<PromptSuggestionList>
  ¿Qué turnos libres hay mañana?
</PromptSuggestionList>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Sugerencias"` |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/ai-promptsuggestion--default)
- [List](/storybook/?path=/story/ai-promptsuggestion--list)
- [Narrow](/storybook/?path=/story/ai-promptsuggestion--narrow)
- [Preset Brutal](/storybook/?path=/story/ai-promptsuggestion--preset-brutal)

## Source

`packages/ui/src/ai/prompt-suggestion/prompt-suggestion.tsx`

---

# Source

> Citation chip with a hover/focus preview of the source (title, host and excerpt).

Source: https://ui.jcsoftdev.com/docs/components/source

Citation chip with a hover/focus preview of the source (title, host and excerpt).

## Import

```ts
import { Source } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/source`.

## Usage

```tsx
<Source
  index={1}
  title="Cuidado de la barba: guía para principiantes"
  url="https://www.barberia-ejemplo.pe/guias/cuidado-de-la-barba"
  snippet="Lava la barba dos o tres veces por semana, aplica aceite en pocas gotas y peina en la dirección del crecimiento."
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `index` | `number` |  | Citation number shown in the chip. |
| `title` * | `string` |  |  |
| `url` * | `string` |  | Only http(s) and mailto URLs are linked; anything else renders a non-clickable chip. |
| `snippet` | `string` |  | Short excerpt shown in the hover preview. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/ai-source--default)
- [Group](/storybook/?path=/story/ai-source--group)
- [Narrow](/storybook/?path=/story/ai-source--narrow)
- [Preset Brutal](/storybook/?path=/story/ai-source--preset-brutal)

## Source

`packages/ui/src/ai/source/source.tsx`

---

# TextShimmer

> Text with a light sweep, used for "thinking…" labels.

Source: https://ui.jcsoftdev.com/docs/components/text-shimmer

Text with a light sweep, used for "thinking…" labels. Static with reduced motion.

## Import

```ts
import { TextShimmer } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/text-shimmer`.

## Usage

```tsx
<TextShimmer duration={2}>
  Revisando la agenda de hoy…
</TextShimmer>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` * | `ReactNode` |  |  |
| `as` | `ElementType` | `"span"` | Element to render. |
| `duration` | `number` | `2` | Seconds for one sweep. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/ai-textshimmer--default)
- [Narrow](/storybook/?path=/story/ai-textshimmer--narrow)
- [Preset Brutal](/storybook/?path=/story/ai-textshimmer--preset-brutal)

## Source

`packages/ui/src/ai/text-shimmer/text-shimmer.tsx`

---

# ToolCall

> Collapsible tool invocation with status, JSON arguments and JSON result.

Source: https://ui.jcsoftdev.com/docs/components/tool-call

Collapsible tool invocation with status, JSON arguments and JSON result.

## Import

```ts
import { ToolCall } from "@jcsoftdev/ui/ai";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/ai/tool-call`.

## Usage

```tsx
<ToolCall
  name="buscar_turnos"
  status="done"
  duration="1,2 s"
  defaultOpen
  args={{ fecha: "2026-06-20", barbero: "Diego Quispe" }}
  result={{ libres: ["10:00", "11:30", "16:00"], total: 3 }}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` * | `string` |  | Tool identifier, e.g. `buscar_turnos`. |
| `status` | `"done" \| "error" \| "pending" \| "running"` | `"pending"` |  |
| `args` | `unknown` |  | Arguments sent to the tool; shown as formatted JSON. |
| `result` | `unknown` |  | Result returned by the tool; shown as formatted JSON. |
| `error` | `string` |  | Error text when `status` is `error`. |
| `duration` | `string` |  | Pre-formatted duration, e.g. `1,2 s`. |
| `defaultOpen` | `boolean` | `false` |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/ai-toolcall--default)
- [Running](/storybook/?path=/story/ai-toolcall--running)
- [Failed](/storybook/?path=/story/ai-toolcall--failed)
- [Narrow](/storybook/?path=/story/ai-toolcall--narrow)
- [Preset Brutal](/storybook/?path=/story/ai-toolcall--preset-brutal)

## Source

`packages/ui/src/ai/tool-call/tool-call.tsx`

---

# Avatar

> `Avatar` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

Source: https://ui.jcsoftdev.com/docs/components/avatar

`Avatar` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

## Import

```ts
import { Avatar } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/avatar`.

## Usage

```tsx
<Avatar name="Diego Quispe" size="md" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` * | `string` |  | Full name: used for the initials fallback and as the accessible name. |
| `src` | `string` |  |  |
| `size` | `"md" \| "lg"` | `"md"` |  |
| `highlighted` | `boolean` |  | Fills the avatar with the accent color (e.g. the current user). |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/atoms-avatar--default)
- [Large](/storybook/?path=/story/atoms-avatar--large)
- [Highlighted](/storybook/?path=/story/atoms-avatar--highlighted)
- [Single Name](/storybook/?path=/story/atoms-avatar--single-name)
- [Team](/storybook/?path=/story/atoms-avatar--team)

## Source

`packages/ui/src/atoms/avatar/avatar.tsx`

---

# AvatarGroup

> Stacked, overlapping avatars separated by a surface-colored ring.

Source: https://ui.jcsoftdev.com/docs/components/avatar-group

Stacked, overlapping avatars separated by a surface-colored ring.

## Import

```ts
import { AvatarGroup } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/avatar-group`.

## Usage

```tsx
<AvatarGroup>
  <>
          <Avatar name="Diego Quispe" />
          <Avatar name="Marco Ríos" />
          <Avatar name="Lucho Vargas" />
        </>
</AvatarGroup>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/atoms-avatargroup--default)
- [Large](/storybook/?path=/story/atoms-avatargroup--large)
- [Single](/storybook/?path=/story/atoms-avatargroup--single)

## Source

`packages/ui/src/atoms/avatar-group/avatar-group.tsx`

---

# BigDate

> Prominent date or number, typically at the top of a card.

Source: https://ui.jcsoftdev.com/docs/components/big-date

Prominent date or number, typically at the top of a card.

## Import

```ts
import { BigDate } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/big-date`.

## Usage

```tsx
<BigDate size="normal">
  Mié 8 oct
</BigDate>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"normal" \| "compact"` | `"normal"` |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/atoms-bigdate--default)
- [Compact](/storybook/?path=/story/atoms-bigdate--compact)
- [As Amount](/storybook/?path=/story/atoms-bigdate--as-amount)
- [In Card](/storybook/?path=/story/atoms-bigdate--in-card)

## Source

`packages/ui/src/atoms/big-date/big-date.tsx`

---

# Button

> `Button` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

Source: https://ui.jcsoftdev.com/docs/components/button

`Button` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

## Import

```ts
import { Button } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/button`.

## Usage

```tsx
<Button variant="primary" size="md">
  Reservar corte
</Button>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"primary" \| "secondary" \| "ghost" \| "danger"` | `"secondary"` |  |
| `size` | `"sm" \| "md"` | `"md"` |  |
| `loading` | `boolean` |  |  |
| `asChild` | `boolean` |  | Render the child element (via Radix Slot) instead of a `<button>`, e.g. a link. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/atoms-button--default)
- [Secondary](/storybook/?path=/story/atoms-button--secondary)
- [Ghost](/storybook/?path=/story/atoms-button--ghost)
- [Danger](/storybook/?path=/story/atoms-button--danger)
- [Small](/storybook/?path=/story/atoms-button--small)
- [Loading](/storybook/?path=/story/atoms-button--loading)
- [Disabled](/storybook/?path=/story/atoms-button--disabled)
- [With Icon](/storybook/?path=/story/atoms-button--with-icon)
- [As Link](/storybook/?path=/story/atoms-button--as-link)
- [Long Label](/storybook/?path=/story/atoms-button--long-label)

## Source

`packages/ui/src/atoms/button/button.tsx`

---

# Checkbox

> `Checkbox` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

Source: https://ui.jcsoftdev.com/docs/components/checkbox

`Checkbox` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

## Import

```ts
import { Checkbox } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/checkbox`.

## Usage

```tsx
<Checkbox aria-label="Cita completada" />
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/atoms-checkbox--default)
- [Checked](/storybook/?path=/story/atoms-checkbox--checked)
- [Disabled](/storybook/?path=/story/atoms-checkbox--disabled)
- [Disabled Checked](/storybook/?path=/story/atoms-checkbox--disabled-checked)
- [Controlled Checklist](/storybook/?path=/story/atoms-checkbox--controlled-checklist)

## Source

`packages/ui/src/atoms/checkbox/checkbox.tsx`

---

# Chip

> `Chip` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

Source: https://ui.jcsoftdev.com/docs/components/chip

`Chip` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

## Import

```ts
import { Chip } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/chip`.

## Usage

```tsx
<Chip tone="neutral">
  Corte clásico
</Chip>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"danger" \| "neutral" \| "warning" \| "success" \| "accent" \| "solid" \| "outline"` | `"neutral"` |  |
| `square` | `boolean` |  | Use the smaller chip radius instead of a full pill. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/atoms-chip--default)
- [Square](/storybook/?path=/story/atoms-chip--square)
- [With Icon](/storybook/?path=/story/atoms-chip--with-icon)
- [All Tones](/storybook/?path=/story/atoms-chip--all-tones)
- [All Tones Square](/storybook/?path=/story/atoms-chip--all-tones-square)

## Source

`packages/ui/src/atoms/chip/chip.tsx`

---

# Icon

> `Icon` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

Source: https://ui.jcsoftdev.com/docs/components/icon

`Icon` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

## Import

```ts
import { Icon } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/icon`.

## Usage

```tsx
<Icon name="calendar" className="size-6 text-ink" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `"menu" \| "search" \| "video" \| "download" \| "alert" \| "grid" \| "list" \| "calendar" \| "folder" \| "users" \| "pen" \| "file" \| "coin" \| "shield" \| "calculator" \| "sync" \| "sliders" \| "bell" \| "plus" \| "chevron-down" \| "chevr…` |  | Registry name; ignored when `icon` is provided. |
| `icon` | `LucideIcon` |  | Any lucide icon component. |
| `label` | `string` |  | Accessible label. Without it the icon is decorative (aria-hidden). |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/atoms-icon--default)
- [With Label](/storybook/?path=/story/atoms-icon--with-label)
- [Custom Lucide Icon](/storybook/?path=/story/atoms-icon--custom-lucide-icon)
- [Registry](/storybook/?path=/story/atoms-icon--registry)

## Source

`packages/ui/src/atoms/icon/icon.tsx`

---

# Led

> `Led` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

Source: https://ui.jcsoftdev.com/docs/components/led

`Led` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

## Import

```ts
import { Led } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/led`.

## Usage

```tsx
<Led status="success" label="Barbero disponible" showLabel />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"danger" \| "warning" \| "success" \| "idle"` | `"success"` |  |
| `label` * | `string` |  | Text describing the status: color is never the only signal. |
| `showLabel` | `boolean` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/atoms-led--default)
- [Warning](/storybook/?path=/story/atoms-led--warning)
- [Danger](/storybook/?path=/story/atoms-led--danger)
- [Idle](/storybook/?path=/story/atoms-led--idle)
- [Label Hidden](/storybook/?path=/story/atoms-led--label-hidden)
- [All Statuses](/storybook/?path=/story/atoms-led--all-statuses)

## Source

`packages/ui/src/atoms/led/led.tsx`

---

# Meter

> Thinner progress bar.

Source: https://ui.jcsoftdev.com/docs/components/meter

Thinner progress bar.

## Import

```ts
import { Meter } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/progress`.

## Usage

```tsx
<Meter value={60} max={100} aria-label="Meta de ingresos del día" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` * | `number` |  |  |
| `max` | `number` |  |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/atoms-progress--default)
- [Empty](/storybook/?path=/story/atoms-progress--empty)
- [Complete](/storybook/?path=/story/atoms-progress--complete)
- [Custom Max](/storybook/?path=/story/atoms-progress--custom-max)
- [Thin Meter](/storybook/?path=/story/atoms-progress--thin-meter)
- [Comparison](/storybook/?path=/story/atoms-progress--comparison)

## Source

`packages/ui/src/atoms/progress/progress.tsx`

---

# NumberValue

> Number that counts up to `value`, formatted with Intl.

Source: https://ui.jcsoftdev.com/docs/components/number-value

Number that counts up to `value`, formatted with Intl. Assistive tech reads the final
value at once; the animated text is hidden from it so it is not announced digit by digit.

## Import

```ts
import { NumberValue } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/number-value`.

## Usage

```tsx
<NumberValue
  value={12840}
  duration={900}
  format={{ style: "currency", currency: "PEN" }}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` * | `number` |  |  |
| `format` | `NumberFormatConfig` |  | Intl options plus `locale`, e.g. `{ style: "currency", currency: "PEN" }`. |
| `duration` | `number` | `900` | Animation length in ms. No animation under `prefers-reduced-motion`. |
| `from` | `number` | `0` | Count up from this value on first render. |
| `animateOnMount` | `boolean` | `true` | When false, only later changes of `value` animate. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/atoms-numbervalue--default)
- [Percent](/storybook/?path=/story/atoms-numbervalue--percent)
- [Compact](/storybook/?path=/story/atoms-numbervalue--compact)
- [Updating](/storybook/?path=/story/atoms-numbervalue--updating)
- [Narrow](/storybook/?path=/story/atoms-numbervalue--narrow)
- [Brutal Preset](/storybook/?path=/story/atoms-numbervalue--brutal-preset)

## Source

`packages/ui/src/atoms/number-value/number-value.tsx`

---

# PressableFeedback

> Wraps any content with press feedback: a ripple from the pointer and a small scale-down.

Source: https://ui.jcsoftdev.com/docs/components/pressable-feedback

Wraps any content with press feedback: a ripple from the pointer and a small scale-down. Both
are skipped under `prefers-reduced-motion`. It adds no semantics, so put it around (or let it
contain) the real button or link.

## Import

```ts
import { PressableFeedback } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/pressable-feedback`.

## Usage

```tsx
export const Default: Story = {};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ripple` | `boolean` | `true` | Draws an expanding ripple from the pointer position. |
| `scale` | `boolean` | `true` | Scales the content down while pressed (uses the preset's `--press-scale`). |
| `disabled` | `boolean` |  |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/atoms-pressablefeedback--default)
- [Ripple Only](/storybook/?path=/story/atoms-pressablefeedback--ripple-only)
- [Disabled](/storybook/?path=/story/atoms-pressablefeedback--disabled)
- [Narrow](/storybook/?path=/story/atoms-pressablefeedback--narrow)
- [Brutal Preset](/storybook/?path=/story/atoms-pressablefeedback--brutal-preset)

## Source

`packages/ui/src/atoms/pressable-feedback/pressable-feedback.tsx`

---

# Progress

> `Progress` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

Source: https://ui.jcsoftdev.com/docs/components/progress

`Progress` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

## Import

```ts
import { Progress } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/progress`.

## Usage

```tsx
<Progress value={60} max={100} aria-label="Meta de ingresos del día" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` * | `number` |  |  |
| `max` | `number` | `100` |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/atoms-progress--default)
- [Empty](/storybook/?path=/story/atoms-progress--empty)
- [Complete](/storybook/?path=/story/atoms-progress--complete)
- [Custom Max](/storybook/?path=/story/atoms-progress--custom-max)
- [Thin Meter](/storybook/?path=/story/atoms-progress--thin-meter)
- [Comparison](/storybook/?path=/story/atoms-progress--comparison)

## Source

`packages/ui/src/atoms/progress/progress.tsx`

---

# RadioGroup

> `RadioGroup` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

Source: https://ui.jcsoftdev.com/docs/components/radio-group

`RadioGroup` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

## Import

```ts
import { RadioGroup } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/radio-group`.

## Usage

```tsx
<RadioGroup
  options={options}
  defaultValue="efectivo"
  aria-label="Método de pago"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` * | `RadioOption[]` |  |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/atoms-radiogroup--default)
- [Without Descriptions](/storybook/?path=/story/atoms-radiogroup--without-descriptions)
- [Disabled](/storybook/?path=/story/atoms-radiogroup--disabled)
- [Controlled](/storybook/?path=/story/atoms-radiogroup--controlled)

## Source

`packages/ui/src/atoms/radio-group/radio-group.tsx`

---

# StatusDot

> `StatusDot` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

Source: https://ui.jcsoftdev.com/docs/components/status-dot

`StatusDot` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

## Import

```ts
import { StatusDot } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/status-dot`.

## Usage

```tsx
<StatusDot tone="success" label="Pagado" showLabel shape="dot" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` * | `"danger" \| "neutral" \| "warning" \| "success" \| "accent"` |  |  |
| `label` * | `string` |  | Text describing the status: color is never the only signal. |
| `showLabel` | `boolean` |  |  |
| `shape` | `"dot" \| "square"` | `"dot"` |  |
| `hollow` | `boolean` |  | Hollow variant: transparent fill with an accent inner ring. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/atoms-statusdot--default)
- [Square](/storybook/?path=/story/atoms-statusdot--square)
- [Hollow](/storybook/?path=/story/atoms-statusdot--hollow)
- [Label Hidden](/storybook/?path=/story/atoms-statusdot--label-hidden)
- [All Tones](/storybook/?path=/story/atoms-statusdot--all-tones)

## Source

`packages/ui/src/atoms/status-dot/status-dot.tsx`

---

# StatusPill

> Pill showing a status LED and its label; the label is hidden when the surrounding container (e.g.

Source: https://ui.jcsoftdev.com/docs/components/status-pill

Pill showing a status LED and its label; the label is hidden when the surrounding container (e.g. the topbar) is narrow.

## Import

```ts
import { StatusPill } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/status-pill`.

## Usage

```tsx
<StatusPill status="success" label="Caja abierta" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` * | `"danger" \| "warning" \| "success" \| "idle"` |  |  |
| `label` * | `string` |  |  |
| `onSelect` | `(() => void)` |  | Without this the pill is decorative (disabled). |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/atoms-statuspill--default)
- [Warning](/storybook/?path=/story/atoms-statuspill--warning)
- [Danger](/storybook/?path=/story/atoms-statuspill--danger)
- [Idle](/storybook/?path=/story/atoms-statuspill--idle)
- [Decorative](/storybook/?path=/story/atoms-statuspill--decorative)

## Source

`packages/ui/src/atoms/status-pill/status-pill.tsx`

---

# Switch

> `Switch` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

Source: https://ui.jcsoftdev.com/docs/components/switch

`Switch` is part of the Atoms set, imported from `@jcsoftdev/ui/atoms`.

## Import

```ts
import { Switch } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/switch`.

## Usage

```tsx
<Switch aria-label="Recordatorios por WhatsApp" />
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/atoms-switch--default)
- [On](/storybook/?path=/story/atoms-switch--on)
- [Disabled](/storybook/?path=/story/atoms-switch--disabled)
- [Disabled On](/storybook/?path=/story/atoms-switch--disabled-on)
- [Controlled](/storybook/?path=/story/atoms-switch--controlled)

## Source

`packages/ui/src/atoms/switch/switch.tsx`

---

# TrendChip

> Compact change indicator: arrow, signed percent and a good/bad tone, never color alone.

Source: https://ui.jcsoftdev.com/docs/components/trend-chip

Compact change indicator: arrow, signed percent and a good/bad tone, never color alone.

## Import

```ts
import { TrendChip } from "@jcsoftdev/ui/atoms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/atoms/trend-chip`.

## Usage

```tsx
<TrendChip value={12.5} label="vs. semana pasada" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` * | `number` |  | Change in percent, e.g. 12.5 for +12.5%. |
| `invert` | `boolean` | `false` | Lower is better (cancelaciones, mermas): a drop reads as favorable. |
| `epsilon` | `number` | `0` | Changes whose absolute value is within this stay "flat". |
| `label` | `string` |  | Text after the number, e.g. "vs. semana pasada". |
| `locale` | `string` |  |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/atoms-trendchip--default)
- [Down](/storybook/?path=/story/atoms-trendchip--down)
- [Flat](/storybook/?path=/story/atoms-trendchip--flat)
- [Lower Is Better](/storybook/?path=/story/atoms-trendchip--lower-is-better)
- [Narrow](/storybook/?path=/story/atoms-trendchip--narrow)
- [Brutal Preset](/storybook/?path=/story/atoms-trendchip--brutal-preset)

## Source

`packages/ui/src/atoms/trend-chip/trend-chip.tsx`

---

# LogoForge

> Interactive brand-mark editor: pick a shape, monogram, palette and layout, browse twelve seeded variations, then download SVG or PNG or copy the SVG source.

Source: https://ui.jcsoftdev.com/docs/components/logo-forge

Interactive brand-mark editor: pick a shape, monogram, palette and layout, browse twelve
seeded variations, then download SVG or PNG or copy the SVG source. The chrome follows
`data-style` and the active theme; the marks keep their own palettes.

## Import

```ts
import { LogoForge } from "@jcsoftdev/ui/brand";
```

## Usage

```tsx
<LogoForge />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `Partial<LogoForgeValue>` |  |  |
| `onChange` | `((options: MarkOptions) => void)` |  | Called with the generator options each time the editor changes. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/foundations-logoforge--default)
- [Narrow](/storybook/?path=/story/foundations-logoforge--narrow)
- [Brutal Preset](/storybook/?path=/story/foundations-logoforge--brutal-preset)
- [Barbería Don Lucho](/storybook/?path=/story/foundations-logoforge--barberia-don-lucho)

## Source

`packages/ui/src/brand/logo-forge.tsx`

---

# LogoMark

> Renders a generated brand mark as an inline `<svg role="img">`.

Source: https://ui.jcsoftdev.com/docs/components/logo-mark

Renders a generated brand mark as an inline `<svg role="img">`.

## Import

```ts
import { LogoMark } from "@jcsoftdev/ui/brand";
```

## Usage

```tsx
<LogoMark
  name="Barbería Don Lucho"
  tagline="Corte y navaja desde 1998"
  shape="shield"
  monogram="glyph"
  glyph="scissors"
  palette="navaja"
  layout="horizontal"
  fill="solid"
  seed={0}
  size={360}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `string \| number` | `"100%"` | CSS width of the mark; the height follows the aspect ratio. Defaults to the full container. |
| `className` | `string` |  |  |
| `name` * | `string` |  | Business name: drives the wordmark and the initials. |
| `tagline` | `string` |  |  |
| `initials` | `string` |  | Overrides the initials taken from `name`. |
| `shape` | `"circle" \| "none" \| "shield" \| "squircle" \| "hexagon" \| "badge" \| "ribbon"` |  |  |
| `monogram` | `"initials" \| "glyph"` |  |  |
| `glyph` | `"scissors" \| "comb" \| "razor" \| "pole" \| "star" \| "leaf" \| "bolt" \| "crown" \| "mustache"` |  |  |
| `initialsCount` | `1 \| 3 \| 2` |  |  |
| `palette` | `string \| BrandPalette` |  | A palette id from `BRAND_PALETTES` or a custom palette. |
| `layout` | `"icon" \| "horizontal" \| "stacked"` |  |  |
| `fill` | `"solid" \| "outline" \| "gradient"` |  |  |
| `seed` | `number` |  | 0 is the canonical look; other values deterministically vary angle, tilt, ring and color order. |
| `ring` | `boolean` |  | Inner ring; left undefined it follows the seed. |
| `wordmark` | `WordmarkStyle` |  |  |
| `background` | `string` |  | Paints a padded background rectangle behind the mark. |
| `wordmarkColor` | `string` |  | Overrides the wordmark color (use a light one over a dark background). |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/foundations-logomark--default)
- [Stacked](/storybook/?path=/story/foundations-logomark--stacked)
- [Initials](/storybook/?path=/story/foundations-logomark--initials)
- [Narrow](/storybook/?path=/story/foundations-logomark--narrow)
- [Gallery](/storybook/?path=/story/foundations-logomark--gallery)

## Source

`packages/ui/src/brand/logo-mark.tsx`

---

# DayChip

> Compact single-line chip for a day marker.

Source: https://ui.jcsoftdev.com/docs/components/day-chip

Compact single-line chip for a day marker.

## Import

```ts
import { DayChip } from "@jcsoftdev/ui/calendar";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/calendar/day-chip`.

## Usage

```tsx
<DayChip marker={marker} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `marker` * | `CalendarMarker` |  |  |
| `onOpen` | `((id: string) => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/calendar-daychip--default)
- [Accent](/storybook/?path=/story/calendar-daychip--accent)
- [Without Subtitle](/storybook/?path=/story/calendar-daychip--without-subtitle)
- [Truncated](/storybook/?path=/story/calendar-daychip--truncated)

## Source

`packages/ui/src/calendar/day-chip/day-chip.tsx`

---

# EventBlock

> `EventBlock` is part of the Calendar set, imported from `@jcsoftdev/ui/calendar`.

Source: https://ui.jcsoftdev.com/docs/components/event-block

`EventBlock` is part of the Calendar set, imported from `@jcsoftdev/ui/calendar`.

## Import

```ts
import { EventBlock } from "@jcsoftdev/ui/calendar";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/calendar/event-block`.

## Usage

```tsx
<EventBlock event={cita} variant="detailed" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `event` * | `CalendarEvent` |  |  |
| `variant` | `"compact" \| "detailed"` | `"detailed"` | "detailed": time range, title and subtitle. "compact": one "time title" line. |
| `onOpen` | `((id: string) => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/calendar-eventblock--default)
- [Compact](/storybook/?path=/story/calendar-eventblock--compact)
- [With Trailing Avatar](/storybook/?path=/story/calendar-eventblock--with-trailing-avatar)
- [No End Time](/storybook/?path=/story/calendar-eventblock--no-end-time)
- [Tones](/storybook/?path=/story/calendar-eventblock--tones)
- [Compact Tones](/storybook/?path=/story/calendar-eventblock--compact-tones)
- [Narrow](/storybook/?path=/story/calendar-eventblock--narrow)

## Source

`packages/ui/src/calendar/event-block/event-block.tsx`

---

# MonthView

> `MonthView` is part of the Calendar set, imported from `@jcsoftdev/ui/calendar`.

Source: https://ui.jcsoftdev.com/docs/components/month-view

`MonthView` is part of the Calendar set, imported from `@jcsoftdev/ui/calendar`.

## Import

```ts
import { MonthView } from "@jcsoftdev/ui/calendar";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/calendar/month-view`.

## Usage

```tsx
<MonthView
  month="2026-10-08"
  today="2026-10-08"
  events={events}
  markers={markers}
  shadedDates={["2026-10-04", "2026-10-11", "2026-10-18", "2026-10-25"]}
  locale="es-PE"
  weekStartsOn={1}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `month` * | `string` |  | Any "YYYY-MM-DD" date inside the month to show. |
| `today` * | `string` |  | "YYYY-MM-DD" date highlighted as today; the view never computes it. |
| `events` * | `CalendarEvent[]` |  |  |
| `markers` | `CalendarMarker[]` | `[]` |  |
| `shadedDates` | `string[]` | `[]` | Dates ("YYYY-MM-DD") rendered with a hatch pattern (non-working days). |
| `locale` | `string` |  | BCP 47 locale for weekday labels. Defaults to the runtime locale. |
| `weekStartsOn` | `0 \| 1 \| 4 \| 3 \| 2 \| 5 \| 6` | `1` | First day of the week, 0 (Sunday) to 6 (Saturday). Defaults to 1 (Monday). |
| `formatMore` * | `(count: number) => string` |  | Label for the overflow button, e.g. `(n) => \`+${n} more\``. |
| `onOpenEvent` | `((id: string) => void)` |  |  |
| `onOpenMarker` | `((id: string) => void)` |  |  |
| `onSelectDate` | `((date: string) => void)` |  | Called with the day's date when the overflow button is clicked. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/calendar-monthview--default)
- [Sunday Start](/storybook/?path=/story/calendar-monthview--sunday-start)
- [Empty](/storybook/?path=/story/calendar-monthview--empty)
- [Next Month](/storybook/?path=/story/calendar-monthview--next-month)
- [Narrow](/storybook/?path=/story/calendar-monthview--narrow)

## Source

`packages/ui/src/calendar/month-view/month-view.tsx`

---

# TimelineView

> `TimelineView` is part of the Calendar set, imported from `@jcsoftdev/ui/calendar`.

Source: https://ui.jcsoftdev.com/docs/components/timeline-view

`TimelineView` is part of the Calendar set, imported from `@jcsoftdev/ui/calendar`.

## Import

```ts
import { TimelineView } from "@jcsoftdev/ui/calendar";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/calendar/timeline-view`.

## Usage

```tsx
<TimelineView
  today="2026-10-08"
  events={events}
  markers={markers}
  hiddenDates={["2026-10-11"]}
  locale="es-PE"
  todayLabel="hoy"
  emptyLabel="Sin citas"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `today` * | `string` |  | "YYYY-MM-DD" date highlighted as today; the view never computes it. |
| `events` * | `CalendarEvent[]` |  |  |
| `markers` | `CalendarMarker[]` | `[]` |  |
| `hiddenDates` | `string[]` | `[]` | Dates ("YYYY-MM-DD") hidden from the timeline unless they are today. |
| `locale` | `string` |  | BCP 47 locale for date labels. Defaults to the runtime locale. |
| `todayLabel` * | `string` |  | Suffix marking today's group, e.g. "today". |
| `emptyLabel` * | `string` |  | Text shown for a day without events or markers. |
| `onOpenEvent` | `((id: string) => void)` |  |  |
| `onOpenMarker` | `((id: string) => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/calendar-timelineview--default)
- [Empty Today](/storybook/?path=/story/calendar-timelineview--empty-today)
- [Hidden Dates](/storybook/?path=/story/calendar-timelineview--hidden-dates)
- [Markers Only](/storybook/?path=/story/calendar-timelineview--markers-only)
- [Narrow](/storybook/?path=/story/calendar-timelineview--narrow)

## Source

`packages/ui/src/calendar/timeline-view/timeline-view.tsx`

---

# WeekView

> `WeekView` is part of the Calendar set, imported from `@jcsoftdev/ui/calendar`.

Source: https://ui.jcsoftdev.com/docs/components/week-view

`WeekView` is part of the Calendar set, imported from `@jcsoftdev/ui/calendar`.

## Import

```ts
import { WeekView } from "@jcsoftdev/ui/calendar";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/calendar/week-view`.

## Usage

```tsx
<WeekView
  week="2026-10-08"
  today="2026-10-08"
  currentTime="11:45"
  events={events}
  markers={markers}
  shadedDates={["2026-10-11"]}
  workingHours={[10, 19]}
  locale="es-PE"
  weekStartsOn={1}
  allDayLabel="Todo el día"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `week` * | `string` |  | Any "YYYY-MM-DD" date inside the week to show. |
| `today` * | `string` |  | "YYYY-MM-DD" date highlighted as today; the view never computes it. |
| `currentTime` | `string` |  | Current time "HH:mm" for the "now" line; without it no line is drawn. |
| `events` * | `CalendarEvent[]` |  |  |
| `markers` | `CalendarMarker[]` | `[]` | Markers render in the all-day row. |
| `shadedDates` | `string[]` | `[]` | Dates ("YYYY-MM-DD") rendered with a hatch pattern (non-working days). |
| `workingHours` | `readonly [number, number]` |  | Highlighted band of working hours, [start, end) in hours. |
| `locale` | `string` |  |  |
| `weekStartsOn` | `0 \| 1 \| 4 \| 3 \| 2 \| 5 \| 6` | `1` | First day of the week, 0 (Sunday) to 6 (Saturday). Defaults to 1 (Monday). |
| `allDayLabel` * | `string` |  | Label of the all-day row. |
| `onOpenEvent` | `((id: string) => void)` |  |  |
| `onOpenMarker` | `((id: string) => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/calendar-weekview--default)
- [Sunday Start](/storybook/?path=/story/calendar-weekview--sunday-start)
- [Empty](/storybook/?path=/story/calendar-weekview--empty)
- [No Now Line](/storybook/?path=/story/calendar-weekview--no-now-line)
- [Busy Day](/storybook/?path=/story/calendar-weekview--busy-day)
- [Narrow](/storybook/?path=/story/calendar-weekview--narrow)

## Source

`packages/ui/src/calendar/week-view/week-view.tsx`

---

# AlluvialChart

> Alluvial diagram: how the same categories flow from one moment to the next (client segments month by month, services chosen by season).

Source: https://ui.jcsoftdev.com/docs/components/alluvial-chart

Alluvial diagram: how the same categories flow from one moment to the next
(client segments month by month, services chosen by season). Each stage is a
column; every category keeps its color and its place from top to bottom, so
the eye follows who moved where. Built on `SankeyChart`.

## Import

```ts
import { AlluvialChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/sankey-chart`.

## Usage

```tsx
<AlluvialChart
  title="Origen de clientes, servicio y medio de pago"
  nodes={nodes}
  links={links}
  columns={["Origen", "Servicio", "Pago"]}
  valueFormat="integer"
  height={400}
  nodePadding={14}
  align="justify"
  iterations={6}
  linkColor="gradient"
  linkOpacity={0.38}
  labelPosition="outside"
  showValues
  tooltip
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stages` * | `readonly string[]` |  | Moments in time, left to right: "Jun", "Jul", ... |
| `categories` * | `readonly { id: string; name: string; color?: string; }[]` |  | The categories that flow; their order is the order top to bottom in every stage. |
| `flows` * | `readonly (readonly { from: string; to: string; value: number; }[])[]` |  | `flows[s]` moves people from stage `s` to stage `s + 1`: `{ from: categoryId, to: categoryId, value }`. |
| `title` * | `string` |  | Accessible name of the drawing and caption of the data table. |
| `animate` | `boolean` |  |  |
| `className` | `string` |  |  |
| `tooltip` | `boolean` |  |  |
| `height` | `number \| "fill"` |  |  |
| `aspectRatio` | `number` |  | Width / height ratio of the drawing; ignored with `"fill"`. |
| `valueFormat` | `ValueFormat` |  |  |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<SankeyLabels>` |  |  |
| `pathTracing` | `boolean` |  | Hover or click traces a whole path: a link lights everything upstream of its source and downstream of its target; a click pins it. |
| `particles` | `boolean` |  | Dots travel along the bands (off under `prefers-reduced-motion`). |
| `exportable` | `boolean` |  | Show SVG and PNG export buttons above the drawing. |
| `nodeWidth` | `number` |  | Thickness of the node bars (wider by default with inside labels). |
| `nodePadding` | `number` |  | Vertical gap between nodes of a column. |
| `iterations` | `number` |  | Relaxation sweeps of the layout; more untangles more, at a cost. |
| `linkColor` | `"source" \| "target" \| "neutral" \| "gradient"` |  | `gradient` blends source into target; `source`/`target` use one end; `neutral` is grey. |
| `linkOpacity` | `number` |  | Resting opacity of the links (0-1). |
| `labelPosition` | `"outside" \| "inside"` |  | Node labels beside the bars (`outside`) or on wide bars (`inside`). |
| `showValues` | `boolean` |  | Value after each node label. |
| `onNodeClick` | `((node: SankeyNode) => void)` |  |  |
| `onLinkClick` | `((link: SankeyLink) => void)` |  |  |
| `onRemovedLinks` | `((removed: SankeyGraph["removed"]) => void)` |  | Links the layout left out (cycles, self links, unknown ids, invalid values). |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-sankeychart--default)
- [Source Colored](/storybook/?path=/story/charts-sankeychart--source-colored)
- [Inside Labels](/storybook/?path=/story/charts-sankeychart--inside-labels)
- [Revenue](/storybook/?path=/story/charts-sankeychart--revenue)
- [With Cycle](/storybook/?path=/story/charts-sankeychart--with-cycle)
- [Loading](/storybook/?path=/story/charts-sankeychart--loading)
- [Empty](/storybook/?path=/story/charts-sankeychart--empty)
- [Narrow](/storybook/?path=/story/charts-sankeychart--narrow)
- [Fill Parent](/storybook/?path=/story/charts-sankeychart--fill-parent)
- [Alluvial](/storybook/?path=/story/charts-sankeychart--alluvial)
- [Diff](/storybook/?path=/story/charts-sankeychart--diff)
- [Path Tracing](/storybook/?path=/story/charts-sankeychart--path-tracing)
- [Particles](/storybook/?path=/story/charts-sankeychart--particles)
- [Export](/storybook/?path=/story/charts-sankeychart--export)
- [Chord](/storybook/?path=/story/charts-sankeychart--chord)

## Source

`packages/ui/src/charts/sankey-chart/alluvial-chart.tsx`

---

# AreaChart

> Volume over time with a soft gradient fill.

Source: https://ui.jcsoftdev.com/docs/components/area-chart

Volume over time with a soft gradient fill. `stack="normal"` piles series
into a total; `stack="percent"` shows each one's share of 100%.

## Import

```ts
import { AreaChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/area-chart`.

## Usage

```tsx
<AreaChart
  title="Servicios vendidos por semana"
  categories={weeks}
  valueFormat="integer"
  height={300}
  curve="smooth"
  stack="none"
  gradient
  markers={false}
  dataLabels={false}
  brush={false}
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `series` * | `readonly ChartSeries[]` |  |  |
| `legend` | `boolean \| "top" \| "bottom"` |  | Legend placement, or false to hide it. Defaults to "top" with two or more series. |
| `title` * | `string` |  | Accessible name of the chart (`aria-label` of the drawing). |
| `animate` | `boolean` |  | Entry animation (default true; always off with prefers-reduced-motion). |
| `className` | `string` |  |  |
| `grid` | `boolean` |  | Background gridlines (default true). |
| `tooltip` | `boolean` |  | Shared tooltip (default true). |
| `gradient` | `boolean` |  | Gradient fill under areas (default true). |
| `categories` * | `readonly XValue[]` |  | One entry per data point: strings, numbers or dates. |
| `description` | `string` |  | Extra sentence for the hidden data table caption. |
| `height` | `number \| "fill"` |  | Height of the plot in pixels, 300 by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the plot from the container width (wins over a pixel `height`). |
| `stack` | `"normal" \| "none" \| "percent"` |  | Stacks every area and column series. |
| `curve` | `"linear" \| "smooth" \| "step" \| "step-before" \| "step-after"` | `"smooth"` |  |
| `markers` | `boolean` |  | Dots on every line point. Hovered points are always marked. |
| `dataLabels` | `boolean` |  | Values printed on the marks. |
| `lineGradient` | `boolean` |  | Strokes lines with a gradient from each series color to the next palette color. |
| `transition` | `boolean` |  | Eases lines and areas between data updates (live data); off by default. |
| `maxPoints` | `number \| false` |  | Series with more points than this are reduced with LTTB, 2000 by default; `false` draws every point. |
| `syncId` | `string` |  | Charts with the same id share hover (crosshair and tooltip) and the zoom window. |
| `onPointClick` | `((point: CartesianPointEvent) => void)` |  | Called with the category (and nearest series) under the pointer when the plot is clicked or Enter is pressed. |
| `valueFormat` | `ValueFormat` |  | Format of values in tooltips, labels and the data table. |
| `xFormat` | `((value: XValue) => string)` |  | Label of a category on the axis and in the tooltip (dates get Spanish defaults). |
| `xScale` | `"time" \| "auto" \| "band"` |  | "time" spaces dates by real elapsed time; "auto" picks it when every category is a Date and no series is a column. |
| `yAxis` | `ValueAxisOptions` |  |  |
| `axes` | `readonly CartesianAxisSpec[]` |  | Any number of value axes. `yAxis` and `rightAxis` are shorthand for the ids "left" and "right"; more entries stack outward on their `side` (right by default) and series pick one with `axis`. |
| `annotations` | `readonly ChartAnnotation[]` |  |  |
| `categoryLabelRotation` | `number` |  | Tilts the category labels (degrees, e.g. -45) so long names fit; vertical charts only. |
| `categoryGroups` | `readonly CategoryGroup[]` |  | Second tier of labels under the category axis (vertical charts); counts must add up to the categories. |
| `onCategoryClick` | `((index: number) => void)` |  | Click (or Enter on the focused plot) on a category; receives its index in `categories`. |
| `brush` | `boolean` |  | Drag-to-zoom on the plot plus an overview brush with a reset button. |
| `overlay` | `CartesianOverlay` |  | Extra layers over the plot, e.g. the ruler and ink tools of `useChartInk`. Vertical charts only. |
| `rangeSelect` | `{ value: readonly [number, number] \| null; onChange: (range: readonly [number, number] \| null) => void; }` |  |  |
| `loading` | `boolean` |  |  |
| `initialHidden` | `readonly string[]` |  | Series hidden at first; the legend can show them. |
| `labels` | `Partial<ChartLabels>` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-areachart--default)
- [Multiple Series](/storybook/?path=/story/charts-areachart--multiple-series)
- [Stacked](/storybook/?path=/story/charts-areachart--stacked)
- [Stacked 100%](/storybook/?path=/story/charts-areachart--stacked-percent)
- [Without Gradient](/storybook/?path=/story/charts-areachart--without-gradient)
- [Brush and zoom (120 days)](/storybook/?path=/story/charts-areachart--brush-zoom)
- [Step](/storybook/?path=/story/charts-areachart--step)
- [Negative Values](/storybook/?path=/story/charts-areachart--negative-values)
- [With Gaps](/storybook/?path=/story/charts-areachart--with-gaps)
- [Narrow](/storybook/?path=/story/charts-areachart--narrow)
- [Loading](/storybook/?path=/story/charts-areachart--loading)

## Source

`packages/ui/src/charts/area-chart/area-chart.tsx`

---

# AxisBottom

> Category or time labels under the plot.

Source: https://ui.jcsoftdev.com/docs/components/axis-bottom

Category or time labels under the plot.

## Import

```ts
import { AxisBottom } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {
  render: () => <AxesDemo title="Ventas" rightTitle="Cortes" showRight={false} showGrid />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ticks` * | `readonly AxisTick[]` |  |  |
| `offset` * | `number` |  | Offset of the axis line: `y` for bottom, `x` for left/right. |
| `title` | `string` |  |  |
| `color` | `string` |  | Overrides the label color (a value axis matched to its series). |
| `rotate` | `number` |  | Tilts the labels by this many degrees (negative reads up and to the right), e.g. -45. |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-axes--default)
- [Dual Axis](/storybook/?path=/story/charts-primitives-axes--dual-axis)
- [Without Grid](/storybook/?path=/story/charts-primitives-axes--without-grid)

## Source

`packages/ui/src/charts/core/axes.tsx`

---

# AxisLeft

> Value labels on the left, right-aligned against the plot.

Source: https://ui.jcsoftdev.com/docs/components/axis-left

Value labels on the left, right-aligned against the plot.

## Import

```ts
import { AxisLeft } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {
  render: () => <AxesDemo title="Ventas" rightTitle="Cortes" showRight={false} showGrid />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ticks` * | `readonly AxisTick[]` |  |  |
| `offset` * | `number` |  | Offset of the axis line: `y` for bottom, `x` for left/right. |
| `title` | `string` |  |  |
| `color` | `string` |  | Overrides the label color (a value axis matched to its series). |
| `rotate` | `number` |  | Tilts the labels by this many degrees (negative reads up and to the right), e.g. -45. |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-axes--default)
- [Dual Axis](/storybook/?path=/story/charts-primitives-axes--dual-axis)
- [Without Grid](/storybook/?path=/story/charts-primitives-axes--without-grid)
- [Default](/storybook/?path=/story/charts-primitives-cartesianchart--default)
- [Stacked](/storybook/?path=/story/charts-primitives-cartesianchart--stacked)
- [Horizontal](/storybook/?path=/story/charts-primitives-cartesianchart--horizontal)
- [Columns And Line On Right Axis](/storybook/?path=/story/charts-primitives-cartesianchart--columns-and-line-on-right-axis)
- [Area With Goal](/storybook/?path=/story/charts-primitives-cartesianchart--area-with-goal)
- [With Brush](/storybook/?path=/story/charts-primitives-cartesianchart--with-brush)
- [Loading](/storybook/?path=/story/charts-primitives-cartesianchart--loading)
- [Empty](/storybook/?path=/story/charts-primitives-cartesianchart--empty)
- [Default](/storybook/?path=/story/charts-primitives-categoryslider--default)
- [Default](/storybook/?path=/story/charts-primitives-chartbreadcrumb--default)
- [Root Only](/storybook/?path=/story/charts-primitives-chartbreadcrumb--root-only)
- [Interactive](/storybook/?path=/story/charts-primitives-chartbreadcrumb--interactive)
- [Default](/storybook/?path=/story/charts-primitives-chartbrush--default)
- [Full Range](/storybook/?path=/story/charts-primitives-chartbrush--full-range)
- [Default](/storybook/?path=/story/charts-primitives-chartdatatable--default)
- [Missing Values](/storybook/?path=/story/charts-primitives-chartdatatable--missing-values)
- [Default](/storybook/?path=/story/charts-primitives-chartframe--default)
- [Fills Parent](/storybook/?path=/story/charts-primitives-chartframe--fills-parent)
- [Aspect Ratio](/storybook/?path=/story/charts-primitives-chartframe--aspect-ratio)
- [With Legend And Table](/storybook/?path=/story/charts-primitives-chartframe--with-legend-and-table)
- [Loading](/storybook/?path=/story/charts-primitives-chartframe--loading)
- [Loading Ring](/storybook/?path=/story/charts-primitives-chartframe--loading-ring)
- [Empty](/storybook/?path=/story/charts-primitives-chartframe--empty)
- [Read Only](/storybook/?path=/story/charts-primitives-chartlegend--read-only)
- [Toggleable](/storybook/?path=/story/charts-primitives-chartlegend--toggleable)
- [Centered](/storybook/?path=/story/charts-primitives-chartlegend--centered)
- [Bars](/storybook/?path=/story/charts-primitives-chartskeleton--bars)
- [Line](/storybook/?path=/story/charts-primitives-chartskeleton--line)
- [Ring](/storybook/?path=/story/charts-primitives-chartskeleton--ring)
- [Empty](/storybook/?path=/story/charts-primitives-chartskeleton--empty)
- [Default](/storybook/?path=/story/charts-primitives-charttooltip--default)
- [Flips Near The Right Edge](/storybook/?path=/story/charts-primitives-charttooltip--flips-near-the-right-edge)
- [Without Title](/storybook/?path=/story/charts-primitives-charttooltip--without-title)
- [Default](/storybook/?path=/story/charts-primitives-exportmenu--default)
- [Spanish](/storybook/?path=/story/charts-primitives-exportmenu--spanish)
- [Default](/storybook/?path=/story/charts-primitives-hierarchyheader--default)
- [At Root](/storybook/?path=/story/charts-primitives-hierarchyheader--at-root)
- [Default](/storybook/?path=/story/charts-primitives-hierarchylegend--default)
- [Drilled In](/storybook/?path=/story/charts-primitives-hierarchylegend--drilled-in)
- [Limited](/storybook/?path=/story/charts-primitives-hierarchylegend--limited)
- [Leaf](/storybook/?path=/story/charts-primitives-hierarchylegend--leaf)
- [Default](/storybook/?path=/story/charts-primitives-hierarchytable--default)
- [From Branch](/storybook/?path=/story/charts-primitives-hierarchytable--from-branch)
- [Gallery](/storybook/?path=/story/charts-primitives-chartpatterndefs--gallery)
- [Custom Tile](/storybook/?path=/story/charts-primitives-chartpatterndefs--custom-tile)
- [Default](/storybook/?path=/story/charts-primitives-plotoverlay--default)
- [Vertical Keys](/storybook/?path=/story/charts-primitives-plotoverlay--vertical-keys)
- [Both Axes Keys](/storybook/?path=/story/charts-primitives-plotoverlay--both-axes-keys)
- [Default](/storybook/?path=/story/charts-primitives-unitglyph--default)
- [Fills Up](/storybook/?path=/story/charts-primitives-unitglyph--fills-up)
- [Scissors](/storybook/?path=/story/charts-primitives-unitglyph--scissors)
- [Without Track](/storybook/?path=/story/charts-primitives-unitglyph--without-track)

## Source

`packages/ui/src/charts/core/axes.tsx`

---

# AxisRight

> Value labels on the right, for a secondary axis.

Source: https://ui.jcsoftdev.com/docs/components/axis-right

Value labels on the right, for a secondary axis.

## Import

```ts
import { AxisRight } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {
  render: () => <AxesDemo title="Ventas" rightTitle="Cortes" showRight={false} showGrid />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ticks` * | `readonly AxisTick[]` |  |  |
| `offset` * | `number` |  | Offset of the axis line: `y` for bottom, `x` for left/right. |
| `title` | `string` |  |  |
| `color` | `string` |  | Overrides the label color (a value axis matched to its series). |
| `rotate` | `number` |  | Tilts the labels by this many degrees (negative reads up and to the right), e.g. -45. |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-axes--default)
- [Dual Axis](/storybook/?path=/story/charts-primitives-axes--dual-axis)
- [Without Grid](/storybook/?path=/story/charts-primitives-axes--without-grid)
- [Default](/storybook/?path=/story/charts-primitives-cartesianchart--default)
- [Stacked](/storybook/?path=/story/charts-primitives-cartesianchart--stacked)
- [Horizontal](/storybook/?path=/story/charts-primitives-cartesianchart--horizontal)
- [Columns And Line On Right Axis](/storybook/?path=/story/charts-primitives-cartesianchart--columns-and-line-on-right-axis)
- [Area With Goal](/storybook/?path=/story/charts-primitives-cartesianchart--area-with-goal)
- [With Brush](/storybook/?path=/story/charts-primitives-cartesianchart--with-brush)
- [Loading](/storybook/?path=/story/charts-primitives-cartesianchart--loading)
- [Empty](/storybook/?path=/story/charts-primitives-cartesianchart--empty)
- [Default](/storybook/?path=/story/charts-primitives-categoryslider--default)
- [Default](/storybook/?path=/story/charts-primitives-chartbreadcrumb--default)
- [Root Only](/storybook/?path=/story/charts-primitives-chartbreadcrumb--root-only)
- [Interactive](/storybook/?path=/story/charts-primitives-chartbreadcrumb--interactive)
- [Default](/storybook/?path=/story/charts-primitives-chartbrush--default)
- [Full Range](/storybook/?path=/story/charts-primitives-chartbrush--full-range)
- [Default](/storybook/?path=/story/charts-primitives-chartdatatable--default)
- [Missing Values](/storybook/?path=/story/charts-primitives-chartdatatable--missing-values)
- [Default](/storybook/?path=/story/charts-primitives-chartframe--default)
- [Fills Parent](/storybook/?path=/story/charts-primitives-chartframe--fills-parent)
- [Aspect Ratio](/storybook/?path=/story/charts-primitives-chartframe--aspect-ratio)
- [With Legend And Table](/storybook/?path=/story/charts-primitives-chartframe--with-legend-and-table)
- [Loading](/storybook/?path=/story/charts-primitives-chartframe--loading)
- [Loading Ring](/storybook/?path=/story/charts-primitives-chartframe--loading-ring)
- [Empty](/storybook/?path=/story/charts-primitives-chartframe--empty)
- [Read Only](/storybook/?path=/story/charts-primitives-chartlegend--read-only)
- [Toggleable](/storybook/?path=/story/charts-primitives-chartlegend--toggleable)
- [Centered](/storybook/?path=/story/charts-primitives-chartlegend--centered)
- [Bars](/storybook/?path=/story/charts-primitives-chartskeleton--bars)
- [Line](/storybook/?path=/story/charts-primitives-chartskeleton--line)
- [Ring](/storybook/?path=/story/charts-primitives-chartskeleton--ring)
- [Empty](/storybook/?path=/story/charts-primitives-chartskeleton--empty)
- [Default](/storybook/?path=/story/charts-primitives-charttooltip--default)
- [Flips Near The Right Edge](/storybook/?path=/story/charts-primitives-charttooltip--flips-near-the-right-edge)
- [Without Title](/storybook/?path=/story/charts-primitives-charttooltip--without-title)
- [Default](/storybook/?path=/story/charts-primitives-exportmenu--default)
- [Spanish](/storybook/?path=/story/charts-primitives-exportmenu--spanish)
- [Default](/storybook/?path=/story/charts-primitives-hierarchyheader--default)
- [At Root](/storybook/?path=/story/charts-primitives-hierarchyheader--at-root)
- [Default](/storybook/?path=/story/charts-primitives-hierarchylegend--default)
- [Drilled In](/storybook/?path=/story/charts-primitives-hierarchylegend--drilled-in)
- [Limited](/storybook/?path=/story/charts-primitives-hierarchylegend--limited)
- [Leaf](/storybook/?path=/story/charts-primitives-hierarchylegend--leaf)
- [Default](/storybook/?path=/story/charts-primitives-hierarchytable--default)
- [From Branch](/storybook/?path=/story/charts-primitives-hierarchytable--from-branch)
- [Gallery](/storybook/?path=/story/charts-primitives-chartpatterndefs--gallery)
- [Custom Tile](/storybook/?path=/story/charts-primitives-chartpatterndefs--custom-tile)
- [Default](/storybook/?path=/story/charts-primitives-plotoverlay--default)
- [Vertical Keys](/storybook/?path=/story/charts-primitives-plotoverlay--vertical-keys)
- [Both Axes Keys](/storybook/?path=/story/charts-primitives-plotoverlay--both-axes-keys)
- [Default](/storybook/?path=/story/charts-primitives-unitglyph--default)
- [Fills Up](/storybook/?path=/story/charts-primitives-unitglyph--fills-up)
- [Scissors](/storybook/?path=/story/charts-primitives-unitglyph--scissors)
- [Without Track](/storybook/?path=/story/charts-primitives-unitglyph--without-track)

## Source

`packages/ui/src/charts/core/axes.tsx`

---

# BarChart

> Columns (`orientation="vertical"`, default) or horizontal bars.

Source: https://ui.jcsoftdev.com/docs/components/bar-chart

Columns (`orientation="vertical"`, default) or horizontal bars. Several
series are grouped side by side, or piled with `stack`. Bars are rounded at
their value end only, negative values grow downwards (or to the left).

Also: floating `ranges`, `stackGroup` piles side by side, `categoryGroups`
labels under the axis, a `reversed` value axis (`yAxis.reversed`), SVG
`pattern` fills per series, per-bar `colors` / `distributed`, and
`onCategoryClick` for drill-down.

## Import

```ts
import { BarChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/bar-chart`.

## Usage

```tsx
<BarChart
  title="Citas por barbero esta semana"
  categories={barbers}
  series={[{ id: "citas", name: "Citas", data: appointmentsThisWeek }]}
  valueFormat="integer"
  orientation="vertical"
  stack="none"
  barRadius={6}
  height={300}
  dataLabels={false}
  grid
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `series` * | `readonly BarSeries[]` |  |  |
| `distributed` | `boolean` | `false` | One palette color per bar instead of one per series (single-series charts). |
| `legend` | `boolean \| "top" \| "bottom"` |  | Legend placement, or false to hide it. Defaults to "top" with two or more series. |
| `title` * | `string` |  | Accessible name of the chart (`aria-label` of the drawing). |
| `animate` | `boolean` |  | Entry animation (default true; always off with prefers-reduced-motion). |
| `className` | `string` |  |  |
| `grid` | `boolean` |  | Background gridlines (default true). |
| `tooltip` | `boolean` |  | Shared tooltip (default true). |
| `orientation` | `"horizontal" \| "vertical"` |  | "horizontal" lays categories top to bottom (bar charts). |
| `barRadius` | `number` |  | Corner radius at the value end of bars, 6 by default. |
| `categories` * | `readonly XValue[]` |  | One entry per data point: strings, numbers or dates. |
| `description` | `string` |  | Extra sentence for the hidden data table caption. |
| `height` | `number \| "fill"` |  | Height of the plot in pixels, 300 by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the plot from the container width (wins over a pixel `height`). |
| `stack` | `"normal" \| "none" \| "percent"` |  | Stacks every area and column series. |
| `dataLabels` | `boolean` |  | Values printed on the marks. |
| `lineGradient` | `boolean` |  | Strokes lines with a gradient from each series color to the next palette color. |
| `transition` | `boolean` |  | Eases lines and areas between data updates (live data); off by default. |
| `maxPoints` | `number \| false` |  | Series with more points than this are reduced with LTTB, 2000 by default; `false` draws every point. |
| `syncId` | `string` |  | Charts with the same id share hover (crosshair and tooltip) and the zoom window. |
| `onPointClick` | `((point: CartesianPointEvent) => void)` |  | Called with the category (and nearest series) under the pointer when the plot is clicked or Enter is pressed. |
| `valueFormat` | `ValueFormat` |  | Format of values in tooltips, labels and the data table. |
| `xFormat` | `((value: XValue) => string)` |  | Label of a category on the axis and in the tooltip (dates get Spanish defaults). |
| `yAxis` | `ValueAxisOptions` |  |  |
| `axes` | `readonly CartesianAxisSpec[]` |  | Any number of value axes. `yAxis` and `rightAxis` are shorthand for the ids "left" and "right"; more entries stack outward on their `side` (right by default) and series pick one with `axis`. |
| `annotations` | `readonly ChartAnnotation[]` |  |  |
| `categoryLabelRotation` | `number` |  | Tilts the category labels (degrees, e.g. -45) so long names fit; vertical charts only. |
| `categoryGroups` | `readonly CategoryGroup[]` |  | Second tier of labels under the category axis (vertical charts); counts must add up to the categories. |
| `onCategoryClick` | `((index: number) => void)` |  | Click (or Enter on the focused plot) on a category; receives its index in `categories`. |
| `overlay` | `CartesianOverlay` |  | Extra layers over the plot, e.g. the ruler and ink tools of `useChartInk`. Vertical charts only. |
| `rangeSelect` | `{ value: readonly [number, number] \| null; onChange: (range: readonly [number, number] \| null) => void; }` |  |  |
| `loading` | `boolean` |  |  |
| `initialHidden` | `readonly string[]` |  | Series hidden at first; the legend can show them. |
| `labels` | `Partial<ChartLabels>` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-barchart--default)
- [Grouped](/storybook/?path=/story/charts-barchart--grouped)
- [Stacked](/storybook/?path=/story/charts-barchart--stacked)
- [Stacked 100%](/storybook/?path=/story/charts-barchart--stacked-percent)
- [Horizontal (top services)](/storybook/?path=/story/charts-barchart--horizontal)
- [Horizontal Stacked](/storybook/?path=/story/charts-barchart--horizontal-stacked)
- [Negative Values](/storybook/?path=/story/charts-barchart--negative-values)
- [Annotation (weekly goal)](/storybook/?path=/story/charts-barchart--with-goal)
- [Data Labels](/storybook/?path=/story/charts-barchart--data-labels)
- [Custom Data Labels](/storybook/?path=/story/charts-barchart--custom-data-labels)
- [Distributed (a color per bar)](/storybook/?path=/story/charts-barchart--distributed)
- [Rotated Labels](/storybook/?path=/story/charts-barchart--rotated-labels)
- [Range column (shifts)](/storybook/?path=/story/charts-barchart--range-column)
- [Range bar (service duration)](/storybook/?path=/story/charts-barchart--range-bar)
- [Grouped stacked (income vs costs)](/storybook/?path=/story/charts-barchart--grouped-stacked)
- [Group labels (quarters)](/storybook/?path=/story/charts-barchart--group-labels)
- [Reversed value axis](/storybook/?path=/story/charts-barchart--reversed)
- [Patterns (color-blind friendly)](/storybook/?path=/story/charts-barchart--patterned)
- [Patterned Stacked](/storybook/?path=/story/charts-barchart--patterned-stacked)
- [Drilldown](/storybook/?path=/story/charts-barchart--drilldown)
- [Race (animated re-sort)](/storybook/?path=/story/charts-barchart--race)
- [Loading](/storybook/?path=/story/charts-barchart--loading)
- [Empty](/storybook/?path=/story/charts-barchart--empty)
- [Fill Parent](/storybook/?path=/story/charts-barchart--fill-parent)
- [Narrow](/storybook/?path=/story/charts-barchart--narrow)

## Source

`packages/ui/src/charts/bar-chart/bar-chart.tsx`

---

# BarRaceChart

> Bar race: horizontal bars that grow, shrink and swap places as time moves through `frames`.

Source: https://ui.jcsoftdev.com/docs/components/bar-race-chart

Bar race: horizontal bars that grow, shrink and swap places as time moves
through `frames`. Play/pause, scrub with the slider, `topN` limits the rows.
Under `prefers-reduced-motion` the bars step from frame to frame.

## Import

```ts
import { BarRaceChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/bar-chart`.

## Usage

```tsx
<BarRaceChart
  title="Citas por barbero esta semana"
  categories={barbers}
  series={[{ id: "citas", name: "Citas", data: appointmentsThisWeek }]}
  valueFormat="integer"
  orientation="vertical"
  stack="none"
  barRadius={6}
  height={300}
  dataLabels={false}
  grid
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `entities` * | `readonly BarRaceEntity[]` |  |  |
| `frames` * | `readonly RaceFrame[]` |  | One entry per moment; `values[i]` belongs to `entities[i]`. |
| `title` * | `string` |  | Accessible name of the chart. |
| `description` | `string` |  |  |
| `topN` | `number` | `6` | How many bars race at once (default 6). |
| `frameDuration` | `number` | `1400` | Milliseconds between two frames (default 1400). |
| `defaultPlaying` | `boolean` | `true` | Starts playing (default true; reduced motion starts paused). |
| `loop` | `boolean` | `true` | Starts over after the last frame (default true). |
| `valueFormat` | `ValueFormat` |  |  |
| `height` | `number \| "fill"` | `340` |  |
| `aspectRatio` | `number` |  |  |
| `loading` | `boolean` |  |  |
| `playLabel` | `string` | `"Play"` |  |
| `pauseLabel` | `string` | `"Pause"` |  |
| `momentLabel` | `string` | `"Moment"` | Accessible name of the moment slider. |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-barchart--default)
- [Grouped](/storybook/?path=/story/charts-barchart--grouped)
- [Stacked](/storybook/?path=/story/charts-barchart--stacked)
- [Stacked 100%](/storybook/?path=/story/charts-barchart--stacked-percent)
- [Horizontal (top services)](/storybook/?path=/story/charts-barchart--horizontal)
- [Horizontal Stacked](/storybook/?path=/story/charts-barchart--horizontal-stacked)
- [Negative Values](/storybook/?path=/story/charts-barchart--negative-values)
- [Annotation (weekly goal)](/storybook/?path=/story/charts-barchart--with-goal)
- [Data Labels](/storybook/?path=/story/charts-barchart--data-labels)
- [Custom Data Labels](/storybook/?path=/story/charts-barchart--custom-data-labels)
- [Distributed (a color per bar)](/storybook/?path=/story/charts-barchart--distributed)
- [Rotated Labels](/storybook/?path=/story/charts-barchart--rotated-labels)
- [Range column (shifts)](/storybook/?path=/story/charts-barchart--range-column)
- [Range bar (service duration)](/storybook/?path=/story/charts-barchart--range-bar)
- [Grouped stacked (income vs costs)](/storybook/?path=/story/charts-barchart--grouped-stacked)
- [Group labels (quarters)](/storybook/?path=/story/charts-barchart--group-labels)
- [Reversed value axis](/storybook/?path=/story/charts-barchart--reversed)
- [Patterns (color-blind friendly)](/storybook/?path=/story/charts-barchart--patterned)
- [Patterned Stacked](/storybook/?path=/story/charts-barchart--patterned-stacked)
- [Drilldown](/storybook/?path=/story/charts-barchart--drilldown)
- [Race (animated re-sort)](/storybook/?path=/story/charts-barchart--race)
- [Loading](/storybook/?path=/story/charts-barchart--loading)
- [Empty](/storybook/?path=/story/charts-barchart--empty)
- [Fill Parent](/storybook/?path=/story/charts-barchart--fill-parent)
- [Narrow](/storybook/?path=/story/charts-barchart--narrow)

## Source

`packages/ui/src/charts/bar-chart/bar-race-chart.tsx`

---

# BeeswarmChart

> Beeswarm: every observation is a dot on the value axis, nudged sideways just enough that no two overlap, so clusters read as density while each point stays individually explorable.

Source: https://ui.jcsoftdev.com/docs/components/beeswarm-chart

Beeswarm: every observation is a dot on the value axis, nudged sideways
just enough that no two overlap, so clusters read as density while each
point stays individually explorable.

## Import

```ts
import { BeeswarmChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/beeswarm-chart`.

## Usage

```tsx
<BeeswarmChart
  title="Duración de cada corte por barbero"
  series={[{ id: "corte", name: "Corte", points: haircut(201) }]}
  valueFormat={minutes}
  valueAxis={{ title: "min" }}
  orientation="horizontal"
  radius={4.5}
  gap={1.25}
  grid
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `series` * | `readonly BeeswarmSeries[]` |  | Colors and legend; points of every series share the rows. |
| `categories` | `readonly string[]` |  | Row order; derived from the points (first seen first) when omitted. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | "horizontal": values along x, one row per category. "vertical": one column per category. |
| `valueFormat` | `ValueFormat` |  |  |
| `valueAxis` | `DistributionAxisOptions` |  |  |
| `radius` | `number` | `4.5` | Radius of every point when there are no sizes (pixels). |
| `sizeRange` | `readonly [number, number]` | `[3, 14]` | Radius range for sized points: the largest size gets `max`, area-proportional. |
| `sizeFormat` | `ValueFormat` |  |  |
| `gap` | `number` | `1.25` | Space between points (pixels). |
| `height` | `number \| "fill"` |  | Height of the drawing; grows with the number of rows by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `grid` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `labels` | `Partial<DistributionLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-beeswarmchart--default)
- [Vertical](/storybook/?path=/story/charts-beeswarmchart--vertical)
- [Sized By Ticket](/storybook/?path=/story/charts-beeswarmchart--sized-by-ticket)
- [Colored By Series](/storybook/?path=/story/charts-beeswarmchart--colored-by-series)
- [Narrow](/storybook/?path=/story/charts-beeswarmchart--narrow)
- [Loading](/storybook/?path=/story/charts-beeswarmchart--loading)
- [Empty](/storybook/?path=/story/charts-beeswarmchart--empty)

## Source

`packages/ui/src/charts/beeswarm-chart/beeswarm-chart.tsx`

---

# BoxGlyph

> One box-and-whisker: IQR box, median line, whiskers with caps, optional mean diamond and outlier dots.

Source: https://ui.jcsoftdev.com/docs/components/box-glyph

One box-and-whisker: IQR box, median line, whiskers with caps, optional
mean diamond and outlier dots. Pure SVG, memoised.

## Import

```ts
import { BoxGlyph } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
<BoxGlyph
  stats={stats}
  map={vertical}
  center={WIDTH / 2}
  size={64}
  horizontal={false}
  variant="box"
  showMean
  showOutliers
  dimmed={false}
  active={false}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stats` * | `BoxStats` |  |  |
| `map` * | `(value: number) => number` |  | Value to pixel along the value axis. |
| `center` * | `number` |  | Pixel of the box axis on the cross axis. |
| `size` * | `number` |  | Box thickness in pixels. |
| `horizontal` * | `boolean` |  |  |
| `color` * | `string` |  |  |
| `variant` | `"box" \| "inner"` | `"box"` | "box": soft fill and colored outline. "inner": slim dark box for violins and rainclouds. |
| `showMean` | `boolean` | `true` |  |
| `showOutliers` | `boolean` | `true` |  |
| `activeOutlier` | `number \| null` |  | Highlighted outlier value (keyboard or pointer). |
| `dimmed` | `boolean` |  |  |
| `active` | `boolean` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-boxglyph--default)
- [Horizontal](/storybook/?path=/story/charts-primitives-boxglyph--horizontal)
- [Inner Variant](/storybook/?path=/story/charts-primitives-boxglyph--inner-variant)
- [Without Mean And Outliers](/storybook/?path=/story/charts-primitives-boxglyph--without-mean-and-outliers)
- [Active](/storybook/?path=/story/charts-primitives-boxglyph--active)
- [Dimmed](/storybook/?path=/story/charts-primitives-boxglyph--dimmed)

## Source

`packages/ui/src/charts/core/distribution/marks.tsx`

---

# BoxPlot

> Box-and-whisker plot: median, quartiles, Tukey whiskers, outliers and the mean for every category, optionally grouped by series.

Source: https://ui.jcsoftdev.com/docs/components/box-plot

Box-and-whisker plot: median, quartiles, Tukey whiskers, outliers and the
mean for every category, optionally grouped by series.

## Import

```ts
import { BoxPlot } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/box-plot`.

## Usage

```tsx
<BoxPlot
  title="Duración del corte por barbero"
  categories={barbers}
  series={[{ id: "corte", name: "Corte", data: haircutMinutes }]}
  valueFormat={minutes}
  valueAxis={{ title: "min" }}
  orientation="vertical"
  whisker={1.5}
  showMean
  showOutliers
  height={320}
  grid
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the chart and caption of its data table. |
| `categories` * | `readonly string[]` |  | One box (per series) for each category, e.g. the barbers. |
| `series` * | `readonly DistributionSeries[]` |  | `data[i]` holds the raw samples of `categories[i]`. Several series are drawn side by side. |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | "vertical": boxes stand on the x axis. "horizontal": one row per category. |
| `valueFormat` | `ValueFormat` |  |  |
| `valueAxis` | `DistributionAxisOptions` |  |  |
| `whisker` | `number` | `1.5` | Tukey fence multiplier; `Infinity` stretches the whiskers to min and max. |
| `showMean` | `boolean` | `true` | Diamond on the mean. |
| `showOutliers` | `boolean` | `true` | Dots for values outside the whiskers. |
| `showPoints` | `boolean` | `false` | Every raw observation as a dot over the box, with deterministic jitter. |
| `jitter` | `number` | `0.7` | Share (0-1) of the box width the dots spread over. |
| `pointColor` | `"value" \| "series"` | `"series"` | "value" grades each dot from pale to full colour across the value range. |
| `seed` | `number` | `11` | Seed of the jitter, so the dots are stable between renders. |
| `height` | `number \| "fill"` | `320` | Height of the drawing in pixels. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `legend` | `boolean \| "top" \| "bottom"` |  | Shown automatically with more than one series. |
| `grid` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `labels` | `Partial<DistributionLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-boxplot--default)
- [Horizontal](/storybook/?path=/story/charts-boxplot--horizontal)
- [Grouped By Series](/storybook/?path=/story/charts-boxplot--grouped-by-series)
- [With Points](/storybook/?path=/story/charts-boxplot--with-points)
- [Jitter](/storybook/?path=/story/charts-boxplot--jitter)
- [Average Ticket](/storybook/?path=/story/charts-boxplot--average-ticket)
- [Whiskers To Extremes](/storybook/?path=/story/charts-boxplot--whiskers-to-extremes)
- [Narrow](/storybook/?path=/story/charts-boxplot--narrow)
- [Loading](/storybook/?path=/story/charts-boxplot--loading)
- [Empty](/storybook/?path=/story/charts-boxplot--empty)

## Source

`packages/ui/src/charts/box-plot/box-plot.tsx`

---

# BoxStatsTable

> Hidden data table with the summary of every box, violin or cloud.

Source: https://ui.jcsoftdev.com/docs/components/box-stats-table

Hidden data table with the summary of every box, violin or cloud.

## Import

```ts
import { BoxStatsTable } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
<BoxStatsTable
  caption="Duración del servicio por barbero"
  labels={labels}
  rows={[
      { name: "Kevin", stats: boxStats(kevin), format: minutes },
      { name: "Diego", stats: boxStats(diego), format: minutes },
      { name: "Andrea", stats: boxStats(andrea), format: minutes },
      { name: "Renzo", stats: null, format: minutes },
    ]}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `caption` * | `string` |  |  |
| `labels` * | `DistributionLabels` |  |  |
| `rows` * | `readonly { name: string; stats: BoxStats \| null; format: ValueFormatter; }[]` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-boxstatstable--default)
- [Single Row](/storybook/?path=/story/charts-primitives-boxstatstable--single-row)

## Source

`packages/ui/src/charts/core/distribution/marks.tsx`

---

# BubbleChart

> Bubble chart: x, y and a third value as the bubble's area (radius grows with the square root, so twice the value is twice the ink).

Source: https://ui.jcsoftdev.com/docs/components/bubble-chart

Bubble chart: x, y and a third value as the bubble's area (radius grows
with the square root, so twice the value is twice the ink). Labels sit
inside large bubbles and next to small ones; a size key explains the scale.

## Import

```ts
import { BubbleChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/bubble-chart`.

## Usage

```tsx
<BubbleChart
  title="Servicios: duración, ticket y volumen"
  series={[{ id: "servicios", name: "Servicios", points: services }]}
  xFormat={minutes}
  yFormat="currency"
  sizeFormat="integer"
  xAxis={{ title: "Duración media (min)" }}
  yAxis={{ title: "Ticket (S/)" }}
  sizeRange={[4, 34]}
  showLabels
  sizeLegend
  trendLine={false}
  height={360}
  grid
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `title` * | `string` |  |  |
| `animate` | `boolean` |  |  |
| `className` | `string` |  |  |
| `grid` | `boolean` |  |  |
| `tooltip` | `boolean` |  |  |
| `series` * | `readonly XYSeries[]` |  |  |
| `height` | `number \| "fill"` |  |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `xFormat` | `ValueFormat` |  |  |
| `yAxis` | `DistributionAxisOptions` |  |  |
| `brush` | `XYBrush` |  | Rectangular brush over the plot (pointer drag plus keyboard). |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<DistributionLabels>` |  |  |
| `yFormat` | `ValueFormat` |  |  |
| `sizeFormat` | `ValueFormat` |  |  |
| `xAxis` | `DistributionAxisOptions` |  |  |
| `trendLine` | `boolean` |  | Least-squares line per series, drawn over its x range. |
| `quadrants` | `QuadrantOptions` |  |  |
| `sizeRange` | `readonly [number, number]` |  |  |
| `xType` | `"time" \| "linear"` |  | "time": `x` is epoch milliseconds and the axis shows calendar ticks. |
| `jitter` | `number \| { x?: number; y?: number; }` |  | Deterministic displacement in pixels that separates overlapping points (a number applies to both axes). Tooltips still show the true values. |
| `seed` | `number` |  | Seed of the jitter, so points are stable between renders. |
| `renderer` | `"canvas" \| "svg"` |  | "canvas" paints the marks on a canvas for tens of thousands of points; axes, tooltip and keyboard stay SVG/HTML. Falls back to SVG when points carry images or `shading` is "shaded". |
| `shading` | `"flat" \| "shaded"` |  | "shaded" fills bubbles with an off-centre radial gradient so they read as spheres. |
| `showLabels` | `boolean` | `true` | Text labels next to (or inside) the points that have a `label`. |
| `sizeLegend` | `boolean` |  | Reference circles explaining the bubble sizes, under the plot. |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-bubblechart--default)
- [Barbers By Branch](/storybook/?path=/story/charts-bubblechart--barbers-by-branch)
- [With Quadrants](/storybook/?path=/story/charts-bubblechart--with-quadrants)
- [Shaded 3 D](/storybook/?path=/story/charts-bubblechart--shaded-3-d)
- [Without Labels](/storybook/?path=/story/charts-bubblechart--without-labels)
- [Narrow](/storybook/?path=/story/charts-bubblechart--narrow)
- [Loading](/storybook/?path=/story/charts-bubblechart--loading)
- [Empty](/storybook/?path=/story/charts-bubblechart--empty)

## Source

`packages/ui/src/charts/bubble-chart/bubble-chart.tsx`

---

# BubbleMap

> Markers on a map by longitude and latitude, sized by value (area proportional) and colored by category, with optional clustering.

Source: https://ui.jcsoftdev.com/docs/components/bubble-map

Markers on a map by longitude and latitude, sized by value (area
proportional) and colored by category, with optional clustering. Sizes stay
in screen pixels while you zoom. Hover or arrow keys select a marker (keyboard
order follows the visible bubbles), click or Enter calls `onPointClick`
(a cluster zooms in instead), `+` / `-` zoom, `0` fits.

## Import

```ts
import { BubbleMap } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/bubble-map`.

## Usage

```tsx
<BubbleMap
  title="Sedes en Lima"
  map={limaMap}
  points={branches}
  categories={categories}
  valueName="Citas al mes"
  valueFormat="integer"
  minRadius={5}
  maxRadius={22}
  cluster={false}
  clusterDistance={36}
  regionLabels={false}
  legend
  tooltip
  zoomable
  wheelZoom="always"
  maxZoom={16}
  animate
  loading={false}
  labels={spanishLabels}
  height={480}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `map` * | `GeoMap` |  | Base map under the markers, e.g. `peruMap`. |
| `points` * | `readonly MapPoint[]` |  |  |
| `categories` | `readonly BubbleMapCategory[]` |  | Legend entries and colors; derived from the points' `category` by order when omitted. |
| `valueFormat` | `ValueFormat` |  |  |
| `valueName` | `string` |  | Name of the value in the tooltip and the data table, e.g. "Citas". |
| `projection` | `"equirectangular" \| "mercator" \| "equalEarth" \| "fitted"` |  |  |
| `minRadius` | `number` | `6` | Area-proportional bubbles between these radii (px). Points without `value` use `minRadius`. |
| `maxRadius` | `number` | `28` |  |
| `cluster` | `boolean` | `false` | Merge markers closer than `clusterDistance` px into one bubble (count inside, click to zoom in). |
| `clusterDistance` | `number` | `36` |  |
| `regionLabels` | `boolean` | `false` | Write the region names on the base map where they fit. |
| `routes` | `readonly MapRoute[]` | `[]` | Flows between places, drawn as arcs under the bubbles with animated dashes. |
| `routeStyle` | `"curve" \| "great-circle"` | `"curve"` | "curve": a soft arch in screen space (regions); "great-circle": the shortest path on the globe (world). |
| `routeBend` | `number` | `0.25` | Arch height of a "curve" as a fraction of the distance (0 straight, default 0.25). |
| `animateRoutes` | `boolean` | `true` | Marching dashes along the routes; off under `prefers-reduced-motion`. |
| `height` | `number \| "fill"` |  |  |
| `aspectRatio` | `number` |  |  |
| `legend` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `zoomable` | `boolean` | `true` |  |
| `wheelZoom` | `"always" \| "modifier"` | `"modifier"` |  |
| `maxZoom` | `number` | `16` |  |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<MapLabels>` |  |  |
| `onPointClick` | `((point: MapPoint) => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-bubblemap--default)
- [With Region Names](/storybook/?path=/story/charts-bubblemap--with-region-names)
- [Clustered](/storybook/?path=/story/charts-bubblemap--clustered)
- [Clustering Off](/storybook/?path=/story/charts-bubblemap--clustering-off)
- [World](/storybook/?path=/story/charts-bubblemap--world)
- [Routes](/storybook/?path=/story/charts-bubblemap--routes)
- [Routes World](/storybook/?path=/story/charts-bubblemap--routes-world)
- [Routes Narrow](/storybook/?path=/story/charts-bubblemap--routes-narrow)
- [Loading](/storybook/?path=/story/charts-bubblemap--loading)
- [Empty](/storybook/?path=/story/charts-bubblemap--empty)
- [Narrow](/storybook/?path=/story/charts-bubblemap--narrow)
- [Fill Parent](/storybook/?path=/story/charts-bubblemap--fill-parent)

## Source

`packages/ui/src/charts/bubble-map/bubble-map.tsx`

---

# CalendarHeatmap

> Contribution-style calendar: one square per day, weeks as columns (Monday first), months labelled on top.

Source: https://ui.jcsoftdev.com/docs/components/calendar-heatmap

Contribution-style calendar: one square per day, weeks as columns (Monday
first), months labelled on top. Same color scales, ranges, crosshair and
keyboard model as `HeatmapChart`.

## Import

```ts
import { CalendarHeatmap } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/heatmap-chart`.

## Usage

```tsx
<CalendarHeatmap
  title="Ocupación de sillas por hora y día"
  rows={days}
  columns={hours}
  values={occupancy}
  scale="sequential"
  valueFormat={percent}
  domain={[0, 100]}
  cellLabels={false}
  gap={3}
  radius={4}
  legend
  tooltip
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the drawing and caption of the data table. |
| `days` * | `readonly CalendarDay[]` |  | One entry per day; missing days inside the range are drawn empty. |
| `from` | `Date` |  | First day shown; the earliest entry by default. |
| `to` | `Date` |  | Last day shown; the latest entry by default. |
| `scale` | `"sequential" \| "diverging"` | `"sequential"` |  |
| `domain` | `readonly [number, number]` |  |  |
| `center` | `number` | `0` |  |
| `colors` | `ScaleColors` |  |  |
| `ranges` | `readonly ColorRange[]` |  | Stepped coloring, e.g. "Sin citas", "1-5", "6-10", "Más de 10". |
| `valueFormat` | `ValueFormat` |  |  |
| `minCellSize` | `number` | `11` | Smallest cell in pixels; narrow containers show only the most recent weeks that fit. |
| `height` | `number \| "fill"` |  | Height of the drawing in px or "fill". By default it follows the width: cells are square, so the height is the month header plus seven cell sides. |
| `aspectRatio` | `number` |  | Width / height ratio; overrides the width-derived default height. |
| `gap` | `number` | `3` |  |
| `radius` | `number` | `3` |  |
| `weekdays` | `readonly string[]` | `WEEKDAYS` | Weekday names Monday to Sunday; only Monday, Wednesday and Friday are drawn. |
| `legend` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<HeatmapLabels>` |  |  |
| `onDayClick` | `((day: CalendarDay) => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-heatmapchart--default)
- [Cell Labels](/storybook/?path=/story/charts-heatmapchart--cell-labels)
- [Diverging](/storybook/?path=/story/charts-heatmapchart--diverging)
- [Ranges](/storybook/?path=/story/charts-heatmapchart--ranges)
- [Missing Data](/storybook/?path=/story/charts-heatmapchart--missing-data)
- [Calendar](/storybook/?path=/story/charts-heatmapchart--calendar)
- [Calendar Ranges](/storybook/?path=/story/charts-heatmapchart--calendar-ranges)
- [Rounded](/storybook/?path=/story/charts-heatmapchart--rounded)
- [Honeycomb](/storybook/?path=/story/charts-heatmapchart--honeycomb)
- [Continuous Datetime](/storybook/?path=/story/charts-heatmapchart--continuous-datetime)
- [Canvas Dense](/storybook/?path=/story/charts-heatmapchart--canvas-dense)
- [Drilldown](/storybook/?path=/story/charts-heatmapchart--drilldown)
- [Narrow Drilldown](/storybook/?path=/story/charts-heatmapchart--narrow-drilldown)
- [Loading](/storybook/?path=/story/charts-heatmapchart--loading)
- [Empty](/storybook/?path=/story/charts-heatmapchart--empty)
- [Narrow](/storybook/?path=/story/charts-heatmapchart--narrow)
- [Narrow Calendar](/storybook/?path=/story/charts-heatmapchart--narrow-calendar)

## Source

`packages/ui/src/charts/heatmap-chart/calendar-heatmap.tsx`

---

# CandlestickChart

> Open-high-low-close candles with up and down tokens, optional volume bars on the same x axis, a last-price line and a brush to zoom.

Source: https://ui.jcsoftdev.com/docs/components/candlestick-chart

Open-high-low-close candles with up and down tokens, optional volume bars
on the same x axis, a last-price line and a brush to zoom. Arrow keys walk
the candles; the tooltip reads open, high, low, close, change and volume.

## Import

```ts
import { CandlestickChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/candlestick-chart`.

## Usage

```tsx
<CandlestickChart
  title="Precio semanal de la pomada (S/ por unidad)"
  data={insumo}
  valueFormat="currency"
  volumeFormat="integer"
  height={380}
  candleStyle="filled"
  brush={false}
  lastPrice
  grid
  legend
  tooltip
  loading={false}
  animate
  texts={spanishTexts}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` * | `readonly Candle[]` |  |  |
| `title` * | `string` |  | Accessible name of the chart. |
| `description` | `string` |  |  |
| `height` | `number \| "fill"` | `360` | Height of the plot (price and volume), 360 by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the chart from the container width. |
| `volume` | `boolean` |  | Volume bars below the price, sharing the x axis. Default: shown when any candle has a volume. |
| `candleStyle` | `"filled" \| "hollow"` | `"filled"` | "filled" paints every body; "hollow" leaves rising candles empty. |
| `brush` | `boolean` | `false` | Overview with a draggable view to zoom the x axis. |
| `lastPrice` | `boolean` | `true` | Dashed line and tag at the last close (default true). |
| `valueFormat` | `ValueFormat` |  |  |
| `volumeFormat` | `ValueFormat` | `"compact"` |  |
| `xFormat` | `((value: XValue) => string)` |  |  |
| `upColor` | `string` | `DIRECTION_COLORS.up` | Overrides the rising color (default the `chart-up` token). |
| `downColor` | `string` | `DIRECTION_COLORS.down` | Overrides the falling color (default the `chart-down` token). |
| `grid` | `boolean` | `true` |  |
| `legend` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `texts` | `Partial<CandlestickTexts>` |  |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-candlestickchart--default)
- [Brush Zoom](/storybook/?path=/story/charts-candlestickchart--brush-zoom)
- [Hollow](/storybook/?path=/story/charts-candlestickchart--hollow)
- [With Volume](/storybook/?path=/story/charts-candlestickchart--with-volume)
- [Price Only](/storybook/?path=/story/charts-candlestickchart--price-only)
- [Daily Cash](/storybook/?path=/story/charts-candlestickchart--daily-cash)
- [Loading](/storybook/?path=/story/charts-candlestickchart--loading)
- [Empty](/storybook/?path=/story/charts-candlestickchart--empty)
- [Narrow](/storybook/?path=/story/charts-candlestickchart--narrow)

## Source

`packages/ui/src/charts/candlestick-chart/candlestick-chart.tsx`

---

# CartesianChart

> The cartesian engine.

Source: https://ui.jcsoftdev.com/docs/components/cartesian-chart

The cartesian engine. Line, area and column series share one plot, one
value axis (plus an optional right axis), the legend, tooltip, keyboard
exploration, annotations, entry animation and the zoom brush.
`LineChart`, `AreaChart`, `BarChart` and `ComboChart` are presets of it.

## Import

```ts
import { CartesianChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
<CartesianChart
  title="Ventas por servicio"
  categories={weekdays}
  series={[
      { id: "cortes", name: "Cortes", kind: "column", data: cuts },
      { id: "barba", name: "Barba", kind: "column", data: beard },
    ]}
  valueFormat="currency"
  height={300}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `categories` * | `readonly XValue[]` |  | One entry per data point: strings, numbers or dates. |
| `series` * | `readonly CartesianSeries[]` |  |  |
| `title` * | `string` |  | Accessible name of the chart (`aria-label` of the drawing). |
| `description` | `string` |  | Extra sentence for the hidden data table caption. |
| `height` | `number \| "fill"` | `300` | Height of the plot in pixels, 300 by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the plot from the container width (wins over a pixel `height`). |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | "horizontal" lays categories top to bottom (bar charts). |
| `stack` | `"normal" \| "none" \| "percent"` | `"none"` | Stacks every area and column series. |
| `curve` | `"linear" \| "smooth" \| "step" \| "step-before" \| "step-after"` | `"linear"` |  |
| `markers` | `boolean` | `false` | Dots on every line point. Hovered points are always marked. |
| `dataLabels` | `boolean` | `false` | Values printed on the marks. |
| `lineGradient` | `boolean` | `false` | Strokes lines with a gradient from each series color to the next palette color. |
| `transition` | `boolean` | `false` | Eases lines and areas between data updates (live data); off by default. |
| `maxPoints` | `number \| false` | `DEFAULT_MAX_POINTS` | Series with more points than this are reduced with LTTB, 2000 by default; `false` draws every point. |
| `syncId` | `string` |  | Charts with the same id share hover (crosshair and tooltip) and the zoom window. |
| `onPointClick` | `((point: CartesianPointEvent) => void)` |  | Called with the category (and nearest series) under the pointer when the plot is clicked or Enter is pressed. |
| `gradient` | `boolean` | `true` | Gradient fill under areas (default true). |
| `barRadius` | `number` | `6` | Corner radius at the value end of bars, 6 by default. |
| `valueFormat` | `ValueFormat` |  | Format of values in tooltips, labels and the data table. |
| `xFormat` | `((value: XValue) => string)` |  | Label of a category on the axis and in the tooltip (dates get Spanish defaults). |
| `xScale` | `"time" \| "auto" \| "band"` | `"auto"` | "time" spaces dates by real elapsed time; "auto" picks it when every category is a Date and no series is a column. |
| `yAxis` | `ValueAxisOptions` |  |  |
| `rightAxis` | `ValueAxisOptions` |  | Secondary axis for series with `axis: "right"`. |
| `axes` | `readonly CartesianAxisSpec[]` |  | Any number of value axes. `yAxis` and `rightAxis` are shorthand for the ids "left" and "right"; more entries stack outward on their `side` (right by default) and series pick one with `axis`. |
| `grid` | `boolean` | `true` | Background gridlines (default true). |
| `legend` | `boolean \| "top" \| "bottom"` |  | Legend placement, or false to hide it. Defaults to "top" with two or more series. |
| `tooltip` | `boolean` | `true` | Shared tooltip (default true). |
| `annotations` | `readonly ChartAnnotation[]` |  |  |
| `categoryLabelRotation` | `number` |  | Tilts the category labels (degrees, e.g. -45) so long names fit; vertical charts only. |
| `categoryGroups` | `readonly CategoryGroup[]` |  | Second tier of labels under the category axis (vertical charts); counts must add up to the categories. |
| `onCategoryClick` | `((index: number) => void)` |  | Click (or Enter on the focused plot) on a category; receives its index in `categories`. |
| `brush` | `boolean` | `false` | Drag-to-zoom on the plot plus an overview brush with a reset button. |
| `overlay` | `CartesianOverlay` |  | Extra layers over the plot, e.g. the ruler and ink tools of `useChartInk`. Vertical charts only. |
| `rangeSelect` | `{ value: readonly [number, number] \| null; onChange: (range: readonly [number, number] \| null) => void; }` |  |  |
| `loading` | `boolean` | `false` |  |
| `animate` | `boolean` | `true` | Entry animation (default true; always off with prefers-reduced-motion). |
| `initialHidden` | `readonly string[]` |  | Series hidden at first; the legend can show them. |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-cartesianchart--default)
- [Stacked](/storybook/?path=/story/charts-primitives-cartesianchart--stacked)
- [Horizontal](/storybook/?path=/story/charts-primitives-cartesianchart--horizontal)
- [Columns And Line On Right Axis](/storybook/?path=/story/charts-primitives-cartesianchart--columns-and-line-on-right-axis)
- [Area With Goal](/storybook/?path=/story/charts-primitives-cartesianchart--area-with-goal)
- [With Brush](/storybook/?path=/story/charts-primitives-cartesianchart--with-brush)
- [Loading](/storybook/?path=/story/charts-primitives-cartesianchart--loading)
- [Empty](/storybook/?path=/story/charts-primitives-cartesianchart--empty)

## Source

`packages/ui/src/charts/core/cartesian/cartesian-chart.tsx`

---

# CategoryAxes

> Gridlines along the value axis plus both axes of a `categoryLayout`.

Source: https://ui.jcsoftdev.com/docs/components/category-axes

Gridlines along the value axis plus both axes of a `categoryLayout`.

## Import

```ts
import { CategoryAxes } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => <AxesFrame horizontal={false} title={args.title} grid={args.grid} />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `layout` * | `CategoryLayout` |  |  |
| `title` | `string` |  |  |
| `grid` | `boolean` | `true` |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-categoryaxes--default)
- [Horizontal](/storybook/?path=/story/charts-primitives-categoryaxes--horizontal)
- [Without Grid](/storybook/?path=/story/charts-primitives-categoryaxes--without-grid)

## Source

`packages/ui/src/charts/core/distribution/marks.tsx`

---

# CategoryGroupAxis

> Brackets and labels of category groups, placed `offset` pixels below the plot.

Source: https://ui.jcsoftdev.com/docs/components/category-group-axis

Brackets and labels of category groups, placed `offset` pixels below the plot.

## Import

```ts
import { CategoryGroupAxis } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `spans` * | `readonly CategoryGroupSpan[]` |  |  |
| `offset` * | `number` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-categorygroupaxis--default)
- [Narrow](/storybook/?path=/story/charts-primitives-categorygroupaxis--narrow)

## Source

`packages/ui/src/charts/core/cartesian/category-group-axis.tsx`

---

# CategorySlider

> Focusable keyboard layer laid over the drawing.

Source: https://ui.jcsoftdev.com/docs/components/category-slider

Focusable keyboard layer laid over the drawing. It ignores the pointer
(`pointer-events: none`), so hovering still reaches the marks underneath.

## Import

```ts
import { CategorySlider } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = { render: () => <Demo /> };
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `explorer` * | `CategoryExplorer` |  |  |
| `label` * | `string` |  |  |
| `count` * | `number` |  |  |
| `valueText` * | `string` |  | What a screen reader hears for the current category. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-categoryslider--default)

## Source

`packages/ui/src/charts/core/category-explorer.tsx`

---

# ChartBreadcrumb

> Drill-down path of a hierarchy chart.

Source: https://ui.jcsoftdev.com/docs/components/chart-breadcrumb

Drill-down path of a hierarchy chart. Every ancestor is a button that
zooms back out to it; the current node is marked with `aria-current`.

## Import

```ts
import { ChartBreadcrumb } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
<ChartBreadcrumb items={trail} label="Ruta de la jerarquía" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` * | `readonly ChartBreadcrumbItem[]` |  | Root first, current node last. |
| `onSelect` * | `(id: string) => void` |  |  |
| `label` * | `string` |  | Accessible name of the navigation landmark. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-chartbreadcrumb--default)
- [Root Only](/storybook/?path=/story/charts-primitives-chartbreadcrumb--root-only)
- [Interactive](/storybook/?path=/story/charts-primitives-chartbreadcrumb--interactive)

## Source

`packages/ui/src/charts/core/breadcrumb.tsx`

---

# ChartBrush

> Overview of the whole series with a draggable window.

Source: https://ui.jcsoftdev.com/docs/components/chart-brush

Overview of the whole series with a draggable window. Drag the window to
pan, its handles to resize, or anywhere outside to draw a new window.
Keyboard: arrows pan, Shift+arrows resize the end, Home/End jump.

## Import

```ts
import { ChartBrush } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => {
    const [range, setRange] = useState<IndexRange>(args.range);
    return (
      <ChartBrush
        {...args}
        range={range}
        onChange={setRange}
        valueText={`Día ${range[0] + 1} al día ${range[1] + 1}`}
      />
    );
  },
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` * | `number` |  | Total number of categories (the full, un-zoomed data). |
| `series` * | `readonly { id: string; color: string; data: ReadonlyArray<number \| null>; }[]` |  | Full-length series drawn as the overview. |
| `indices` | `readonly number[]` |  | Original category index of each entry of `series` when the series were downsampled. |
| `range` * | `IndexRange` |  | Selected window, inclusive indices. |
| `onChange` * | `(range: IndexRange) => void` |  |  |
| `width` * | `number` |  |  |
| `left` * | `number` |  | Align with the plot above. |
| `right` * | `number` |  |  |
| `height` | `number` | `52` |  |
| `label` * | `string` |  |  |
| `valueText` * | `string` |  | Text for screen readers describing the window, e.g. "6 oct – 20 oct". |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-chartbrush--default)
- [Full Range](/storybook/?path=/story/charts-primitives-chartbrush--full-range)

## Source

`packages/ui/src/charts/core/cartesian/brush.tsx`

---

# ChartDataTable

> Visually hidden table with the same numbers as the chart, so the data is reachable by screen readers (and by copy/paste) without relying on color.

Source: https://ui.jcsoftdev.com/docs/components/chart-data-table

Visually hidden table with the same numbers as the chart, so the data is
reachable by screen readers (and by copy/paste) without relying on color.

## Import

```ts
import { ChartDataTable } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
<ChartDataTable
  caption="Ventas por servicio de la semana"
  categoryHeader="Día"
  categories={["Lunes", "Martes", "Miércoles", "Jueves", "Viernes", "Sábado"]}
  columns={[
      {
        id: "cortes",
        name: "Cortes",
        values: ["S/ 420", "S/ 380", "S/ 450", "S/ 510", "S/ 690", "S/ 840"],
      },
      {
        id: "barba",
        name: "Barba",
        values: ["S/ 150", "S/ 120", "S/ 180", "S/ 210", "S/ 260", "S/ 390"],
      },
    ]}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `caption` * | `string` |  |  |
| `categoryHeader` * | `string` |  | Header of the first column. |
| `categories` * | `readonly string[]` |  | Row headers, already formatted. |
| `columns` * | `readonly { id: string; name: string; values: ReadonlyArray<string>; }[]` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-chartdatatable--default)
- [Missing Values](/storybook/?path=/story/charts-primitives-chartdatatable--missing-values)

## Source

`packages/ui/src/charts/core/data-table.tsx`

---

# ChartEmpty

> Shown when there is nothing to plot: keeps the chart's footprint, says why.

Source: https://ui.jcsoftdev.com/docs/components/chart-empty

Shown when there is nothing to plot: keeps the chart's footprint, says why.

## Import

```ts
import { ChartEmpty } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {
  render: () => <AxesDemo title="Ventas" rightTitle="Cortes" showRight={false} showGrid />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `height` * | `number` |  |  |
| `label` * | `string` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-axes--default)
- [Dual Axis](/storybook/?path=/story/charts-primitives-axes--dual-axis)
- [Without Grid](/storybook/?path=/story/charts-primitives-axes--without-grid)
- [Default](/storybook/?path=/story/charts-primitives-cartesianchart--default)
- [Stacked](/storybook/?path=/story/charts-primitives-cartesianchart--stacked)
- [Horizontal](/storybook/?path=/story/charts-primitives-cartesianchart--horizontal)
- [Columns And Line On Right Axis](/storybook/?path=/story/charts-primitives-cartesianchart--columns-and-line-on-right-axis)
- [Area With Goal](/storybook/?path=/story/charts-primitives-cartesianchart--area-with-goal)
- [With Brush](/storybook/?path=/story/charts-primitives-cartesianchart--with-brush)
- [Loading](/storybook/?path=/story/charts-primitives-cartesianchart--loading)
- [Empty](/storybook/?path=/story/charts-primitives-cartesianchart--empty)
- [Default](/storybook/?path=/story/charts-primitives-categoryslider--default)
- [Default](/storybook/?path=/story/charts-primitives-chartbreadcrumb--default)
- [Root Only](/storybook/?path=/story/charts-primitives-chartbreadcrumb--root-only)
- [Interactive](/storybook/?path=/story/charts-primitives-chartbreadcrumb--interactive)
- [Default](/storybook/?path=/story/charts-primitives-chartbrush--default)
- [Full Range](/storybook/?path=/story/charts-primitives-chartbrush--full-range)
- [Default](/storybook/?path=/story/charts-primitives-chartdatatable--default)
- [Missing Values](/storybook/?path=/story/charts-primitives-chartdatatable--missing-values)
- [Default](/storybook/?path=/story/charts-primitives-chartframe--default)
- [Fills Parent](/storybook/?path=/story/charts-primitives-chartframe--fills-parent)
- [Aspect Ratio](/storybook/?path=/story/charts-primitives-chartframe--aspect-ratio)
- [With Legend And Table](/storybook/?path=/story/charts-primitives-chartframe--with-legend-and-table)
- [Loading](/storybook/?path=/story/charts-primitives-chartframe--loading)
- [Loading Ring](/storybook/?path=/story/charts-primitives-chartframe--loading-ring)
- [Empty](/storybook/?path=/story/charts-primitives-chartframe--empty)
- [Read Only](/storybook/?path=/story/charts-primitives-chartlegend--read-only)
- [Toggleable](/storybook/?path=/story/charts-primitives-chartlegend--toggleable)
- [Centered](/storybook/?path=/story/charts-primitives-chartlegend--centered)
- [Bars](/storybook/?path=/story/charts-primitives-chartskeleton--bars)
- [Line](/storybook/?path=/story/charts-primitives-chartskeleton--line)
- [Ring](/storybook/?path=/story/charts-primitives-chartskeleton--ring)
- [Empty](/storybook/?path=/story/charts-primitives-chartskeleton--empty)
- [Default](/storybook/?path=/story/charts-primitives-charttooltip--default)
- [Flips Near The Right Edge](/storybook/?path=/story/charts-primitives-charttooltip--flips-near-the-right-edge)
- [Without Title](/storybook/?path=/story/charts-primitives-charttooltip--without-title)
- [Default](/storybook/?path=/story/charts-primitives-exportmenu--default)
- [Spanish](/storybook/?path=/story/charts-primitives-exportmenu--spanish)
- [Default](/storybook/?path=/story/charts-primitives-hierarchyheader--default)
- [At Root](/storybook/?path=/story/charts-primitives-hierarchyheader--at-root)
- [Default](/storybook/?path=/story/charts-primitives-hierarchylegend--default)
- [Drilled In](/storybook/?path=/story/charts-primitives-hierarchylegend--drilled-in)
- [Limited](/storybook/?path=/story/charts-primitives-hierarchylegend--limited)
- [Leaf](/storybook/?path=/story/charts-primitives-hierarchylegend--leaf)
- [Default](/storybook/?path=/story/charts-primitives-hierarchytable--default)
- [From Branch](/storybook/?path=/story/charts-primitives-hierarchytable--from-branch)
- [Gallery](/storybook/?path=/story/charts-primitives-chartpatterndefs--gallery)
- [Custom Tile](/storybook/?path=/story/charts-primitives-chartpatterndefs--custom-tile)
- [Default](/storybook/?path=/story/charts-primitives-plotoverlay--default)
- [Vertical Keys](/storybook/?path=/story/charts-primitives-plotoverlay--vertical-keys)
- [Both Axes Keys](/storybook/?path=/story/charts-primitives-plotoverlay--both-axes-keys)
- [Default](/storybook/?path=/story/charts-primitives-unitglyph--default)
- [Fills Up](/storybook/?path=/story/charts-primitives-unitglyph--fills-up)
- [Scissors](/storybook/?path=/story/charts-primitives-unitglyph--scissors)
- [Without Track](/storybook/?path=/story/charts-primitives-unitglyph--without-track)

## Source

`packages/ui/src/charts/core/chart-states.tsx`

---

# ChartFrame

> Shared outer shell for every chart: measures its slot (width and, when filling, height), swaps in the loading or empty state, and places the legend, drawing, footer and the hidden…

Source: https://ui.jcsoftdev.com/docs/components/chart-frame

Shared outer shell for every chart: measures its slot (width and, when
filling, height), swaps in the loading or empty state, and places the
legend, drawing, footer and the hidden data table in a consistent order.
The root has no padding or margin: the drawing touches the container edges.

## Import

```ts
import { ChartFrame } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
<ChartFrame height={260} labels={labels}>
  {Columns}
</ChartFrame>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `height` * | `number \| "fill" \| ((width: number) => number)` |  | Height of the drawing area in pixels (legend and brush are extra), or `"fill"` to take whatever height the parent leaves after the legend and footer. The parent needs a definite height (fixed, flex or grid sized). A function derives the height from the measur… |
| `aspectRatio` | `number` |  | Width / height ratio of the drawing. Wins over a pixel `height`; ignored with `"fill"`. |
| `labels` * | `ChartLabels` |  |  |
| `loading` | `boolean` |  |  |
| `empty` | `boolean` |  | Nothing to plot: renders the empty state instead of `children`. |
| `skeleton` | `"line" \| "bars" \| "ring"` | `"bars"` | Skeleton silhouette while loading. |
| `legend` | `ReactNode` |  |  |
| `legendPosition` | `"top" \| "bottom"` | `"top"` |  |
| `legendAside` | `boolean` | `false` | Polar charts: when the container is wide (`@lg/chart`) the legend moves to a column beside the drawing instead of stacking above or below it. |
| `table` | `ReactNode` |  | Accessible data table (usually `ChartDataTable`), rendered after the drawing. |
| `footer` | `ReactNode` |  | Content under the drawing, e.g. the brush. Hidden while loading or empty. |
| `className` | `string` |  |  |
| `children` * | `(width: number, height: number) => ReactNode` |  | Receives the measured width and the drawing height (a fallback on the server). |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-chartframe--default)
- [Fills Parent](/storybook/?path=/story/charts-primitives-chartframe--fills-parent)
- [Aspect Ratio](/storybook/?path=/story/charts-primitives-chartframe--aspect-ratio)
- [With Legend And Table](/storybook/?path=/story/charts-primitives-chartframe--with-legend-and-table)
- [Loading](/storybook/?path=/story/charts-primitives-chartframe--loading)
- [Loading Ring](/storybook/?path=/story/charts-primitives-chartframe--loading-ring)
- [Empty](/storybook/?path=/story/charts-primitives-chartframe--empty)

## Source

`packages/ui/src/charts/core/chart-frame.tsx`

---

# ChartGrid

> Small multiples (trellis): the same chart repeated per category over shared scales, so panels compare at a glance.

Source: https://ui.jcsoftdev.com/docs/components/chart-grid

Small multiples (trellis): the same chart repeated per category over shared
scales, so panels compare at a glance. Columns follow the width of the
container, never the viewport.

## Import

```ts
import { ChartGrid } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/chart-grid`.

## Usage

```tsx
<ChartGrid
  title="Ventas por barbero"
  panels={linePanels}
  minPanelWidth={220}
  maxColumns={3}
  gap={16}
  sharedValueDomain
  sharedXDomain={false}
  includeZero={false}
  syncHover={false}
  bordered={false}
  emptyLabel="Sin barberos para mostrar"
>
  {none}
</ChartGrid>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the whole grid. |
| `panels` * | `readonly ChartGridPanel[]` |  |  |
| `children` * | `(panel: ChartGridPanel, context: ChartGridContext) => ReactNode` |  | Renders the chart of one panel. Fill the panel: pass `ctx.height` and the shared domain on. |
| `minPanelWidth` | `number` | `220` | Narrowest a panel may get before the grid drops a column (container-based). |
| `maxColumns` | `number` | `6` |  |
| `gap` | `number` | `16` |  |
| `panelHeight` | `number` |  | Height of every chart in pixels. Default: derived from the panel width (about 1.4:1), at least 180. |
| `aspectRatio` | `number` |  | Width / height ratio for the charts; wins over `panelHeight`. |
| `sharedValueDomain` | `boolean` | `true` | One value domain for every panel (default true). |
| `sharedXDomain` | `boolean` | `false` | One x domain for every panel. |
| `includeZero` | `boolean` | `false` | Bars: keep zero inside the shared domain. |
| `legend` | `readonly LegendItem[]` |  | One legend for all panels (their own legends should be off). |
| `syncHover` | `boolean` | `false` | Hovering a panel shows the real crosshair and tooltip in every other panel. The charts must receive `context.syncId` as their `syncId`; panels only react when the hovered category exists in them. |
| `bordered` | `boolean` | `false` | Draw a border around every panel. |
| `emptyLabel` | `string` | `"No data"` | Text when there are no panels. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Trellis](/storybook/?path=/story/charts-chartgrid--trellis)
- [Trellis Sync Hover](/storybook/?path=/story/charts-chartgrid--trellis-sync-hover)
- [Trellis Bars](/storybook/?path=/story/charts-chartgrid--trellis-bars)
- [Narrow](/storybook/?path=/story/charts-chartgrid--narrow)
- [Empty](/storybook/?path=/story/charts-chartgrid--empty)

## Source

`packages/ui/src/charts/chart-grid/chart-grid.tsx`

---

# ChartInkToolbar

> Buttons for the ruler and pen tools plus undo, redo and clear.

Source: https://ui.jcsoftdev.com/docs/components/chart-ink-toolbar

Buttons for the ruler and pen tools plus undo, redo and clear. Place it next to the chart.

## Import

```ts
import { ChartInkToolbar } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {
  args: { ink: placeholder },
  render: () => <InkDemo kind="line" tool="ruler" />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ink` * | `ChartInk` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-inkannotations--default)
- [On Bars](/storybook/?path=/story/charts-inkannotations--on-bars)
- [On Horizontal Bars](/storybook/?path=/story/charts-inkannotations--on-horizontal-bars)
- [Narrow](/storybook/?path=/story/charts-inkannotations--narrow)
- [Brutal Preset](/storybook/?path=/story/charts-inkannotations--brutal-preset)
- [Keyboard](/storybook/?path=/story/charts-inkannotations--keyboard)
- [Downsampled](/storybook/?path=/story/charts-inkannotations--downsampled)

## Source

`packages/ui/src/charts/core/cartesian/ink-layer.tsx`

---

# ChartLegend

> Series legend.

Source: https://ui.jcsoftdev.com/docs/components/chart-legend

Series legend. Each item is a toggle button (`aria-pressed`), so hiding a
series works with mouse, touch and keyboard; hovering or focusing one dims
the rest of the chart.

## Import

```ts
import { ChartLegend } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
<ChartLegend items={items} align="start" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` * | `readonly LegendItem[]` |  |  |
| `onToggle` | `((id: string) => void)` |  | Click toggles a series. Omit for a read-only legend. |
| `onHighlight` | `((id: string \| null) => void)` |  | Hover or focus of an item, `null` when leaving: used to dim the other series. |
| `align` | `"center" \| "start" \| "end"` | `"start"` |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Read Only](/storybook/?path=/story/charts-primitives-chartlegend--read-only)
- [Toggleable](/storybook/?path=/story/charts-primitives-chartlegend--toggleable)
- [Centered](/storybook/?path=/story/charts-primitives-chartlegend--centered)

## Source

`packages/ui/src/charts/core/legend.tsx`

---

# ChartPatternDefs

> `<pattern>` definitions to place inside an `<svg><defs>`.

Source: https://ui.jcsoftdev.com/docs/components/chart-pattern-defs

`<pattern>` definitions to place inside an `<svg><defs>`. Strokes and fills
use the item colour through `style`, so tokens resolve per theme.

## Import

```ts
import { ChartPatternDefs } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Gallery: Story = {};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` * | `readonly PatternDefItem[]` |  |  |

`*` marks a required prop.

## Storybook stories

- [Gallery](/storybook/?path=/story/charts-primitives-chartpatterndefs--gallery)
- [Custom Tile](/storybook/?path=/story/charts-primitives-chartpatterndefs--custom-tile)

## Source

`packages/ui/src/charts/core/pattern-defs.tsx`

---

# ChartSkeleton

> Loading placeholder with the rough shape of the chart that is coming.

Source: https://ui.jcsoftdev.com/docs/components/chart-skeleton

Loading placeholder with the rough shape of the chart that is coming.

## Import

```ts
import { ChartSkeleton } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
<ChartSkeleton height={220} label="Cargando ventas" shape="bars" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `height` * | `number` |  |  |
| `label` * | `string` |  |  |
| `shape` | `"line" \| "bars" \| "ring"` | `"bars"` | "bars" mimics columns, "line" a soft wave, "ring" a donut (for polar charts). |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Bars](/storybook/?path=/story/charts-primitives-chartskeleton--bars)
- [Line](/storybook/?path=/story/charts-primitives-chartskeleton--line)
- [Ring](/storybook/?path=/story/charts-primitives-chartskeleton--ring)
- [Empty](/storybook/?path=/story/charts-primitives-chartskeleton--empty)

## Source

`packages/ui/src/charts/core/chart-states.tsx`

---

# ChartSyncProvider

> Scopes chart sync to its children, so two groups that happen to use the same `syncId` never talk to each other.

Source: https://ui.jcsoftdev.com/docs/components/chart-sync-provider

Scopes chart sync to its children, so two groups that happen to use the same
`syncId` never talk to each other. Optional: charts with the same `syncId`
already sync through a shared default store.

## Import

```ts
import { ChartSyncProvider } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` * | `ReactNode` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-categorygroupaxis--default)
- [Narrow](/storybook/?path=/story/charts-primitives-categorygroupaxis--narrow)
- [Default](/storybook/?path=/story/charts-inkannotations--default)
- [On Bars](/storybook/?path=/story/charts-inkannotations--on-bars)
- [On Horizontal Bars](/storybook/?path=/story/charts-inkannotations--on-horizontal-bars)
- [Narrow](/storybook/?path=/story/charts-inkannotations--narrow)
- [Brutal Preset](/storybook/?path=/story/charts-inkannotations--brutal-preset)
- [Keyboard](/storybook/?path=/story/charts-inkannotations--keyboard)
- [Downsampled](/storybook/?path=/story/charts-inkannotations--downsampled)

## Source

`packages/ui/src/charts/core/cartesian/sync.tsx`

---

# ChartTooltip

> Floating card that lists every series at the hovered position.

Source: https://ui.jcsoftdev.com/docs/components/chart-tooltip

Floating card that lists every series at the hovered position. Purely
visual (`aria-hidden`): screen readers get the same numbers from the live
region and the hidden data table. Moves with a GPU transform, so following
the pointer never triggers layout. Its own width is measured so the card
always stays inside the container: it takes the side of the anchor with
room, and is clamped to the edges when neither side fits (narrow charts).

## Import

```ts
import { ChartTooltip } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
<ChartTooltip
  x={120}
  y={80}
  containerWidth={420}
  title="Sábado 4 oct"
  rows={rows}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `x` * | `number` |  | Anchor in pixels, relative to the positioned chart container. |
| `y` * | `number` |  |  |
| `containerWidth` * | `number` |  | Width of the container; the tooltip prefers the left of the anchor past 60% and never leaves it. |
| `title` | `ReactNode` |  |  |
| `rows` * | `readonly TooltipRow[]` |  |  |
| `body` | `string` |  | Wrapped sentence under the title, for notes that are not series values. |
| `side` | `"left" \| "right"` |  | Forces the side of the anchor the card opens on (when it fits); by default it follows the anchor. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-charttooltip--default)
- [Flips Near The Right Edge](/storybook/?path=/story/charts-primitives-charttooltip--flips-near-the-right-edge)
- [Without Title](/storybook/?path=/story/charts-primitives-charttooltip--without-title)

## Source

`packages/ui/src/charts/core/tooltip.tsx`

---

# ChordChart

> Chord diagram: groups share a circle, ribbons between them are the flows (who switches to whom, which service goes with which).

Source: https://ui.jcsoftdev.com/docs/components/chord-chart

Chord diagram: groups share a circle, ribbons between them are the flows
(who switches to whom, which service goes with which). Hover a group to
light its ribbons, a ribbon to isolate it; arrows walk the groups.

## Import

```ts
import { ChordChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/chord-chart`.

## Usage

```tsx
<ChordChart
  title="Clientes que cambian de barbero"
  description="Octubre frente a septiembre"
  groups={barberos}
  matrix={cambios}
  padAngle={3}
  startAngle={0}
  ringWidth={0.09}
  sortGroups="input"
  sortSubgroups="descending"
  showLabels
  valueFormat="integer"
  height={440}
  legend
  tooltip
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the drawing and caption of the data table. |
| `description` | `string` |  |  |
| `groups` * | `readonly ChordGroupInput[]` |  |  |
| `matrix` * | `readonly (readonly number[])[]` |  | `matrix[i][j]`: flow from group `i` to group `j`. A group's arc spans its row sum. |
| `padAngle` | `number` | `3` | Gap between groups, in degrees. |
| `startAngle` | `number` | `0` | Where the first group starts, degrees from twelve o'clock. |
| `ringWidth` | `number` | `0.09` | Thickness of the group ring as a fraction of the radius. |
| `sortGroups` | `"input" \| "ascending" \| "descending"` | `"input"` |  |
| `sortSubgroups` | `"input" \| "ascending" \| "descending"` | `"descending"` | Order of the ribbon ends inside a group. |
| `showLabels` | `boolean` | `true` | Group names around the ring (hidden automatically in narrow containers). |
| `valueFormat` | `ValueFormat` |  |  |
| `height` | `number \| "fill"` | `420` |  |
| `aspectRatio` | `number` |  | Width / height ratio of the drawing; ignored with `"fill"`. |
| `legend` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `exportable` | `boolean` | `false` | SVG and PNG export buttons. |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<ChordLabels>` |  |  |
| `onGroupClick` | `((group: ChordGroupInput, index: number) => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-chordchart--default)
- [Sorted](/storybook/?path=/story/charts-chordchart--sorted)
- [Services](/storybook/?path=/story/charts-chordchart--services)
- [Loading](/storybook/?path=/story/charts-chordchart--loading)
- [Empty](/storybook/?path=/story/charts-chordchart--empty)
- [Export](/storybook/?path=/story/charts-chordchart--export)
- [Dark](/storybook/?path=/story/charts-chordchart--dark)
- [Narrow](/storybook/?path=/story/charts-chordchart--narrow)
- [Fill Parent](/storybook/?path=/story/charts-chordchart--fill-parent)

## Source

`packages/ui/src/charts/chord-chart/chord-chart.tsx`

---

# ChoroplethDrilldown

> `ChoroplethMap` that opens a region into a finer map (world to country, country to departments) with a breadcrumb back up.

Source: https://ui.jcsoftdev.com/docs/components/choropleth-drilldown

`ChoroplethMap` that opens a region into a finer map (world to country, country to
departments) with a breadcrumb back up. The map of each level only needs its own geometry, so
only levels the user opens are ever drawn. The path is announced politely to screen readers.

## Import

```ts
import { ChoroplethDrilldown } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/choropleth-map`.

## Usage

```tsx
<ChoroplethDrilldown
  title="Clientes por departamento"
  map={peruMap}
  data={customers}
  valueName="Clientes"
  valueFormat="integer"
  scale="sequential"
  regionLabels="none"
  dataTable="hidden"
  legend
  tooltip
  zoomable
  wheelZoom="always"
  maxZoom={16}
  animate
  loading={false}
  labels={spanishLabels}
  height={520}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name; the current level is appended: "Clientes: Perú". |
| `root` * | `DrilldownLevel` |  |  |
| `resolve` * | `(region: ChoroplethRegionInfo, path: readonly DrilldownLevel[]) => DrilldownLevel \| null \| undefined` |  | Level to open when a region is clicked, given the path so far (root first), or nothing when that region has no detail (the click goes to `onRegionClick`). |
| `breadcrumbLabel` | `string` | `"Map level"` | Accessible name of the breadcrumb navigation. |
| `onNavigate` | `((path: readonly DrilldownLevel[]) => void)` |  | Called after every change of level with the new path (root first). |
| `onRegionClick` | `((region: ChoroplethRegionInfo, path: readonly DrilldownLevel[]) => void)` |  | Click on a region without detail. |
| `center` | `number` |  | Neutral value of a diverging scale. |
| `legend` | `boolean` |  |  |
| `animate` | `boolean` |  |  |
| `className` | `string` |  |  |
| `tooltip` | `boolean` |  |  |
| `height` | `number \| "fill"` |  | Height in px, "fill" or the default (half of the width, at least 220). |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width. |
| `valueFormat` | `ValueFormat` |  |  |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<MapLabels>` |  |  |
| `scale` | `"sequential" \| "diverging"` |  | "sequential" (empty to brand) or "diverging" (low hue, neutral at `center`, brand). |
| `domain` | `readonly [number, number]` |  | Fixed [min, max] of the color scale; the data extent by default. |
| `colors` | `ScaleColors` |  |  |
| `ranges` | `readonly ColorRange[]` |  | Stepped (threshold) coloring; replaces the continuous scale. |
| `valueName` | `string` |  | Name of the value in the tooltip and the data table, e.g. "Clientes". |
| `projection` | `"equirectangular" \| "mercator" \| "equalEarth" \| "fitted"` |  | Overrides the projection of the map. |
| `regionLabels` | `"name" \| "value" \| "none"` |  | Text drawn on each region where it fits: its name or its value. |
| `dataTable` | `"hidden" \| "toggle" \| "visible"` |  | The numbers as a real table, the accessible alternative to color: "hidden" (default, for screen readers only), "visible" (replaces the map) or "toggle" (a button switches between the map and the table). |
| `zoomable` | `boolean` |  | Zoom buttons, wheel, drag and pinch. |
| `wheelZoom` | `"always" \| "modifier"` |  | "modifier": the wheel only zooms with Ctrl or Cmd held, so page scrolling is never trapped. |
| `maxZoom` | `number` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-choroplethmap--default)
- [Region Labels](/storybook/?path=/story/charts-choroplethmap--region-labels)
- [Diverging](/storybook/?path=/story/charts-choroplethmap--diverging)
- [Thresholds](/storybook/?path=/story/charts-choroplethmap--thresholds)
- [Missing Data](/storybook/?path=/story/charts-choroplethmap--missing-data)
- [World](/storybook/?path=/story/charts-choroplethmap--world)
- [World Mercator](/storybook/?path=/story/charts-choroplethmap--world-mercator)
- [Drilldown](/storybook/?path=/story/charts-choroplethmap--drilldown)
- [Data Table](/storybook/?path=/story/charts-choroplethmap--data-table)
- [Data Table Toggle](/storybook/?path=/story/charts-choroplethmap--data-table-toggle)
- [Data Table Narrow](/storybook/?path=/story/charts-choroplethmap--data-table-narrow)
- [Loading](/storybook/?path=/story/charts-choroplethmap--loading)
- [Empty](/storybook/?path=/story/charts-choroplethmap--empty)
- [Narrow](/storybook/?path=/story/charts-choroplethmap--narrow)
- [Fill Parent](/storybook/?path=/story/charts-choroplethmap--fill-parent)

## Source

`packages/ui/src/charts/choropleth-map/choropleth-drilldown.tsx`

---

# ChoroplethMap

> Regions colored by value: customers by department, sales by country.

Source: https://ui.jcsoftdev.com/docs/components/choropleth-map

Regions colored by value: customers by department, sales by country.
Sequential, diverging or threshold scales come from tokens, so the map
follows the theme and accent. Hover or arrow keys highlight a region and
show its value; click or Enter calls `onRegionClick`; zoom with the
buttons, wheel, pinch or `+` / `-`, drag to pan, `0` to fit.

## Import

```ts
import { ChoroplethMap } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/choropleth-map`.

## Usage

```tsx
<ChoroplethMap
  title="Clientes por departamento"
  map={peruMap}
  data={customers}
  valueName="Clientes"
  valueFormat="integer"
  scale="sequential"
  regionLabels="none"
  dataTable="hidden"
  legend
  tooltip
  zoomable
  wheelZoom="always"
  maxZoom={16}
  animate
  loading={false}
  labels={spanishLabels}
  height={520}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the drawing and caption of the data table. |
| `map` * | `GeoMap` |  | Geometry to draw, e.g. `peruMap` from `@jcsoftdev/ui/charts/maps/data/peru`. |
| `data` * | `readonly ChoroplethDatum[]` |  |  |
| `scale` | `"sequential" \| "diverging"` | `"sequential"` | "sequential" (empty to brand) or "diverging" (low hue, neutral at `center`, brand). |
| `domain` | `readonly [number, number]` |  | Fixed [min, max] of the color scale; the data extent by default. |
| `center` | `number` | `0` | Neutral value of a diverging scale. |
| `colors` | `ScaleColors` |  |  |
| `ranges` | `readonly ColorRange[]` |  | Stepped (threshold) coloring; replaces the continuous scale. |
| `valueFormat` | `ValueFormat` |  |  |
| `valueName` | `string` |  | Name of the value in the tooltip and the data table, e.g. "Clientes". |
| `projection` | `"equirectangular" \| "mercator" \| "equalEarth" \| "fitted"` |  | Overrides the projection of the map. |
| `regionLabels` | `"name" \| "value" \| "none"` | `"none"` | Text drawn on each region where it fits: its name or its value. |
| `height` | `number \| "fill"` |  | Height in px, "fill" or the default (half of the width, at least 220). |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width. |
| `legend` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `dataTable` | `"hidden" \| "toggle" \| "visible"` | `"hidden"` | The numbers as a real table, the accessible alternative to color: "hidden" (default, for screen readers only), "visible" (replaces the map) or "toggle" (a button switches between the map and the table). |
| `zoomable` | `boolean` | `true` | Zoom buttons, wheel, drag and pinch. |
| `wheelZoom` | `"always" \| "modifier"` | `"modifier"` | "modifier": the wheel only zooms with Ctrl or Cmd held, so page scrolling is never trapped. |
| `maxZoom` | `number` | `16` |  |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<MapLabels>` |  |  |
| `onRegionClick` | `((region: ChoroplethRegionInfo) => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-choroplethmap--default)
- [Region Labels](/storybook/?path=/story/charts-choroplethmap--region-labels)
- [Diverging](/storybook/?path=/story/charts-choroplethmap--diverging)
- [Thresholds](/storybook/?path=/story/charts-choroplethmap--thresholds)
- [Missing Data](/storybook/?path=/story/charts-choroplethmap--missing-data)
- [World](/storybook/?path=/story/charts-choroplethmap--world)
- [World Mercator](/storybook/?path=/story/charts-choroplethmap--world-mercator)
- [Drilldown](/storybook/?path=/story/charts-choroplethmap--drilldown)
- [Data Table](/storybook/?path=/story/charts-choroplethmap--data-table)
- [Data Table Toggle](/storybook/?path=/story/charts-choroplethmap--data-table-toggle)
- [Data Table Narrow](/storybook/?path=/story/charts-choroplethmap--data-table-narrow)
- [Loading](/storybook/?path=/story/charts-choroplethmap--loading)
- [Empty](/storybook/?path=/story/charts-choroplethmap--empty)
- [Narrow](/storybook/?path=/story/charts-choroplethmap--narrow)
- [Fill Parent](/storybook/?path=/story/charts-choroplethmap--fill-parent)

## Source

`packages/ui/src/charts/choropleth-map/choropleth-map.tsx`

---

# ComboChart

> Columns and lines on one plot, e.g.

Source: https://ui.jcsoftdev.com/docs/components/combo-chart

Columns and lines on one plot, e.g. revenue as columns with appointments
as a line on a second axis. `stack` applies to the columns only.

## Import

```ts
import { ComboChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/combo-chart`.

## Usage

```tsx
<ComboChart
  title="Ventas y citas de la semana"
  categories={days}
  series={[
      { id: "ventas", name: "Ventas", type: "column", data: revenue, format: "currency" },
      {
        id: "citas",
        name: "Citas",
        type: "line",
        axis: "right",
        data: appointments,
        format: "integer",
      },
    ]}
  yAxis={{ format: "currency", title: "S/" }}
  rightAxis={{ title: "Citas" }}
  height={320}
  curve="smooth"
  markers
  dataLabels={false}
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `series` * | `readonly ComboSeries[]` |  |  |
| `legend` | `boolean \| "top" \| "bottom"` |  | Legend placement, or false to hide it. Defaults to "top" with two or more series. |
| `title` * | `string` |  | Accessible name of the chart (`aria-label` of the drawing). |
| `animate` | `boolean` |  | Entry animation (default true; always off with prefers-reduced-motion). |
| `className` | `string` |  |  |
| `grid` | `boolean` |  | Background gridlines (default true). |
| `tooltip` | `boolean` |  | Shared tooltip (default true). |
| `gradient` | `boolean` |  | Gradient fill under areas (default true). |
| `barRadius` | `number` |  | Corner radius at the value end of bars, 6 by default. |
| `rightAxis` | `ValueAxisOptions` |  | Secondary axis for series with `axis: "right"`. |
| `categories` * | `readonly XValue[]` |  | One entry per data point: strings, numbers or dates. |
| `description` | `string` |  | Extra sentence for the hidden data table caption. |
| `height` | `number \| "fill"` |  | Height of the plot in pixels, 300 by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the plot from the container width (wins over a pixel `height`). |
| `stack` | `"normal" \| "none" \| "percent"` |  | Stacks every area and column series. |
| `curve` | `"linear" \| "smooth" \| "step" \| "step-before" \| "step-after"` | `"smooth"` |  |
| `markers` | `boolean` |  | Dots on every line point. Hovered points are always marked. |
| `dataLabels` | `boolean` |  | Values printed on the marks. |
| `lineGradient` | `boolean` |  | Strokes lines with a gradient from each series color to the next palette color. |
| `transition` | `boolean` |  | Eases lines and areas between data updates (live data); off by default. |
| `maxPoints` | `number \| false` |  | Series with more points than this are reduced with LTTB, 2000 by default; `false` draws every point. |
| `syncId` | `string` |  | Charts with the same id share hover (crosshair and tooltip) and the zoom window. |
| `onPointClick` | `((point: CartesianPointEvent) => void)` |  | Called with the category (and nearest series) under the pointer when the plot is clicked or Enter is pressed. |
| `valueFormat` | `ValueFormat` |  | Format of values in tooltips, labels and the data table. |
| `xFormat` | `((value: XValue) => string)` |  | Label of a category on the axis and in the tooltip (dates get Spanish defaults). |
| `yAxis` | `ValueAxisOptions` |  |  |
| `axes` | `readonly CartesianAxisSpec[]` |  | Any number of value axes. `yAxis` and `rightAxis` are shorthand for the ids "left" and "right"; more entries stack outward on their `side` (right by default) and series pick one with `axis`. |
| `annotations` | `readonly ChartAnnotation[]` |  |  |
| `categoryLabelRotation` | `number` |  | Tilts the category labels (degrees, e.g. -45) so long names fit; vertical charts only. |
| `categoryGroups` | `readonly CategoryGroup[]` |  | Second tier of labels under the category axis (vertical charts); counts must add up to the categories. |
| `onCategoryClick` | `((index: number) => void)` |  | Click (or Enter on the focused plot) on a category; receives its index in `categories`. |
| `overlay` | `CartesianOverlay` |  | Extra layers over the plot, e.g. the ruler and ink tools of `useChartInk`. Vertical charts only. |
| `rangeSelect` | `{ value: readonly [number, number] \| null; onChange: (range: readonly [number, number] \| null) => void; }` |  |  |
| `loading` | `boolean` |  |  |
| `initialHidden` | `readonly string[]` |  | Series hidden at first; the legend can show them. |
| `labels` | `Partial<ChartLabels>` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-combochart--default)
- [Columns And Area](/storybook/?path=/story/charts-combochart--columns-and-area)
- [Stacked Columns With Total Line](/storybook/?path=/story/charts-combochart--stacked-columns-with-total-line)
- [Multi Axis](/storybook/?path=/story/charts-combochart--multi-axis)
- [Multi Axis Narrow](/storybook/?path=/story/charts-combochart--multi-axis-narrow)
- [Loading](/storybook/?path=/story/charts-combochart--loading)

## Source

`packages/ui/src/charts/combo-chart/combo-chart.tsx`

---

# CrossfilterBarChart

> Bars per category of one dimension.

Source: https://ui.jcsoftdev.com/docs/components/crossfilter-bar-chart

Bars per category of one dimension. Click a bar to filter by it (click again to undo, several
bars add up). The light bars are the totals, the accent ones what the OTHER charts leave in;
categories outside this chart's own filter are dimmed.

## Import

```ts
import { CrossfilterBarChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/crossfilter`.

## Usage

```tsx
export const VentasCruzadas: Story = {
  args: storyArgs,
  render: () => <SalesCrossfilter columns="wide" />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `dimension` * | `string` |  | Dimension id (a key of the provider's `dimensions`). |
| `keys` | `readonly DimensionValue[]` |  | Categories in display order; otherwise the order of first appearance. |
| `keyLabel` | `((key: DimensionValue) => string)` | `String` | Text of a category on the axis. |
| `measure` | `((record: never) => number)` |  | Add this instead of counting records, e.g. `(sale) => sale.total` for revenue. |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` |  |
| `labels` | `Partial<CrossfilterLabels>` |  |  |
| `className` | `string` |  |  |
| `legend` | `boolean \| "top" \| "bottom"` |  | Legend placement, or false to hide it. Defaults to "top" with two or more series. |
| `animate` | `boolean` |  | Entry animation (default true; always off with prefers-reduced-motion). |
| `height` | `number \| "fill"` |  | Height of the plot in pixels, 300 by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the plot from the container width (wins over a pixel `height`). |
| `valueFormat` | `ValueFormat` |  | Format of values in tooltips, labels and the data table. |
| `yAxis` | `ValueAxisOptions` |  |  |

`*` marks a required prop.

## Storybook stories

- [Ventas Cruzadas](/storybook/?path=/story/charts-crossfilter--ventas-cruzadas)
- [Filtro Inicial](/storybook/?path=/story/charts-crossfilter--filtro-inicial)
- [Narrow](/storybook/?path=/story/charts-crossfilter--narrow)
- [Brutal Preset](/storybook/?path=/story/charts-crossfilter--brutal-preset)
- [Pincel Rectangular](/storybook/?path=/story/charts-crossfilter--pincel-rectangular)
- [Pincel Inicial](/storybook/?path=/story/charts-crossfilter--pincel-inicial)
- [Pincel Narrow](/storybook/?path=/story/charts-crossfilter--pincel-narrow)
- [Pincel Tactil](/storybook/?path=/story/charts-crossfilter--pincel-tactil)

## Source

`packages/ui/src/charts/crossfilter/crossfilter.tsx`

---

# CrossfilterHistogram

> Distribution of a numeric dimension.

Source: https://ui.jcsoftdev.com/docs/components/crossfilter-histogram

Distribution of a numeric dimension. Drag across the bars to filter by that interval, or click a
bin; the band stays drawn until you click it again or press Clear.

## Import

```ts
import { CrossfilterHistogram } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/crossfilter`.

## Usage

```tsx
export const VentasCruzadas: Story = {
  args: storyArgs,
  render: () => <SalesCrossfilter columns="wide" />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `dimension` * | `string` |  | Numeric dimension to bin. |
| `edges` | `readonly number[]` |  | Bin edges; or give `domain` and `bins` to split evenly. |
| `domain` | `readonly [number, number]` | `[0, 100]` |  |
| `bins` | `number` | `10` |  |
| `edgeFormat` | `ValueFormat` |  | Format of the bin edges in the axis and tooltip. |
| `labels` | `Partial<CrossfilterLabels>` |  |  |
| `className` | `string` |  |  |
| `legend` | `boolean \| "top" \| "bottom"` |  | Legend placement, or false to hide it. Defaults to "top" with two or more series. |
| `animate` | `boolean` |  | Entry animation (default true; always off with prefers-reduced-motion). |
| `height` | `number \| "fill"` |  | Height of the plot in pixels, 300 by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the plot from the container width (wins over a pixel `height`). |
| `valueFormat` | `ValueFormat` |  | Format of values in tooltips, labels and the data table. |
| `yAxis` | `ValueAxisOptions` |  |  |

`*` marks a required prop.

## Storybook stories

- [Ventas Cruzadas](/storybook/?path=/story/charts-crossfilter--ventas-cruzadas)
- [Filtro Inicial](/storybook/?path=/story/charts-crossfilter--filtro-inicial)
- [Narrow](/storybook/?path=/story/charts-crossfilter--narrow)
- [Brutal Preset](/storybook/?path=/story/charts-crossfilter--brutal-preset)
- [Pincel Rectangular](/storybook/?path=/story/charts-crossfilter--pincel-rectangular)
- [Pincel Inicial](/storybook/?path=/story/charts-crossfilter--pincel-inicial)
- [Pincel Narrow](/storybook/?path=/story/charts-crossfilter--pincel-narrow)
- [Pincel Tactil](/storybook/?path=/story/charts-crossfilter--pincel-tactil)

## Source

`packages/ui/src/charts/crossfilter/crossfilter.tsx`

---

# CrossfilterProvider

> Shares one dataset and its filters with every chart inside: each chart filters by brushing or clicking, and every other chart (and any table fed from `useCrossfilter().filtered`) …

Source: https://ui.jcsoftdev.com/docs/components/crossfilter-provider

Shares one dataset and its filters with every chart inside: each chart filters by brushing or
clicking, and every other chart (and any table fed from `useCrossfilter().filtered`) follows.

## Import

```ts
import { CrossfilterProvider } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/crossfilter`.

## Usage

```tsx
export const VentasCruzadas: Story = {
  args: storyArgs,
  render: () => <SalesCrossfilter columns="wide" />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` * | `readonly T[]` |  |  |
| `dimensions` * | `Readonly<Record<string, Accessor<T>>>` |  | How to read each dimension from a record. Keep the object stable (module level or memoized). |
| `initialFilters` | `Readonly<Record<string, CrossfilterFilter>>` | `NO_FILTERS` | Filters when the page loads. |
| `children` * | `ReactNode` |  |  |

`*` marks a required prop.

## Storybook stories

- [Ventas Cruzadas](/storybook/?path=/story/charts-crossfilter--ventas-cruzadas)
- [Filtro Inicial](/storybook/?path=/story/charts-crossfilter--filtro-inicial)
- [Narrow](/storybook/?path=/story/charts-crossfilter--narrow)
- [Brutal Preset](/storybook/?path=/story/charts-crossfilter--brutal-preset)
- [Pincel Rectangular](/storybook/?path=/story/charts-crossfilter--pincel-rectangular)
- [Pincel Inicial](/storybook/?path=/story/charts-crossfilter--pincel-inicial)
- [Pincel Narrow](/storybook/?path=/story/charts-crossfilter--pincel-narrow)
- [Pincel Tactil](/storybook/?path=/story/charts-crossfilter--pincel-tactil)

## Source

`packages/ui/src/charts/crossfilter/crossfilter.tsx`

---

# CrossfilterScatter

> One dot per record: accent for the records every filter leaves in, faint for the rest, so the dots you filtered out stay visible as context.

Source: https://ui.jcsoftdev.com/docs/components/crossfilter-scatter

One dot per record: accent for the records every filter leaves in, faint for the rest, so the
dots you filtered out stay visible as context. Drag a rectangle to filter both dimensions at
once (a click clears it). From the keyboard, focus the brush after the plot: arrows move the
rectangle, Shift and arrows resize it, Enter applies it and Escape clears it. On touch the page
keeps scrolling: rest a finger on the plot for about 350 ms (`touchDelay`) and then drag to draw.

## Import

```ts
import { CrossfilterScatter } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/crossfilter`.

## Usage

```tsx
export const VentasCruzadas: Story = {
  args: storyArgs,
  render: () => <SalesCrossfilter columns="wide" />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `x` * | `string` |  | Numeric dimensions on each axis. |
| `y` * | `string` |  |  |
| `xFormat` | `ValueFormat` |  |  |
| `yFormat` | `ValueFormat` |  |  |
| `pointLabel` | `((record: never) => string)` |  | Name of the point in tooltips, e.g. the client. |
| `xLabel` | `string` |  | Names of the axes in the spoken brush range; the dimension ids by default. |
| `yLabel` | `string` |  |  |
| `brush` | `boolean` | `true` | Rectangular brush on both dimensions (drag, or focus the plot and use the keys). On by default. |
| `touchDelay` | `number` |  | Touch: milliseconds a finger must rest before a drag draws the rectangle (350 by default), so a swipe over the plot still scrolls the page. `0` brushes at once and blocks scrolling on the plot. |
| `jitter` | `number` |  | Pixels of deterministic spread for dimensions with few distinct values. |
| `height` | `number \| "fill"` |  |  |
| `aspectRatio` | `number` |  |  |
| `labels` | `Partial<CrossfilterLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Ventas Cruzadas](/storybook/?path=/story/charts-crossfilter--ventas-cruzadas)
- [Filtro Inicial](/storybook/?path=/story/charts-crossfilter--filtro-inicial)
- [Narrow](/storybook/?path=/story/charts-crossfilter--narrow)
- [Brutal Preset](/storybook/?path=/story/charts-crossfilter--brutal-preset)
- [Pincel Rectangular](/storybook/?path=/story/charts-crossfilter--pincel-rectangular)
- [Pincel Inicial](/storybook/?path=/story/charts-crossfilter--pincel-inicial)
- [Pincel Narrow](/storybook/?path=/story/charts-crossfilter--pincel-narrow)
- [Pincel Tactil](/storybook/?path=/story/charts-crossfilter--pincel-tactil)

## Source

`packages/ui/src/charts/crossfilter/crossfilter.tsx`

---

# CrossfilterSummary

> "128 of 480" plus a button that clears every filter.

Source: https://ui.jcsoftdev.com/docs/components/crossfilter-summary

"128 of 480" plus a button that clears every filter.

## Import

```ts
import { CrossfilterSummary } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/crossfilter`.

## Usage

```tsx
export const VentasCruzadas: Story = {
  args: storyArgs,
  render: () => <SalesCrossfilter columns="wide" />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `noun` * | `string` |  | What the records are, e.g. "ventas". |
| `labels` | `Partial<CrossfilterLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Ventas Cruzadas](/storybook/?path=/story/charts-crossfilter--ventas-cruzadas)
- [Filtro Inicial](/storybook/?path=/story/charts-crossfilter--filtro-inicial)
- [Narrow](/storybook/?path=/story/charts-crossfilter--narrow)
- [Brutal Preset](/storybook/?path=/story/charts-crossfilter--brutal-preset)
- [Pincel Rectangular](/storybook/?path=/story/charts-crossfilter--pincel-rectangular)
- [Pincel Inicial](/storybook/?path=/story/charts-crossfilter--pincel-inicial)
- [Pincel Narrow](/storybook/?path=/story/charts-crossfilter--pincel-narrow)
- [Pincel Tactil](/storybook/?path=/story/charts-crossfilter--pincel-tactil)

## Source

`packages/ui/src/charts/crossfilter/crossfilter.tsx`

---

# DonutChart

> Donut, pie and semi-donut.

Source: https://ui.jcsoftdev.com/docs/components/donut-chart

Donut, pie and semi-donut. Rounded slice corners and a pixel gap between
slices, a centre total that follows the hovered slice, slices that step out
on hover or keyboard focus, optional outside labels on leader lines (with
collision avoidance) and a legend that toggles slices.

## Import

```ts
import { DonutChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/donut-chart`.

## Usage

```tsx
<DonutChart
  title="Ingresos por servicio en octubre"
  data={services}
  valueFormat="currency"
  variant="donut"
  semi={false}
  innerRadius={0.62}
  cornerRadius={6}
  gap={3}
  explode={8}
  startAngle={0}
  outsideLabels={false}
  height={320}
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the drawing. |
| `description` | `string` |  |  |
| `data` * | `readonly DonutDatum[]` |  |  |
| `variant` | `"donut" \| "pie"` | `"donut"` | `pie` fills the centre (no centre label). |
| `semi` | `boolean` | `false` | Half circle opening upwards, like a gauge. |
| `innerRadius` | `number` | `0.62` | Hole size as a fraction of the outer radius (donut only). |
| `cornerRadius` | `number` | `6` | Radius of the rounded slice corners, in pixels. 0 = sharp. |
| `gap` | `number` | `3` | Visible gap between slices, in pixels. |
| `explode` | `number` | `8` | Pixels a hovered or focused slice moves outwards. |
| `startAngle` | `number` | `0` | Where the first slice starts, in degrees from 12 o'clock (full circle only). |
| `monochrome` | `string \| boolean` | `false` | One hue in shades, darkest on the largest slice. `true` uses the accent; a string sets the base color. |
| `fill` | `"pattern" \| "solid" \| "gradient"` | `"solid"` | `gradient` fades each slice towards the hole; `pattern` adds a texture per slice, so color is not the only cue. |
| `drilldown` | `boolean` | `true` | Slices with `children` open on click (or Enter) with a breadcrumb to go back. |
| `rootLabel` | `string` |  | First breadcrumb item; defaults to the chart title. |
| `breadcrumbLabel` | `string` | `"Drill-down path"` | Accessible name of the breadcrumb. |
| `height` | `number \| "fill"` | `300` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `valueFormat` | `ValueFormat` |  |  |
| `centerLabel` | `string` |  | Caption under the centre value when nothing is hovered. Defaults to the "Total" label. |
| `centerValue` | `string` |  | Replaces the total shown in the centre while nothing is hovered. |
| `outsideLabels` | `boolean \| "name" \| "percent" \| "both"` | `false` | Names / percentages on leader lines around the ring. `true` shows both. |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` | `false` |  |
| `animate` | `boolean` | `true` |  |
| `initialHidden` | `readonly string[]` |  | Ids hidden at first. |
| `onSliceClick` | `((datum: DonutDatum) => void)` |  |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-donutchart--default)
- [Outside Labels](/storybook/?path=/story/charts-donutchart--outside-labels)
- [Outside Percent Only](/storybook/?path=/story/charts-donutchart--outside-percent-only)
- [Semi Donut](/storybook/?path=/story/charts-donutchart--semi-donut)
- [Semi With Outside Labels](/storybook/?path=/story/charts-donutchart--semi-with-outside-labels)
- [Sharp Thin Ring](/storybook/?path=/story/charts-donutchart--sharp-thin-ring)
- [Custom Center](/storybook/?path=/story/charts-donutchart--custom-center)
- [Monochrome](/storybook/?path=/story/charts-donutchart--monochrome)
- [Gradient](/storybook/?path=/story/charts-donutchart--gradient)
- [Textured](/storybook/?path=/story/charts-donutchart--textured)
- [Update](/storybook/?path=/story/charts-donutchart--update)
- [Drilldown](/storybook/?path=/story/charts-donutchart--drilldown)
- [Hidden Slices](/storybook/?path=/story/charts-donutchart--hidden-slices)
- [Loading](/storybook/?path=/story/charts-donutchart--loading)
- [Empty](/storybook/?path=/story/charts-donutchart--empty)
- [Narrow](/storybook/?path=/story/charts-donutchart--narrow)
- [Fill Parent](/storybook/?path=/story/charts-donutchart--fill-parent)
- [Small Ring Long Value](/storybook/?path=/story/charts-donutchart--small-ring-long-value)

## Source

`packages/ui/src/charts/donut-chart/donut-chart.tsx`

---

# DrilldownBarChart

> Bars of one level of a hierarchy.

Source: https://ui.jcsoftdev.com/docs/components/drilldown-bar-chart

Bars of one level of a hierarchy. Click (or Enter on) a bar that has
children to drill into it; the breadcrumb above brings you back out.
Bars that can be opened carry a `›` after their label.

## Import

```ts
import { DrilldownBarChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/bar-chart`.

## Usage

```tsx
<DrilldownBarChart
  title="Citas por barbero esta semana"
  categories={barbers}
  series={[{ id: "citas", name: "Citas", data: appointmentsThisWeek }]}
  valueFormat="integer"
  orientation="vertical"
  stack="none"
  barRadius={6}
  height={300}
  dataLabels={false}
  grid
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` * | `HierarchyDatum` |  | Tree to explore: the chart shows the children of the focused node. |
| `seriesName` | `string` | `"Value"` | Name of the single series (tooltip and data table). |
| `breadcrumbLabel` | `string` | `"Drill-down path"` | Accessible name of the breadcrumb navigation. |
| `sort` | `boolean` | `true` | Largest first (default) or in data order. |
| `legend` | `boolean \| "top" \| "bottom"` |  | Legend placement, or false to hide it. Defaults to "top" with two or more series. |
| `title` * | `string` |  | Accessible name of the chart (`aria-label` of the drawing). |
| `animate` | `boolean` |  | Entry animation (default true; always off with prefers-reduced-motion). |
| `className` | `string` |  |  |
| `grid` | `boolean` |  | Background gridlines (default true). |
| `tooltip` | `boolean` |  | Shared tooltip (default true). |
| `orientation` | `"horizontal" \| "vertical"` |  | "horizontal" lays categories top to bottom (bar charts). |
| `barRadius` | `number` |  | Corner radius at the value end of bars, 6 by default. |
| `description` | `string` |  | Extra sentence for the hidden data table caption. |
| `height` | `number \| "fill"` |  | Height of the plot in pixels, 300 by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the plot from the container width (wins over a pixel `height`). |
| `stack` | `"normal" \| "none" \| "percent"` |  | Stacks every area and column series. |
| `dataLabels` | `boolean` |  | Values printed on the marks. |
| `lineGradient` | `boolean` |  | Strokes lines with a gradient from each series color to the next palette color. |
| `transition` | `boolean` |  | Eases lines and areas between data updates (live data); off by default. |
| `maxPoints` | `number \| false` |  | Series with more points than this are reduced with LTTB, 2000 by default; `false` draws every point. |
| `syncId` | `string` |  | Charts with the same id share hover (crosshair and tooltip) and the zoom window. |
| `onPointClick` | `((point: CartesianPointEvent) => void)` |  | Called with the category (and nearest series) under the pointer when the plot is clicked or Enter is pressed. |
| `valueFormat` | `ValueFormat` |  | Format of values in tooltips, labels and the data table. |
| `xFormat` | `((value: XValue) => string)` |  | Label of a category on the axis and in the tooltip (dates get Spanish defaults). |
| `yAxis` | `ValueAxisOptions` |  |  |
| `axes` | `readonly CartesianAxisSpec[]` |  | Any number of value axes. `yAxis` and `rightAxis` are shorthand for the ids "left" and "right"; more entries stack outward on their `side` (right by default) and series pick one with `axis`. |
| `annotations` | `readonly ChartAnnotation[]` |  |  |
| `categoryLabelRotation` | `number` |  | Tilts the category labels (degrees, e.g. -45) so long names fit; vertical charts only. |
| `categoryGroups` | `readonly CategoryGroup[]` |  | Second tier of labels under the category axis (vertical charts); counts must add up to the categories. |
| `overlay` | `CartesianOverlay` |  | Extra layers over the plot, e.g. the ruler and ink tools of `useChartInk`. Vertical charts only. |
| `rangeSelect` | `{ value: readonly [number, number] \| null; onChange: (range: readonly [number, number] \| null) => void; }` |  |  |
| `loading` | `boolean` |  |  |
| `initialHidden` | `readonly string[]` |  | Series hidden at first; the legend can show them. |
| `labels` | `Partial<ChartLabels>` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-barchart--default)
- [Grouped](/storybook/?path=/story/charts-barchart--grouped)
- [Stacked](/storybook/?path=/story/charts-barchart--stacked)
- [Stacked 100%](/storybook/?path=/story/charts-barchart--stacked-percent)
- [Horizontal (top services)](/storybook/?path=/story/charts-barchart--horizontal)
- [Horizontal Stacked](/storybook/?path=/story/charts-barchart--horizontal-stacked)
- [Negative Values](/storybook/?path=/story/charts-barchart--negative-values)
- [Annotation (weekly goal)](/storybook/?path=/story/charts-barchart--with-goal)
- [Data Labels](/storybook/?path=/story/charts-barchart--data-labels)
- [Custom Data Labels](/storybook/?path=/story/charts-barchart--custom-data-labels)
- [Distributed (a color per bar)](/storybook/?path=/story/charts-barchart--distributed)
- [Rotated Labels](/storybook/?path=/story/charts-barchart--rotated-labels)
- [Range column (shifts)](/storybook/?path=/story/charts-barchart--range-column)
- [Range bar (service duration)](/storybook/?path=/story/charts-barchart--range-bar)
- [Grouped stacked (income vs costs)](/storybook/?path=/story/charts-barchart--grouped-stacked)
- [Group labels (quarters)](/storybook/?path=/story/charts-barchart--group-labels)
- [Reversed value axis](/storybook/?path=/story/charts-barchart--reversed)
- [Patterns (color-blind friendly)](/storybook/?path=/story/charts-barchart--patterned)
- [Patterned Stacked](/storybook/?path=/story/charts-barchart--patterned-stacked)
- [Drilldown](/storybook/?path=/story/charts-barchart--drilldown)
- [Race (animated re-sort)](/storybook/?path=/story/charts-barchart--race)
- [Loading](/storybook/?path=/story/charts-barchart--loading)
- [Empty](/storybook/?path=/story/charts-barchart--empty)
- [Fill Parent](/storybook/?path=/story/charts-barchart--fill-parent)
- [Narrow](/storybook/?path=/story/charts-barchart--narrow)

## Source

`packages/ui/src/charts/bar-chart/drilldown-bar-chart.tsx`

---

# DrilldownHeatmap

> Heatmap you can dive into: click (or press Enter on) a cell to open the matrix behind it.

Source: https://ui.jcsoftdev.com/docs/components/drilldown-heatmap

Heatmap you can dive into: click (or press Enter on) a cell to open the
matrix behind it. The breadcrumb above climbs back to any earlier level.

## Import

```ts
import { DrilldownHeatmap } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/heatmap-chart`.

## Usage

```tsx
<DrilldownHeatmap
  title="Ocupación de sillas por hora y día"
  rows={days}
  columns={hours}
  values={occupancy}
  scale="sequential"
  valueFormat={percent}
  domain={[0, 100]}
  cellLabels={false}
  gap={3}
  radius={4}
  legend
  tooltip
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name when a level has no `title`. |
| `root` * | `HeatmapLevel` |  |  |
| `breadcrumbLabel` | `string` | `"Path"` | Accessible name of the breadcrumb landmark. |
| `onLevelChange` | `((path: readonly HeatmapLevel[]) => void)` |  |  |
| `center` | `number` |  | Neutral value of a diverging scale. |
| `legend` | `boolean` |  | Color key (gradient bar or range swatches). |
| `animate` | `boolean` |  |  |
| `className` | `string` |  |  |
| `tooltip` | `boolean` |  |  |
| `height` | `number \| "fill"` |  | Height of the drawing in px or "fill"; 34 px per row plus the column header by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width. |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<HeatmapLabels>` |  |  |
| `radius` | `number` |  |  |
| `renderer` | `"canvas" \| "svg"` |  | "canvas" paints the cells on a canvas, for matrices with tens of thousands of cells. Labels, tooltip, focus ring and keyboard stay SVG/HTML. |
| `scale` | `"sequential" \| "diverging"` |  | "sequential" (empty to brand) or "diverging" (low hue, neutral at `center`, brand). |
| `colors` | `ScaleColors` |  | Override the scale colors (CSS colors or tokens). |
| `ranges` | `readonly ColorRange[]` |  | Stepped coloring by ranges or thresholds; replaces the continuous scale. |
| `shape` | `"rect" \| "hex"` |  | "hex" draws a honeycomb: pointy-top hexagons with odd rows shifted half a cell. |
| `cellLabels` | `boolean` |  | Values inside the cells (only where they fit). |
| `gap` | `number` |  | Gap between cells in pixels. |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-heatmapchart--default)
- [Cell Labels](/storybook/?path=/story/charts-heatmapchart--cell-labels)
- [Diverging](/storybook/?path=/story/charts-heatmapchart--diverging)
- [Ranges](/storybook/?path=/story/charts-heatmapchart--ranges)
- [Missing Data](/storybook/?path=/story/charts-heatmapchart--missing-data)
- [Calendar](/storybook/?path=/story/charts-heatmapchart--calendar)
- [Calendar Ranges](/storybook/?path=/story/charts-heatmapchart--calendar-ranges)
- [Rounded](/storybook/?path=/story/charts-heatmapchart--rounded)
- [Honeycomb](/storybook/?path=/story/charts-heatmapchart--honeycomb)
- [Continuous Datetime](/storybook/?path=/story/charts-heatmapchart--continuous-datetime)
- [Canvas Dense](/storybook/?path=/story/charts-heatmapchart--canvas-dense)
- [Drilldown](/storybook/?path=/story/charts-heatmapchart--drilldown)
- [Narrow Drilldown](/storybook/?path=/story/charts-heatmapchart--narrow-drilldown)
- [Loading](/storybook/?path=/story/charts-heatmapchart--loading)
- [Empty](/storybook/?path=/story/charts-heatmapchart--empty)
- [Narrow](/storybook/?path=/story/charts-heatmapchart--narrow)
- [Narrow Calendar](/storybook/?path=/story/charts-heatmapchart--narrow-calendar)

## Source

`packages/ui/src/charts/heatmap-chart/drilldown-heatmap.tsx`

---

# DumbbellChart

> Two or more values per category joined by a bar: the length of the line is the spread, the change is last minus first.

Source: https://ui.jcsoftdev.com/docs/components/dumbbell-chart

Two or more values per category joined by a bar: the length of the line is
the spread, the change is last minus first. Rows run top to bottom, or
columns left to right with `orientation="vertical"`; use `sort` to rank by change.

## Import

```ts
import { DumbbellChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/dumbbell-chart`.

## Usage

```tsx
<DumbbellChart
  title="Citas por servicio: mes pasado contra este mes"
  items={citas}
  fromLabel="Mes pasado"
  toLabel="Este mes"
  valueFormat="integer"
  sort="none"
  rowHeight={38}
  delta="absolute"
  valueLabels
  lowerIsBetter={false}
  grid
  legend
  tooltip
  loading={false}
  animate
  deltaLabel="Cambio"
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` * | `readonly DumbbellItem[]` |  |  |
| `title` * | `string` |  | Accessible name of the chart. |
| `description` | `string` |  |  |
| `fromLabel` | `string` | `"Before"` | Name of the first value (the left dot), e.g. "Mes pasado". |
| `toLabel` | `string` | `"After"` | Name of the second value (the right dot), e.g. "Este mes". |
| `fromColor` | `string` |  |  |
| `toColor` | `string` |  |  |
| `measures` | `readonly DumbbellMeasure[]` |  | Names and colors of the dots when rows have `values`; the first and last are compared by the change. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | "vertical" draws a column per category with the dots stacked on the value axis. |
| `valueFormat` | `ValueFormat` |  |  |
| `sort` | `"none" \| "delta" \| "abs-delta" \| "to"` | `"none"` | Order of the rows; "delta" puts the biggest increase first. |
| `rowHeight` | `number` | `38` | Height of every row in pixels (default 38), horizontal only. |
| `height` | `number \| "fill"` |  | Height of the drawing in pixels, or `"fill"` to take the height of the parent. Horizontal rows stretch to it; by default they size themselves. |
| `aspectRatio` | `number` |  | Width / height ratio; stretches the rows to fit it. |
| `delta` | `false \| "percent" \| "absolute"` | `"absolute"` | Change (last minus first value) printed next to each row. `false` hides it. |
| `valueLabels` | `boolean` | `true` | Writes the values next to the dots (default true). |
| `lowerIsBetter` | `boolean` | `false` | Colors the change green when it goes down (e.g. cancellations or waiting time). |
| `xAxis` | `ValueAxisOptions` |  | Axis of the values (bottom axis, or left axis when vertical). |
| `grid` | `boolean` | `true` |  |
| `legend` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `deltaLabel` | `string` | `"Change"` |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-dumbbellchart--default)
- [Ranked By Change](/storybook/?path=/story/charts-dumbbellchart--ranked-by-change)
- [Revenue](/storybook/?path=/story/charts-dumbbellchart--revenue)
- [Lower Is Better](/storybook/?path=/story/charts-dumbbellchart--lower-is-better)
- [Columns](/storybook/?path=/story/charts-dumbbellchart--columns)
- [Three Measures](/storybook/?path=/story/charts-dumbbellchart--three-measures)
- [Three Measures Columns](/storybook/?path=/story/charts-dumbbellchart--three-measures-columns)
- [Loading](/storybook/?path=/story/charts-dumbbellchart--loading)
- [Empty](/storybook/?path=/story/charts-dumbbellchart--empty)
- [Narrow](/storybook/?path=/story/charts-dumbbellchart--narrow)

## Source

`packages/ui/src/charts/dumbbell-chart/dumbbell-chart.tsx`

---

# ExportMenu

> Two compact buttons that download the chart drawing as SVG or PNG.

Source: https://ui.jcsoftdev.com/docs/components/export-menu

Two compact buttons that download the chart drawing as SVG or PNG.
`getSvgs` runs on click, so it can read the live DOM.

## Import

```ts
import { ExportMenu } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `getSvgs` * | `(root: HTMLElement) => SVGSVGElement[]` |  | Receives the menu's own element, to find the chart around it. |
| `getLeading` | `((root: HTMLElement) => SVGSVGElement \| null)` |  | A mounted drawing placed left of the others; removed from the page once exported. |
| `texts` | `ExportTexts` | `DEFAULT_EXPORT_TEXTS` |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-exportmenu--default)
- [Spanish](/storybook/?path=/story/charts-primitives-exportmenu--spanish)

## Source

`packages/ui/src/charts/core/export-menu.tsx`

---

# FillGaugeChart

> Silhouettes filled to a level: stock left in a bottle, a battery of capacity, a droplet of water, a target reached.

Source: https://ui.jcsoftdev.com/docs/components/fill-gauge-chart

Silhouettes filled to a level: stock left in a bottle, a battery of
capacity, a droplet of water, a target reached. Several gauges sit side by
side for comparisons and wrap to new rows in narrow containers. The value
inside switches color where the liquid crosses it, so it reads on both.

## Import

```ts
import { FillGaugeChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/fill-gauge-chart`.

## Usage

```tsx
<FillGaugeChart
  title="Stock de productos (unidades)"
  data={stock}
  shape="bottle"
  level="wave"
  minItemWidth={104}
  height={200}
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `description` | `string` |  |  |
| `data` * | `readonly FillGaugeItem[]` |  |  |
| `shape` | `UnitIcon` | `"droplet"` | Built-in shape ("battery", "droplet", "bottle", "person", "target", "shield", ...) or your own. |
| `max` | `number` | `1` | Value of a full shape (1 for fractions, 100 for percentages, 24 for a box of 24 bottles). |
| `level` | `"flat" \| "wave"` | `"wave"` | "wave": a moving liquid surface; "flat": a still level. Shapes that fill sideways are always flat. |
| `valueFormat` | `ValueFormat` |  | Format of the label inside the shape. By default the fill share ("75%"). |
| `minItemWidth` | `number` | `104` | Smallest width of one gauge; more gauges than fit wrap to new rows. |
| `height` | `number \| "fill"` | `200` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the gauges from the container width. |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` | `false` |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-fillgaugechart--default)
- [Droplet](/storybook/?path=/story/charts-fillgaugechart--droplet)
- [Battery (fills sideways)](/storybook/?path=/story/charts-fillgaugechart--battery)
- [Mixed shapes (person, target, shield)](/storybook/?path=/story/charts-fillgaugechart--mixed-shapes)
- [Raw value labels, flat level](/storybook/?path=/story/charts-fillgaugechart--raw-values)
- [Custom SVG shape](/storybook/?path=/story/charts-fillgaugechart--custom-shape)
- [Loading](/storybook/?path=/story/charts-fillgaugechart--loading)
- [Empty](/storybook/?path=/story/charts-fillgaugechart--empty)
- [Narrow](/storybook/?path=/story/charts-fillgaugechart--narrow)

## Source

`packages/ui/src/charts/fill-gauge-chart/fill-gauge-chart.tsx`

---

# FunnelChart

> Funnel and pyramid: stage widths follow the value, the outline stays continuous between stages, and the conversion rate between consecutive stages sits on the joint.

Source: https://ui.jcsoftdev.com/docs/components/funnel-chart

Funnel and pyramid: stage widths follow the value, the outline stays
continuous between stages, and the conversion rate between consecutive
stages sits on the joint. Vertical or horizontal, adapts to narrow
containers (labels shrink and truncate, tooltip carries the detail).

## Import

```ts
import { FunnelChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/funnel-chart`.

## Usage

```tsx
<FunnelChart
  title="Embudo de reservas del mes"
  stages={bookings}
  variant="funnel"
  orientation="vertical"
  tapered
  neck={0.72}
  showConversion
  tone="categorical"
  gap={4}
  valueFormat="integer"
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `description` | `string` |  |  |
| `stages` * | `readonly FunnelDatum[]` |  | Stages in order: widest first. |
| `variant` | `"funnel" \| "pyramid"` | `"funnel"` | `funnel` narrows towards the last stage; `pyramid` tapers it to a point with the first stage as the base. |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` |  |
| `tapered` | `boolean` | `true` | Trapezoid stages that narrow into the next one (default); `false` draws straight bars of each stage's own width. |
| `neck` | `number` | `0.72` | How far the last stage narrows, as a fraction of its width (funnel, tapered). |
| `showConversion` | `boolean` | `true` | Conversion % between consecutive stages. |
| `tone` | `"accent" \| "categorical"` | `"categorical"` | `categorical` colors each stage; `accent` fades one brand color. |
| `gap` | `number` | `4` | Space between stages, in pixels. |
| `height` | `number \| "fill"` |  |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `valueFormat` | `ValueFormat` |  |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` | `false` |  |
| `animate` | `boolean` | `true` |  |
| `labels` | `Partial<FunnelLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-funnelchart--default)
- [Tapered](/storybook/?path=/story/charts-funnelchart--tapered)
- [Stepped](/storybook/?path=/story/charts-funnelchart--stepped)
- [Horizontal Tapered](/storybook/?path=/story/charts-funnelchart--horizontal-tapered)
- [Horizontal](/storybook/?path=/story/charts-funnelchart--horizontal)
- [Accent Ramp](/storybook/?path=/story/charts-funnelchart--accent-ramp)
- [Pyramid](/storybook/?path=/story/charts-funnelchart--pyramid)
- [Horizontal Pyramid](/storybook/?path=/story/charts-funnelchart--horizontal-pyramid)
- [Without Conversion](/storybook/?path=/story/charts-funnelchart--without-conversion)
- [Loading](/storybook/?path=/story/charts-funnelchart--loading)
- [Empty](/storybook/?path=/story/charts-funnelchart--empty)
- [Narrow](/storybook/?path=/story/charts-funnelchart--narrow)
- [Narrow Horizontal](/storybook/?path=/story/charts-funnelchart--narrow-horizontal)
- [Fill Parent](/storybook/?path=/story/charts-funnelchart--fill-parent)

## Source

`packages/ui/src/charts/funnel-chart/funnel-chart.tsx`

---

# GanttChart

> Project plan: a task list (name, start, end, progress; collapsible parents with summary bars) beside a zoomable timeline (hours to quarters) with progress bars, milestones, finish…

Source: https://ui.jcsoftdev.com/docs/components/gantt-chart

Project plan: a task list (name, start, end, progress; collapsible parents
with summary bars) beside a zoomable timeline (hours to quarters) with
progress bars, milestones, finish-to-start dependency arrows, a today line
and shaded non-working days. Both panes share one scroller, so they scroll
together; the header and the list stay pinned. Optional editing by drag or
keyboard reports changes through `onTaskChange`.

## Import

```ts
import { GanttChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/gantt-chart`.

## Usage

```tsx
<GanttChart
  title="Remodelación de la sede San Isidro"
  tasks={remodelacion}
  defaultZoom="day"
  rowHeight={36}
  editable={false}
  dependencies
  tooltip
  loading={false}
  animate
  texts={spanishTexts}
  labels={spanishLabels}
  holidays={[day(10, 8)]}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tasks` * | `readonly GanttTask[]` |  |  |
| `title` * | `string` |  | Accessible name of the chart. |
| `description` | `string` |  |  |
| `zoom` | `"week" \| "month" \| "hour" \| "day" \| "quarter" \| "year"` |  | Controlled zoom level. |
| `defaultZoom` | `"week" \| "month" \| "hour" \| "day" \| "quarter" \| "year"` | `"day"` | Initial zoom when uncontrolled, "day" by default. |
| `onZoomChange` | `((zoom: GanttZoom) => void)` |  |  |
| `zoomLevels` | `readonly GanttZoom[]` | `GANTT_ZOOM_ORDER` | Zoom buttons offered in the toolbar; all five by default. |
| `today` | `number \| false \| Date \| "auto"` | `"auto"` | Today line. "auto" uses the current date (default); false hides it. |
| `height` | `number \| "fill"` |  | Pixels, or `"fill"` to take the parent's height (rows scroll inside). By default the chart is as tall as its rows, between 220 and 560 px. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the chart from the container width. |
| `rowHeight` | `number` | `36` | Height of one task row, 36 by default. |
| `gridWidth` | `number` |  | Initial width of the task list; by default about 40% of the chart, 120-380 px. |
| `columns` | `readonly ("progress" \| "start" \| "end")[]` | `["start", "end", "progress"]` | Optional columns of the task list, shown while they fit. |
| `editable` | `boolean` | `false` | Drag bars to move or resize them and drag the progress handle; keyboard alternatives too. |
| `onTaskChange` | `((change: GanttTaskChange) => void)` |  | Receives every committed edit; update `tasks` to apply it (controlled). |
| `workingDays` | `readonly number[]` | `[1, 2, 3, 4, 5]` | Weekdays that are worked, 0 = Sunday. Monday to Friday by default. |
| `holidays` | `readonly (number \| Date)[]` |  | Extra non-working days (holidays), shaded like weekends. |
| `defaultCollapsed` | `readonly string[]` |  | Parent ids collapsed at first render. |
| `dependencies` | `boolean` | `true` | Finish-to-start arrows (default true). |
| `showCriticalPath` | `boolean` | `false` | Highlight the critical path: the chain of tasks and links with no slack, computed from the dependencies (`criticalPath`). Others show their slack in the tooltip. |
| `showBaselines` | `boolean` | `false` | Draw each task's `baseline` as a thin bar under the actual one, with the variance in the tooltip. |
| `annotations` | `readonly GanttAnnotation[]` |  | Dated lines and bands (releases, deadlines, closures) over the timeline. |
| `exportable` | `boolean` | `false` | Show SVG and PNG export buttons in the toolbar. |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `texts` | `Partial<Omit<GanttTexts, "zoomLevels" \| "zoomShort"> & { zoomLevels: Partial<GanttTexts["zoomLevels"]>; zoomShort: Partial<GanttTexts["zoomShort"]>; }>` |  |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-ganttchart--default)
- [Editable](/storybook/?path=/story/charts-ganttchart--editable)
- [Weeks](/storybook/?path=/story/charts-ganttchart--weeks)
- [Quarters](/storybook/?path=/story/charts-ganttchart--quarters)
- [Collapsed](/storybook/?path=/story/charts-ganttchart--collapsed)
- [Opening Day Hours](/storybook/?path=/story/charts-ganttchart--opening-day-hours)
- [Without Dependencies](/storybook/?path=/story/charts-ganttchart--without-dependencies)
- [Loading](/storybook/?path=/story/charts-ganttchart--loading)
- [Empty](/storybook/?path=/story/charts-ganttchart--empty)
- [Narrow](/storybook/?path=/story/charts-ganttchart--narrow)
- [Fill Parent](/storybook/?path=/story/charts-ganttchart--fill-parent)
- [Critical Path](/storybook/?path=/story/charts-ganttchart--critical-path)
- [Baselines](/storybook/?path=/story/charts-ganttchart--baselines)
- [Annotations](/storybook/?path=/story/charts-ganttchart--annotations)
- [Year View](/storybook/?path=/story/charts-ganttchart--year-view)
- [Milestones](/storybook/?path=/story/charts-ganttchart--milestones)
- [Progress](/storybook/?path=/story/charts-ganttchart--progress)
- [Export](/storybook/?path=/story/charts-ganttchart--export)

## Source

`packages/ui/src/charts/gantt-chart/gantt-chart.tsx`

---

# GaugeChart

> Gauge (semi or three-quarter arc).

Source: https://ui.jcsoftdev.com/docs/components/gauge-chart

Gauge (semi or three-quarter arc). Colored range bands, a filled progress
arc or a needle, min/max labels, optional ticks and an animated value.
Bands are explorable with the keyboard and show a tooltip.

## Import

```ts
import { GaugeChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/gauge-chart`.

## Usage

```tsx
<GaugeChart
  title="Ocupación de sillas"
  label="Ocupación de sillas"
  value={76}
  min={0}
  max={100}
  variant="semi"
  mode="progress"
  ranges={occupancyBands}
  thickness={18}
  roundedCaps
  ticks={0}
  minMaxLabels
  valueFormat={percentFormat}
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `description` | `string` |  |  |
| `value` * | `number` |  |  |
| `min` | `number` | `0` |  |
| `max` | `number` | `100` |  |
| `variant` | `"semi" \| "three-quarter"` | `"semi"` | `semi` is a half circle, `three-quarter` a 270 degree arc. |
| `mode` | `"progress" \| "needle"` | `"progress"` | Filled arc (`progress`) or a pointer over the bands (`needle`). |
| `ranges` | `readonly GaugeRange[]` |  | Colored bands. With `progress` they sit behind the arc and the arc takes the color of the band it is in. |
| `height` | `number \| "fill"` |  |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `thickness` | `number` | `18` | Arc thickness in pixels. |
| `roundedCaps` | `boolean` | `true` |  |
| `ticks` | `number` | `0` | Value labels along the inside of the arc (count of divisions, 0 = none). |
| `tickMarks` | `boolean` | `false` | Draws a tick line at every division (and at each minor step), like a dial. |
| `minorTicks` | `number` | `4` | Minor tick lines between two divisions; only with `tickMarks`. |
| `centerContent` | `((context: GaugeCenterContext) => ReactNode)` |  | Replaces the value and caption in the middle with your own content (HTML, sized to the arc). |
| `minMaxLabels` | `boolean` | `true` | Min and max under the ends of the arc. |
| `label` | `string` |  | Caption under the value, e.g. "Ocupación de sillas". |
| `valueFormat` | `ValueFormat` |  |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` | `false` |  |
| `animate` | `boolean` | `true` |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-gaugechart--default)
- [Needle](/storybook/?path=/story/charts-gaugechart--needle)
- [Three Quarter](/storybook/?path=/story/charts-gaugechart--three-quarter)
- [Three Quarter Needle](/storybook/?path=/story/charts-gaugechart--three-quarter-needle)
- [No Bands](/storybook/?path=/story/charts-gaugechart--no-bands)
- [Ticks](/storybook/?path=/story/charts-gaugechart--ticks)
- [Ticks Three Quarter](/storybook/?path=/story/charts-gaugechart--ticks-three-quarter)
- [Custom Label](/storybook/?path=/story/charts-gaugechart--custom-label)
- [Live Needle](/storybook/?path=/story/charts-gaugechart--live-needle)
- [Loading](/storybook/?path=/story/charts-gaugechart--loading)
- [Empty](/storybook/?path=/story/charts-gaugechart--empty)
- [Narrow](/storybook/?path=/story/charts-gaugechart--narrow)
- [Fill Parent](/storybook/?path=/story/charts-gaugechart--fill-parent)

## Source

`packages/ui/src/charts/gauge-chart/gauge-chart.tsx`

---

# GlobeChart

> The world as a globe (orthographic projection) you turn with the pointer or the arrow keys.

Source: https://ui.jcsoftdev.com/docs/components/globe-chart

The world as a globe (orthographic projection) you turn with the pointer or the arrow keys.
Regions can be colored by value, markers sized by value and great-circle routes drawn over the
surface. It fills its container as a disc, adapts to any width and keeps every interaction
available without a pointer.

## Import

```ts
import { GlobeChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/globe-chart`.

## Usage

```tsx
<GlobeChart
  title="Pedidos por país"
  map={worldMap}
  data={orders}
  valueName="Pedidos"
  valueFormat="integer"
  scale="sequential"
  graticule
  graticuleStep={30}
  autoRotate={false}
  autoRotateSpeed={8}
  legend
  tooltip
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the drawing and caption of the data table. |
| `map` * | `GeoMap` |  | Land to draw, e.g. `worldMap` from `@jcsoftdev/ui/charts/maps/data/world`. |
| `data` | `readonly ChoroplethDatum[]` | `[]` | Value per region (id or name); fills the land with a color scale. |
| `scale` | `"sequential" \| "diverging"` | `"sequential"` |  |
| `domain` | `readonly [number, number]` |  |  |
| `center` | `number` | `0` |  |
| `colors` | `ScaleColors` |  |  |
| `ranges` | `readonly ColorRange[]` |  |  |
| `valueFormat` | `ValueFormat` |  |  |
| `valueName` | `string` |  | Name of the value in the tooltip and the data table. |
| `points` | `readonly MapPoint[]` | `[]` | Markers on the surface, area-proportional when they carry a `value`. |
| `routes` | `readonly MapRoute[]` | `[]` | Great-circle arcs between places, lifted a little over the surface. |
| `minRadius` | `number` | `4` |  |
| `maxRadius` | `number` | `16` |  |
| `graticule` | `boolean` | `true` | Meridians and parallels. |
| `graticuleStep` | `number` | `30` | Degrees between graticule lines (30 by default). |
| `initialRotation` | `GlobeRotation` | `ROTATION_DEFAULT` | View center when the user has not turned the globe yet. Lima by default. |
| `rotation` | `GlobeRotation` |  | Controlled view center; combine with `onRotationChange`. |
| `onRotationChange` | `((rotation: GlobeRotation) => void)` |  |  |
| `autoRotate` | `boolean` | `false` | Slow idle spin that pauses while the pointer or focus is on the globe. Off under reduced motion. |
| `autoRotateSpeed` | `number` | `8` | Degrees per second of the idle spin. |
| `height` | `number \| "fill"` |  |  |
| `aspectRatio` | `number` |  |  |
| `legend` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `dataTable` | `"hidden"` |  | The numbers as a screen-reader table (always hidden visually). |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<GlobeLabels>` |  |  |
| `onRegionClick` | `((region: { id: string; name: string; value: number \| null; }) => void)` |  |  |
| `onPointClick` | `((point: MapPoint) => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-globechart--default)
- [Markers And Routes](/storybook/?path=/story/charts-globechart--markers-and-routes)
- [Auto Rotate](/storybook/?path=/story/charts-globechart--auto-rotate)
- [Narrow](/storybook/?path=/story/charts-globechart--narrow)
- [Fill Parent](/storybook/?path=/story/charts-globechart--fill-parent)
- [Brutal Preset](/storybook/?path=/story/charts-globechart--brutal-preset)
- [Controlled](/storybook/?path=/story/charts-globechart--controlled)
- [Loading](/storybook/?path=/story/charts-globechart--loading)
- [Empty](/storybook/?path=/story/charts-globechart--empty)

## Source

`packages/ui/src/charts/globe-chart/globe-chart.tsx`

---

# GridLines

> Soft background lines; the zero line, when visible, is a little stronger.

Source: https://ui.jcsoftdev.com/docs/components/grid-lines

Soft background lines; the zero line, when visible, is a little stronger.

## Import

```ts
import { GridLines } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {
  render: () => <AxesDemo title="Ventas" rightTitle="Cortes" showRight={false} showGrid />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ticks` * | `readonly AxisTick[]` |  |  |
| `direction` * | `"horizontal" \| "vertical"` |  | Lines across the plot: horizontal for a vertical value axis. |
| `length` * | `number` |  | Plot width (horizontal lines) or height (vertical lines). |
| `zero` | `number` |  | Position of the zero line, drawn stronger. |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-axes--default)
- [Dual Axis](/storybook/?path=/story/charts-primitives-axes--dual-axis)
- [Without Grid](/storybook/?path=/story/charts-primitives-axes--without-grid)
- [Default](/storybook/?path=/story/charts-primitives-cartesianchart--default)
- [Stacked](/storybook/?path=/story/charts-primitives-cartesianchart--stacked)
- [Horizontal](/storybook/?path=/story/charts-primitives-cartesianchart--horizontal)
- [Columns And Line On Right Axis](/storybook/?path=/story/charts-primitives-cartesianchart--columns-and-line-on-right-axis)
- [Area With Goal](/storybook/?path=/story/charts-primitives-cartesianchart--area-with-goal)
- [With Brush](/storybook/?path=/story/charts-primitives-cartesianchart--with-brush)
- [Loading](/storybook/?path=/story/charts-primitives-cartesianchart--loading)
- [Empty](/storybook/?path=/story/charts-primitives-cartesianchart--empty)
- [Default](/storybook/?path=/story/charts-primitives-categoryslider--default)
- [Default](/storybook/?path=/story/charts-primitives-chartbreadcrumb--default)
- [Root Only](/storybook/?path=/story/charts-primitives-chartbreadcrumb--root-only)
- [Interactive](/storybook/?path=/story/charts-primitives-chartbreadcrumb--interactive)
- [Default](/storybook/?path=/story/charts-primitives-chartbrush--default)
- [Full Range](/storybook/?path=/story/charts-primitives-chartbrush--full-range)
- [Default](/storybook/?path=/story/charts-primitives-chartdatatable--default)
- [Missing Values](/storybook/?path=/story/charts-primitives-chartdatatable--missing-values)
- [Default](/storybook/?path=/story/charts-primitives-chartframe--default)
- [Fills Parent](/storybook/?path=/story/charts-primitives-chartframe--fills-parent)
- [Aspect Ratio](/storybook/?path=/story/charts-primitives-chartframe--aspect-ratio)
- [With Legend And Table](/storybook/?path=/story/charts-primitives-chartframe--with-legend-and-table)
- [Loading](/storybook/?path=/story/charts-primitives-chartframe--loading)
- [Loading Ring](/storybook/?path=/story/charts-primitives-chartframe--loading-ring)
- [Empty](/storybook/?path=/story/charts-primitives-chartframe--empty)
- [Read Only](/storybook/?path=/story/charts-primitives-chartlegend--read-only)
- [Toggleable](/storybook/?path=/story/charts-primitives-chartlegend--toggleable)
- [Centered](/storybook/?path=/story/charts-primitives-chartlegend--centered)
- [Bars](/storybook/?path=/story/charts-primitives-chartskeleton--bars)
- [Line](/storybook/?path=/story/charts-primitives-chartskeleton--line)
- [Ring](/storybook/?path=/story/charts-primitives-chartskeleton--ring)
- [Empty](/storybook/?path=/story/charts-primitives-chartskeleton--empty)
- [Default](/storybook/?path=/story/charts-primitives-charttooltip--default)
- [Flips Near The Right Edge](/storybook/?path=/story/charts-primitives-charttooltip--flips-near-the-right-edge)
- [Without Title](/storybook/?path=/story/charts-primitives-charttooltip--without-title)
- [Default](/storybook/?path=/story/charts-primitives-exportmenu--default)
- [Spanish](/storybook/?path=/story/charts-primitives-exportmenu--spanish)
- [Default](/storybook/?path=/story/charts-primitives-hierarchyheader--default)
- [At Root](/storybook/?path=/story/charts-primitives-hierarchyheader--at-root)
- [Default](/storybook/?path=/story/charts-primitives-hierarchylegend--default)
- [Drilled In](/storybook/?path=/story/charts-primitives-hierarchylegend--drilled-in)
- [Limited](/storybook/?path=/story/charts-primitives-hierarchylegend--limited)
- [Leaf](/storybook/?path=/story/charts-primitives-hierarchylegend--leaf)
- [Default](/storybook/?path=/story/charts-primitives-hierarchytable--default)
- [From Branch](/storybook/?path=/story/charts-primitives-hierarchytable--from-branch)
- [Gallery](/storybook/?path=/story/charts-primitives-chartpatterndefs--gallery)
- [Custom Tile](/storybook/?path=/story/charts-primitives-chartpatterndefs--custom-tile)
- [Default](/storybook/?path=/story/charts-primitives-plotoverlay--default)
- [Vertical Keys](/storybook/?path=/story/charts-primitives-plotoverlay--vertical-keys)
- [Both Axes Keys](/storybook/?path=/story/charts-primitives-plotoverlay--both-axes-keys)
- [Default](/storybook/?path=/story/charts-primitives-unitglyph--default)
- [Fills Up](/storybook/?path=/story/charts-primitives-unitglyph--fills-up)
- [Scissors](/storybook/?path=/story/charts-primitives-unitglyph--scissors)
- [Without Track](/storybook/?path=/story/charts-primitives-unitglyph--without-track)

## Source

`packages/ui/src/charts/core/axes.tsx`

---

# HeatmapChart

> Matrix heatmap: one colored cell per row × column, e.g.

Source: https://ui.jcsoftdev.com/docs/components/heatmap-chart

Matrix heatmap: one colored cell per row × column, e.g. occupancy by hour
and weekday. Continuous sequential or diverging scales come from tokens;
`ranges` switches to stepped colors. Hover and keyboard focus light the
row and column of the cell.

## Import

```ts
import { HeatmapChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/heatmap-chart`.

## Usage

```tsx
<HeatmapChart
  title="Ocupación de sillas por hora y día"
  rows={days}
  columns={hours}
  values={occupancy}
  scale="sequential"
  valueFormat={percent}
  domain={[0, 100]}
  cellLabels={false}
  gap={3}
  radius={4}
  legend
  tooltip
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the drawing and caption of the data table. |
| `rows` * | `readonly string[]` |  | Row names, top to bottom. |
| `columns` * | `readonly (string \| Date)[]` |  | Column names, left to right. When every column is a `Date` the columns are consecutive points in time: the header is labelled only at calendar boundaries (weeks, months, years), like a continuous time axis. |
| `values` * | `readonly (readonly (number \| null)[])[]` |  | `values[row][column]`; `null` is a cell without data. |
| `scale` | `"sequential" \| "diverging"` | `"sequential"` | "sequential" (empty to brand) or "diverging" (low hue, neutral at `center`, brand). |
| `domain` | `readonly [number, number]` |  | Fixed [min, max] of the color scale; the data extent by default. |
| `center` | `number` | `0` | Neutral value of a diverging scale. |
| `colors` | `ScaleColors` |  | Override the scale colors (CSS colors or tokens). |
| `ranges` | `readonly ColorRange[]` |  | Stepped coloring by ranges or thresholds; replaces the continuous scale. |
| `valueFormat` | `ValueFormat` |  |  |
| `cellLabels` | `boolean` | `false` | Values inside the cells (only where they fit). |
| `gap` | `number` | `3` | Gap between cells in pixels. |
| `radius` | `number` | `4` |  |
| `shape` | `"rect" \| "hex"` | `"rect"` | "hex" draws a honeycomb: pointy-top hexagons with odd rows shifted half a cell. |
| `renderer` | `"canvas" \| "svg"` | `"svg"` | "canvas" paints the cells on a canvas, for matrices with tens of thousands of cells. Labels, tooltip, focus ring and keyboard stay SVG/HTML. |
| `height` | `number \| "fill"` |  | Height of the drawing in px or "fill"; 34 px per row plus the column header by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width. |
| `legend` | `boolean` | `true` | Color key (gradient bar or range swatches). |
| `tooltip` | `boolean` | `true` |  |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<HeatmapLabels>` |  |  |
| `onCellClick` | `((cell: HeatmapCellInfo) => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-heatmapchart--default)
- [Cell Labels](/storybook/?path=/story/charts-heatmapchart--cell-labels)
- [Diverging](/storybook/?path=/story/charts-heatmapchart--diverging)
- [Ranges](/storybook/?path=/story/charts-heatmapchart--ranges)
- [Missing Data](/storybook/?path=/story/charts-heatmapchart--missing-data)
- [Calendar](/storybook/?path=/story/charts-heatmapchart--calendar)
- [Calendar Ranges](/storybook/?path=/story/charts-heatmapchart--calendar-ranges)
- [Rounded](/storybook/?path=/story/charts-heatmapchart--rounded)
- [Honeycomb](/storybook/?path=/story/charts-heatmapchart--honeycomb)
- [Continuous Datetime](/storybook/?path=/story/charts-heatmapchart--continuous-datetime)
- [Canvas Dense](/storybook/?path=/story/charts-heatmapchart--canvas-dense)
- [Drilldown](/storybook/?path=/story/charts-heatmapchart--drilldown)
- [Narrow Drilldown](/storybook/?path=/story/charts-heatmapchart--narrow-drilldown)
- [Loading](/storybook/?path=/story/charts-heatmapchart--loading)
- [Empty](/storybook/?path=/story/charts-heatmapchart--empty)
- [Narrow](/storybook/?path=/story/charts-heatmapchart--narrow)
- [Narrow Calendar](/storybook/?path=/story/charts-heatmapchart--narrow-calendar)

## Source

`packages/ui/src/charts/heatmap-chart/heatmap-chart.tsx`

---

# HexTileMap

> Tile map: every region is one hexagon of the same size, so small regions (Callao, Tumbes) weigh as much as large ones and nothing hides behind Loreto.

Source: https://ui.jcsoftdev.com/docs/components/hex-tile-map

Tile map: every region is one hexagon of the same size, so small regions (Callao, Tumbes)
weigh as much as large ones and nothing hides behind Loreto. Colored by value like
`ChoroplethMap`, with the same legend, tooltip, keyboard model and data table. The default
layout is Peru's 25 regions; pass `tiles` for any other territory.

## Import

```ts
import { HexTileMap } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/hex-tile-map`.

## Usage

```tsx
<HexTileMap
  title="Clientes por departamento"
  data={customers}
  valueName="Clientes"
  valueFormat="integer"
  scale="sequential"
  tileLabels="both"
  legend
  tooltip
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the drawing and caption of the data table. |
| `data` * | `readonly ChoroplethDatum[]` |  | One value per tile, matched by `id` (or the tile name; accents and case are ignored). |
| `tiles` | `readonly HexTile[]` | `PERU_HEX_TILES` | The tiles and their grid cells; Peru's 25 regions by default. |
| `scale` | `"sequential" \| "diverging"` | `"sequential"` |  |
| `domain` | `readonly [number, number]` |  |  |
| `center` | `number` | `0` |  |
| `colors` | `ScaleColors` |  |  |
| `ranges` | `readonly ColorRange[]` |  | Stepped (threshold) coloring; replaces the continuous scale. |
| `valueFormat` | `ValueFormat` |  |  |
| `valueName` | `string` |  | Name of the value in the tooltip and the data table, e.g. "Clientes". |
| `tileLabels` | `"code" \| "value" \| "none" \| "both"` | `"both"` | What is written on a tile where it fits: the code, the value, both or nothing. |
| `height` | `number \| "fill"` |  | Height in px, "fill" or a default that follows the grid's proportions. |
| `aspectRatio` | `number` |  |  |
| `legend` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<MapLabels>` |  |  |
| `onTileClick` | `((tile: ChoroplethRegionInfo) => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-hextilemap--default)
- [Diverging](/storybook/?path=/story/charts-hextilemap--diverging)
- [Thresholds](/storybook/?path=/story/charts-hextilemap--thresholds)
- [Loading](/storybook/?path=/story/charts-hextilemap--loading)
- [Empty](/storybook/?path=/story/charts-hextilemap--empty)
- [Narrow](/storybook/?path=/story/charts-hextilemap--narrow)
- [Fill Parent](/storybook/?path=/story/charts-hextilemap--fill-parent)

## Source

`packages/ui/src/charts/hex-tile-map/hex-tile-map.tsx`

---

# HierarchyHeader

> Drill-down path, pass it as the frame `legend`.

Source: https://ui.jcsoftdev.com/docs/components/hierarchy-header

Drill-down path, pass it as the frame `legend`. Always first in the frame,
even when the legend moves above the drawing.

## Import

```ts
import { HierarchyHeader } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {
  render: () => <HeaderDemo start={deepest.id} />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `path` * | `readonly HierarchyNode[]` |  |  |
| `onSelect` * | `(id: string) => void` |  |  |
| `labels` * | `HierarchyLabels` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-hierarchyheader--default)
- [At Root](/storybook/?path=/story/charts-primitives-hierarchyheader--at-root)

## Source

`packages/ui/src/charts/core/hierarchy-chart.tsx`

---

# HierarchyLegend

> Read-only legend of the open level's branches, pass it as the frame `footer`: below the drawing in narrow containers, above it from `@md`.

Source: https://ui.jcsoftdev.com/docs/components/hierarchy-legend

Read-only legend of the open level's branches, pass it as the frame
`footer`: below the drawing in narrow containers, above it from `@md`.

## Import

```ts
import { HierarchyLegend } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
<HierarchyLegend focus={root} limit={8} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `focus` * | `HierarchyNode` |  |  |
| `limit` | `number` | `8` | Most items listed. |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-hierarchylegend--default)
- [Drilled In](/storybook/?path=/story/charts-primitives-hierarchylegend--drilled-in)
- [Limited](/storybook/?path=/story/charts-primitives-hierarchylegend--limited)
- [Leaf](/storybook/?path=/story/charts-primitives-hierarchylegend--leaf)

## Source

`packages/ui/src/charts/core/hierarchy-chart.tsx`

---

# HierarchyMorph

> One hierarchy, two views.

Source: https://ui.jcsoftdev.com/docs/components/hierarchy-morph

One hierarchy, two views. Switching between treemap rectangles and
sunburst rings morphs every shape: each is sampled as a polygon in both
layouts and the points glide from one to the other, so the eye follows a
branch instead of re-reading the chart.

## Import

```ts
import { HierarchyMorph } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/hierarchy-morph`.

## Usage

```tsx
<HierarchyMorph
  title="Ventas por categoría y servicio"
  data={sales}
  valueFormat="currency"
  defaultMode="treemap"
  levels={2}
  showSwitch
  height={400}
  gap={2}
  sort
  tooltip
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the drawing and caption of the data table. |
| `data` * | `HierarchyDatum` |  | Root of the tree; its total is shown in the tooltip share. |
| `mode` | `"treemap" \| "sunburst"` |  | Controlled view. |
| `defaultMode` | `"treemap" \| "sunburst"` | `"treemap"` | Initial view when uncontrolled. |
| `onModeChange` | `((mode: HierarchyMorphMode) => void)` |  |  |
| `levels` | `1 \| 2` | `2` | Levels drawn below the root (1 or 2). |
| `showSwitch` | `boolean` | `true` | Hide the built-in switch (drive `mode` from outside). |
| `height` | `number \| "fill"` | `380` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `valueFormat` | `ValueFormat` |  |  |
| `gap` | `number` | `2` | Gap between shapes in pixels. |
| `sort` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `animate` | `boolean` | `true` | Morph duration in ms; 0 or `false` swaps instantly. |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<HierarchyMorphLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-hierarchymorph--default)
- [Starts As Sunburst](/storybook/?path=/story/charts-hierarchymorph--starts-as-sunburst)
- [One Level](/storybook/?path=/story/charts-hierarchymorph--one-level)
- [Controlled](/storybook/?path=/story/charts-hierarchymorph--controlled)
- [Loading](/storybook/?path=/story/charts-hierarchymorph--loading)
- [Empty](/storybook/?path=/story/charts-hierarchymorph--empty)
- [Narrow](/storybook/?path=/story/charts-hierarchymorph--narrow)

## Source

`packages/ui/src/charts/hierarchy-morph/hierarchy-morph.tsx`

---

# HierarchyTable

> Hidden table: every node below the root with its value and share of the total.

Source: https://ui.jcsoftdev.com/docs/components/hierarchy-table

Hidden table: every node below the root with its value and share of the total.

## Import

```ts
import { HierarchyTable } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
<HierarchyTable
  root={root}
  caption="Servicios por sede y barbero"
  labels={labels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `root` * | `HierarchyNode` |  |  |
| `caption` * | `string` |  |  |
| `format` * | `ValueFormatter` |  |  |
| `labels` * | `HierarchyLabels` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-hierarchytable--default)
- [From Branch](/storybook/?path=/story/charts-primitives-hierarchytable--from-branch)

## Source

`packages/ui/src/charts/core/hierarchy-chart.tsx`

---

# Histogram

> Histogram with automatic (Freedman–Diaconis / Sturges) or fixed bins, counts or densities, and an optional fitted normal curve.

Source: https://ui.jcsoftdev.com/docs/components/histogram

Histogram with automatic (Freedman–Diaconis / Sturges) or fixed bins,
counts or densities, and an optional fitted normal curve. Hovering or
arrowing through the bins shows their range and counts.

## Import

```ts
import { Histogram } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/histogram`.

## Usage

```tsx
<Histogram
  title="Distribución del ticket de octubre"
  series={[{ id: "ticket", name: "Ticket", values: tickets }]}
  bins="auto"
  mode="count"
  normalCurve={false}
  valueFormat="currency"
  xAxis={{ title: "Ticket (S/)" }}
  height={300}
  grid
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `series` * | `readonly HistogramSeries[]` |  | One or more samples binned on the same edges; several series overlap. |
| `bins` | `number \| BinRule` | `"auto"` | Bin rule or approximate count. `auto` = Freedman–Diaconis (Sturges when the IQR is 0). |
| `binWidth` | `number` |  | Exact bin width in data units; wins over `bins`. |
| `domain` | `readonly [number, number]` |  | Range to bin; the data range by default. |
| `mode` | `"count" \| "density"` | `"count"` | "count": observations per bin. "density": count / (n · width), area 1. |
| `normalCurve` | `boolean` | `false` | Overlay the normal curve fitted to each series (same mean and standard deviation). |
| `valueFormat` | `ValueFormat` |  | Format of the binned values (x axis, tooltip ranges). |
| `xAxis` | `DistributionAxisOptions` |  |  |
| `yAxis` | `DistributionAxisOptions` |  |  |
| `exploded` | `boolean` |  | Explode every bin into one dot per observation (a dot plot on the same bins). Controlled when set; otherwise `defaultExploded` starts it. |
| `defaultExploded` | `boolean` | `false` |  |
| `onExplodedChange` | `((exploded: boolean) => void)` |  |  |
| `explodeToggle` | `boolean` | `false` | Shows the toggle button under the plot. |
| `height` | `number \| "fill"` | `300` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `grid` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `labels` | `Partial<DistributionLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-histogram--default)
- [Fixed Bin Width](/storybook/?path=/story/charts-histogram--fixed-bin-width)
- [Density With Normal Curve](/storybook/?path=/story/charts-histogram--density-with-normal-curve)
- [Sturges](/storybook/?path=/story/charts-histogram--sturges)
- [Overlaid Series](/storybook/?path=/story/charts-histogram--overlaid-series)
- [Explode](/storybook/?path=/story/charts-histogram--explode)
- [Narrow](/storybook/?path=/story/charts-histogram--narrow)
- [Loading](/storybook/?path=/story/charts-histogram--loading)
- [Empty](/storybook/?path=/story/charts-histogram--empty)

## Source

`packages/ui/src/charts/histogram/histogram.tsx`

---

# IcicleChart

> Rectangular partition: the open node fills the first band and each band after it splits its parent by value.

Source: https://ui.jcsoftdev.com/docs/components/icicle-chart

Rectangular partition: the open node fills the first band and each band
after it splits its parent by value. Drill-down zooms the clicked cell to the
full extent with an animated transition, like the sunburst.

## Import

```ts
import { IcicleChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/icicle-chart`.

## Usage

```tsx
<IcicleChart
  title="Ingresos por sede, barbero y servicio"
  data={revenueByBranch}
  valueFormat="currency"
  orientation="horizontal"
  height={360}
  levels={3}
  drillDown
  breadcrumb
  legend
  tooltip
  gap={2}
  radius={4}
  sort
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the drawing and caption of the data table. |
| `data` * | `HierarchyDatum` |  | Root of the tree; it fills the first band. |
| `height` | `number \| "fill"` | `340` | Height of the drawing in pixels. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | "horizontal": levels run left to right; "vertical": top to bottom. |
| `valueFormat` | `ValueFormat` |  |  |
| `levels` | `number` | `3` | Bands shown after the open node. |
| `drillDown` | `boolean` | `true` | Click a cell to zoom into it, the first band (or Escape) to zoom out. |
| `breadcrumb` | `boolean` | `true` |  |
| `legend` | `boolean` | `true` | Read-only legend of the open level's branches. |
| `tooltip` | `boolean` | `true` |  |
| `gap` | `number` | `2` | Gap between cells in pixels. |
| `radius` | `number` | `4` |  |
| `sort` | `boolean` | `true` |  |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<HierarchyLabels>` |  |  |
| `onFocusChange` | `((node: HierarchyNode) => void)` |  |  |
| `onNodeClick` | `((node: HierarchyNode) => void)` |  | Click on a cell that cannot be opened (a leaf). |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-iciclechart--default)
- [Vertical](/storybook/?path=/story/charts-iciclechart--vertical)
- [Two Levels](/storybook/?path=/story/charts-iciclechart--two-levels)
- [Drilldown](/storybook/?path=/story/charts-iciclechart--drilldown)
- [Loading](/storybook/?path=/story/charts-iciclechart--loading)
- [Empty](/storybook/?path=/story/charts-iciclechart--empty)
- [Narrow](/storybook/?path=/story/charts-iciclechart--narrow)

## Source

`packages/ui/src/charts/icicle-chart/icicle-chart.tsx`

---

# IsotypeRows

> Classic isotype rows: a name, then the same icon repeated in proportion to the value, then the value.

Source: https://ui.jcsoftdev.com/docs/components/isotype-rows

Classic isotype rows: a name, then the same icon repeated in proportion to
the value, then the value. Every row shares one icon size, so lengths are
comparable; icons shrink together when the container is narrow.

## Import

```ts
import { IsotypeRows } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/isotype-rows`.

## Usage

```tsx
<IsotypeRows
  title="Servicios por barbero esta semana"
  data={servicesByBarber}
  perIcon={5}
  icon="scissors"
  colorMode="single"
  track={false}
  rowHeight={34}
  gap={0.18}
  valueFormat="integer"
  showValues
  unitLabel="servicios"
  tooltip
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `description` | `string` |  |  |
| `data` * | `readonly UnitCategory[]` |  | One row per entry. |
| `perIcon` | `number` | `1` | Value one icon stands for; the last icon of a row is cut to its remainder. |
| `icon` | `UnitIcon` | `"scissors"` |  |
| `colorMode` | `"category" \| "single"` | `"single"` | "single": every row in one color (classic isotype); "category": palette color per row. |
| `color` | `string` |  | Color in "single" mode; the brand tone by default. |
| `track` | `boolean` | `false` | Pads every row with empty icons up to the longest one. |
| `height` | `"fill"` |  | `"fill"` spreads the rows over the height of the parent instead of using `rowHeight`. |
| `rowHeight` | `number` | `34` | Height of one row in pixels; the chart height follows the number of rows. |
| `gap` | `number` | `0.18` | Gap between icons, as a fraction of the icon size. |
| `valueFormat` | `ValueFormat` | `"integer"` |  |
| `showValues` | `boolean` | `true` | Value at the end of each row. |
| `unitLabel` | `string` | `"units"` | What the values count, for the key and the tooltip ("servicios"). |
| `showKey` | `boolean` |  | Shows "icon = N unitLabel" under the rows. Defaults to on when `perIcon` is not 1. |
| `tooltip` | `boolean` | `true` |  |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` | `false` |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-isotyperows--default)
- [Color Per Row](/storybook/?path=/story/charts-isotyperows--color-per-row)
- [Track to the longest row](/storybook/?path=/story/charts-isotyperows--with-track)
- [Icon per row](/storybook/?path=/story/charts-isotyperows--icon-per-row)
- [Review Ratings](/storybook/?path=/story/charts-isotyperows--review-ratings)
- [Response Times](/storybook/?path=/story/charts-isotyperows--response-times)
- [Store Locations](/storybook/?path=/story/charts-isotyperows--store-locations)
- [Loading](/storybook/?path=/story/charts-isotyperows--loading)
- [Empty](/storybook/?path=/story/charts-isotyperows--empty)
- [Narrow](/storybook/?path=/story/charts-isotyperows--narrow)

## Source

`packages/ui/src/charts/isotype-rows/isotype-rows.tsx`

---

# LineChart

> Trends over categories or time.

Source: https://ui.jcsoftdev.com/docs/components/line-chart

Trends over categories or time. Smooth monotone curves by default (they
never overshoot the data), straight with `curve="linear"`; `dashed` series
for forecasts or comparisons; `brush` for zooming long date ranges. Other
curves: `"step"`, `"step-before"`, `"step-after"` for values that hold until
they change (stock levels, prices).

## Import

```ts
import { LineChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/line-chart`.

## Usage

```tsx
<LineChart
  title="Ventas por día"
  categories={twoWeeks.dates}
  series={[{ id: "ventas", name: "Ventas", data: twoWeeks.values }]}
  valueFormat="currency"
  height={300}
  curve="smooth"
  markers={false}
  dataLabels={false}
  grid
  tooltip
  brush={false}
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `series` * | `readonly ChartSeries[]` |  |  |
| `gradient` | `boolean` | `false` | Strokes each line with a gradient from its color towards the next palette color. |
| `legend` | `boolean \| "top" \| "bottom"` |  | Legend placement, or false to hide it. Defaults to "top" with two or more series. |
| `title` * | `string` |  | Accessible name of the chart (`aria-label` of the drawing). |
| `animate` | `boolean` |  | Entry animation (default true; always off with prefers-reduced-motion). |
| `className` | `string` |  |  |
| `grid` | `boolean` |  | Background gridlines (default true). |
| `tooltip` | `boolean` |  | Shared tooltip (default true). |
| `categories` * | `readonly XValue[]` |  | One entry per data point: strings, numbers or dates. |
| `description` | `string` |  | Extra sentence for the hidden data table caption. |
| `height` | `number \| "fill"` |  | Height of the plot in pixels, 300 by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the plot from the container width (wins over a pixel `height`). |
| `curve` | `"linear" \| "smooth" \| "step" \| "step-before" \| "step-after"` | `"smooth"` |  |
| `markers` | `boolean` |  | Dots on every line point. Hovered points are always marked. |
| `dataLabels` | `boolean` |  | Values printed on the marks. |
| `transition` | `boolean` |  | Eases lines and areas between data updates (live data); off by default. |
| `maxPoints` | `number \| false` |  | Series with more points than this are reduced with LTTB, 2000 by default; `false` draws every point. |
| `syncId` | `string` |  | Charts with the same id share hover (crosshair and tooltip) and the zoom window. |
| `onPointClick` | `((point: CartesianPointEvent) => void)` |  | Called with the category (and nearest series) under the pointer when the plot is clicked or Enter is pressed. |
| `valueFormat` | `ValueFormat` |  | Format of values in tooltips, labels and the data table. |
| `xFormat` | `((value: XValue) => string)` |  | Label of a category on the axis and in the tooltip (dates get Spanish defaults). |
| `xScale` | `"time" \| "auto" \| "band"` |  | "time" spaces dates by real elapsed time; "auto" picks it when every category is a Date and no series is a column. |
| `yAxis` | `ValueAxisOptions` |  |  |
| `axes` | `readonly CartesianAxisSpec[]` |  | Any number of value axes. `yAxis` and `rightAxis` are shorthand for the ids "left" and "right"; more entries stack outward on their `side` (right by default) and series pick one with `axis`. |
| `annotations` | `readonly ChartAnnotation[]` |  |  |
| `categoryLabelRotation` | `number` |  | Tilts the category labels (degrees, e.g. -45) so long names fit; vertical charts only. |
| `categoryGroups` | `readonly CategoryGroup[]` |  | Second tier of labels under the category axis (vertical charts); counts must add up to the categories. |
| `onCategoryClick` | `((index: number) => void)` |  | Click (or Enter on the focused plot) on a category; receives its index in `categories`. |
| `brush` | `boolean` |  | Drag-to-zoom on the plot plus an overview brush with a reset button. |
| `overlay` | `CartesianOverlay` |  | Extra layers over the plot, e.g. the ruler and ink tools of `useChartInk`. Vertical charts only. |
| `rangeSelect` | `{ value: readonly [number, number] \| null; onChange: (range: readonly [number, number] \| null) => void; }` |  |  |
| `loading` | `boolean` |  |  |
| `initialHidden` | `readonly string[]` |  | Series hidden at first; the legend can show them. |
| `labels` | `Partial<ChartLabels>` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-linechart--default)
- [Straight](/storybook/?path=/story/charts-linechart--straight)
- [Compared with last period (dashed)](/storybook/?path=/story/charts-linechart--compared-with-last-period)
- [Data Labels](/storybook/?path=/story/charts-linechart--data-labels)
- [Annotations (goal and holiday)](/storybook/?path=/story/charts-linechart--goal-and-holiday)
- [Brush and zoom (92 days)](/storybook/?path=/story/charts-linechart--brush-zoom)
- [With Gaps](/storybook/?path=/story/charts-linechart--with-gaps)
- [Step](/storybook/?path=/story/charts-linechart--step)
- [Annotated (lines, bands, markers, text)](/storybook/?path=/story/charts-linechart--annotated)
- [Gradient](/storybook/?path=/story/charts-linechart--gradient)
- [Synced Charts](/storybook/?path=/story/charts-linechart--synced-charts)
- [Live Append](/storybook/?path=/story/charts-linechart--live-append)
- [Downsampled (100k points)](/storybook/?path=/story/charts-linechart--downsampled-100-k)
- [Drilldown](/storybook/?path=/story/charts-linechart--drilldown)
- [Drilldown Narrow](/storybook/?path=/story/charts-linechart--drilldown-narrow)
- [Loading](/storybook/?path=/story/charts-linechart--loading)
- [Empty](/storybook/?path=/story/charts-linechart--empty)
- [Fill Parent](/storybook/?path=/story/charts-linechart--fill-parent)
- [Narrow](/storybook/?path=/story/charts-linechart--narrow)

## Source

`packages/ui/src/charts/line-chart/line-chart.tsx`

---

# LineDrilldown

> A line chart you can drill into: click (or press Enter on) a point that has children to zoom into it, and use the breadcrumb to climb back out.

Source: https://ui.jcsoftdev.com/docs/components/line-drilldown

A line chart you can drill into: click (or press Enter on) a point that has
children to zoom into it, and use the breadcrumb to climb back out.

## Import

```ts
import { LineDrilldown } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/line-chart`.

## Usage

```tsx
<LineDrilldown
  title="Ventas por día"
  categories={twoWeeks.dates}
  series={[{ id: "ventas", name: "Ventas", data: twoWeeks.values }]}
  valueFormat="currency"
  height={300}
  curve="smooth"
  markers={false}
  dataLabels={false}
  grid
  tooltip
  brush={false}
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` * | `HierarchyDatum` |  | Hierarchy to walk. The children of the focused node are the points of the line, in the order given; a node's value is its own or the sum of its children. |
| `seriesName` | `string` |  | Name of the line in legend and tooltip. |
| `breadcrumbLabel` | `string` | `"Drilldown path"` | Accessible name of the breadcrumb landmark. |
| `legend` | `boolean \| "top" \| "bottom"` |  | Legend placement, or false to hide it. Defaults to "top" with two or more series. |
| `title` * | `string` |  | Accessible name of the chart (`aria-label` of the drawing). |
| `animate` | `boolean` |  | Entry animation (default true; always off with prefers-reduced-motion). |
| `className` | `string` |  |  |
| `grid` | `boolean` |  | Background gridlines (default true). |
| `tooltip` | `boolean` |  | Shared tooltip (default true). |
| `gradient` | `boolean` |  | Strokes each line with a gradient from its color towards the next palette color. |
| `description` | `string` |  | Extra sentence for the hidden data table caption. |
| `height` | `number \| "fill"` |  | Height of the plot in pixels, 300 by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the plot from the container width (wins over a pixel `height`). |
| `curve` | `"linear" \| "smooth" \| "step" \| "step-before" \| "step-after"` |  |  |
| `markers` | `boolean` |  | Dots on every line point. Hovered points are always marked. |
| `dataLabels` | `boolean` |  | Values printed on the marks. |
| `transition` | `boolean` |  | Eases lines and areas between data updates (live data); off by default. |
| `maxPoints` | `number \| false` |  | Series with more points than this are reduced with LTTB, 2000 by default; `false` draws every point. |
| `syncId` | `string` |  | Charts with the same id share hover (crosshair and tooltip) and the zoom window. |
| `valueFormat` | `ValueFormat` |  | Format of values in tooltips, labels and the data table. |
| `xFormat` | `((value: XValue) => string)` |  | Label of a category on the axis and in the tooltip (dates get Spanish defaults). |
| `xScale` | `"time" \| "auto" \| "band"` |  | "time" spaces dates by real elapsed time; "auto" picks it when every category is a Date and no series is a column. |
| `yAxis` | `ValueAxisOptions` |  |  |
| `axes` | `readonly CartesianAxisSpec[]` |  | Any number of value axes. `yAxis` and `rightAxis` are shorthand for the ids "left" and "right"; more entries stack outward on their `side` (right by default) and series pick one with `axis`. |
| `annotations` | `readonly ChartAnnotation[]` |  |  |
| `categoryLabelRotation` | `number` |  | Tilts the category labels (degrees, e.g. -45) so long names fit; vertical charts only. |
| `categoryGroups` | `readonly CategoryGroup[]` |  | Second tier of labels under the category axis (vertical charts); counts must add up to the categories. |
| `onCategoryClick` | `((index: number) => void)` |  | Click (or Enter on the focused plot) on a category; receives its index in `categories`. |
| `brush` | `boolean` |  | Drag-to-zoom on the plot plus an overview brush with a reset button. |
| `overlay` | `CartesianOverlay` |  | Extra layers over the plot, e.g. the ruler and ink tools of `useChartInk`. Vertical charts only. |
| `rangeSelect` | `{ value: readonly [number, number] \| null; onChange: (range: readonly [number, number] \| null) => void; }` |  |  |
| `loading` | `boolean` |  |  |
| `initialHidden` | `readonly string[]` |  | Series hidden at first; the legend can show them. |
| `labels` | `Partial<ChartLabels>` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-linechart--default)
- [Straight](/storybook/?path=/story/charts-linechart--straight)
- [Compared with last period (dashed)](/storybook/?path=/story/charts-linechart--compared-with-last-period)
- [Data Labels](/storybook/?path=/story/charts-linechart--data-labels)
- [Annotations (goal and holiday)](/storybook/?path=/story/charts-linechart--goal-and-holiday)
- [Brush and zoom (92 days)](/storybook/?path=/story/charts-linechart--brush-zoom)
- [With Gaps](/storybook/?path=/story/charts-linechart--with-gaps)
- [Step](/storybook/?path=/story/charts-linechart--step)
- [Annotated (lines, bands, markers, text)](/storybook/?path=/story/charts-linechart--annotated)
- [Gradient](/storybook/?path=/story/charts-linechart--gradient)
- [Synced Charts](/storybook/?path=/story/charts-linechart--synced-charts)
- [Live Append](/storybook/?path=/story/charts-linechart--live-append)
- [Downsampled (100k points)](/storybook/?path=/story/charts-linechart--downsampled-100-k)
- [Drilldown](/storybook/?path=/story/charts-linechart--drilldown)
- [Drilldown Narrow](/storybook/?path=/story/charts-linechart--drilldown-narrow)
- [Loading](/storybook/?path=/story/charts-linechart--loading)
- [Empty](/storybook/?path=/story/charts-linechart--empty)
- [Fill Parent](/storybook/?path=/story/charts-linechart--fill-parent)
- [Narrow](/storybook/?path=/story/charts-linechart--narrow)

## Source

`packages/ui/src/charts/line-chart/line-drilldown.tsx`

---

# MapDataTable

> Visible, sortable table with the same numbers as a choropleth: the accessible alternative to the colors.

Source: https://ui.jcsoftdev.com/docs/components/map-data-table

Visible, sortable table with the same numbers as a choropleth: the accessible alternative to
the colors. A bar next to each value repeats the magnitude without relying on hue. Rows
without data always sort last.

## Import

```ts
import { MapDataTable } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/maps`.

## Usage

```tsx
<MapDataTable
  caption="Citas por distrito"
  rows={rows}
  valueName="Citas"
  labels={labels}
  height={280}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `caption` * | `string` |  |  |
| `rows` * | `readonly MapDataRow[]` |  |  |
| `valueName` * | `string` |  |  |
| `labels` * | `MapLabels` |  |  |
| `height` * | `number` |  | Height in px of the scrolling area. |
| `onRowClick` | `((row: MapDataRow) => void)` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-mapdatatable--default)
- [Narrow](/storybook/?path=/story/charts-primitives-mapdatatable--narrow)

## Source

`packages/ui/src/charts/maps/geo/map-data-table.tsx`

---

# MapLegend

> Color key of a choropleth: a gradient bar with its extremes (and centre when diverging), or one swatch per range.

Source: https://ui.jcsoftdev.com/docs/components/map-legend

Color key of a choropleth: a gradient bar with its extremes (and centre when
diverging), or one swatch per range. It sits under the map in narrow
containers and above it, aligned to the end, from `@md/chart`.

## Import

```ts
import { MapLegend } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/maps`.

## Usage

```tsx
<MapLegend
  kind="sequential"
  domain={[0, 24000]}
  format={soles}
  noData="Sin sedes"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` * | `"sequential" \| "diverging"` |  |  |
| `domain` * | `readonly [number, number]` |  |  |
| `center` | `number` | `0` |  |
| `colors` | `ScaleColors` |  |  |
| `ranges` | `readonly ColorRange[]` |  | Stepped scale: one swatch per range instead of a gradient bar. |
| `format` * | `ValueFormatter` |  |  |
| `noData` | `string` |  | Swatch for regions without data, with its label. |

`*` marks a required prop.

## Storybook stories

- [Sequential](/storybook/?path=/story/charts-primitives-maplegend--sequential)
- [Diverging](/storybook/?path=/story/charts-primitives-maplegend--diverging)
- [Stepped Ranges](/storybook/?path=/story/charts-primitives-maplegend--stepped-ranges)

## Source

`packages/ui/src/charts/maps/geo/map-legend.tsx`

---

# MapViewport

> The shared stage of the maps: draws the regions of a fitted geometry, owns zoom and pan (wheel, drag, pinch, buttons, keys), the region labels, the zoom buttons and the focusable …

Source: https://ui.jcsoftdev.com/docs/components/map-viewport

The shared stage of the maps: draws the regions of a fitted geometry, owns
zoom and pan (wheel, drag, pinch, buttons, keys), the region labels, the
zoom buttons and the focusable keyboard layer. Charts supply fills,
hover/click semantics, an SVG overlay (markers) and HTML (tooltip).

## Import

```ts
import { MapViewport } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/maps`.

## Usage

```tsx
<MapViewport
  caption="Citas por distrito"
  rows={rows}
  valueName="Citas"
  labels={labels}
  height={280}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `width` * | `number` |  |  |
| `height` * | `number` |  |  |
| `title` * | `string` |  | Accessible name of the drawing. |
| `geometry` * | `MapGeometry` |  |  |
| `labels` * | `MapLabels` |  |  |
| `fills` * | `readonly string[]` |  | CSS fill of each region. |
| `interactive` * | `boolean` |  | Regions react to hover, focus and click. Off for a plain base map. |
| `activeRegion` | `number \| null` | `null` | Region under the pointer or the keyboard, or null. |
| `onRegionHover` | `((index: number, event: { clientX: number; clientY: number; }) => void)` |  |  |
| `onLeave` | `(() => void)` |  |  |
| `onRegionClick` | `((index: number) => void)` |  |  |
| `regionLabels` | `readonly (string \| null)[]` |  | Text drawn on each region where it fits (null leaves it out). |
| `controller` * | `{ ref: RefObject<SVGSVGElement \| null>; view: MapView; dragging: boolean; wasDragged: () => boolean; zoomBy: (factor: number, cx?: number, cy?: number) => void; fit: () => void; panBy: (dx: number, dy: number) => void; …` |  | Zoom and pan state, from `useMapView`; the parent owns it so markers can depend on the zoom. |
| `zoomable` * | `boolean` |  | Shows the zoom buttons and enables the zoom keys (gestures are configured in `useMapView`). |
| `containerRef` | `RefObject<HTMLDivElement \| null>` |  | Ref of the positioned container, for pointer-relative tooltips. |
| `keyboard` | `{ count: number; active: number \| null; valueText: string; onKeyDown?: (event: KeyboardEvent<HTMLElement>) => void; onFocus?: () => void; onBlur?: () => void; onActivate?: () => void; }` |  | Keyboard model, usually from `useIndexNavigation(...).sliderProps`. |
| `reveal` | `readonly [number, number] \| null` |  | Zoom 1 pixel position to keep in view while the keyboard moves (null: no panning). |
| `overlay` | `((context: MapViewportContext) => ReactNode)` |  | SVG drawn in screen space over the regions (markers, bubbles). |
| `floating` | `((context: MapViewportContext) => ReactNode)` |  | HTML positioned over the map (tooltips). |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-mapdatatable--default)
- [Narrow](/storybook/?path=/story/charts-primitives-mapdatatable--narrow)
- [Sequential](/storybook/?path=/story/charts-primitives-maplegend--sequential)
- [Diverging](/storybook/?path=/story/charts-primitives-maplegend--diverging)
- [Stepped Ranges](/storybook/?path=/story/charts-primitives-maplegend--stepped-ranges)
- [Default](/storybook/?path=/story/charts-primitives-mapviewport--default)
- [With Region Names](/storybook/?path=/story/charts-primitives-mapviewport--with-region-names)
- [Static Base Map](/storybook/?path=/story/charts-primitives-mapviewport--static-base-map)

## Source

`packages/ui/src/charts/maps/geo/map-viewport.tsx`

---

# ObservationDots

> Raw observations of a box or violin as small dots (jitter already applied).

Source: https://ui.jcsoftdev.com/docs/components/observation-dots

Raw observations of a box or violin as small dots (jitter already applied).

## Import

```ts
import { ObservationDots } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `points` * | `readonly { value: number; offset: number; }[]` |  |  |
| `map` * | `(value: number) => number` |  | Value to pixel along the value axis. |
| `center` * | `number` |  | Pixel of the group axis on the cross axis. |
| `horizontal` * | `boolean` |  |  |
| `color` * | `string` |  |  |
| `coloring` | `"value" \| "series"` | `"series"` | "value" grades the fill from a pale tint of `color` to `color` across `range`. |
| `range` | `readonly [number, number]` |  |  |
| `radius` | `number` | `2.6` |  |
| `dimmed` | `boolean` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-observationdots--default)
- [Graded By Value](/storybook/?path=/story/charts-primitives-observationdots--graded-by-value)
- [Dimmed](/storybook/?path=/story/charts-primitives-observationdots--dimmed)

## Source

`packages/ui/src/charts/core/distribution/observations.tsx`

---

# ParliamentChart

> Hemicycle of seats: the arcs are worked out for the total, every arc gets seats in proportion to its length, and groups are laid left to right so each one reads as a wedge.

Source: https://ui.jcsoftdev.com/docs/components/parliament-chart

Hemicycle of seats: the arcs are worked out for the total, every arc gets
seats in proportion to its length, and groups are laid left to right so
each one reads as a wedge. Optional majority mark and seat total.

## Import

```ts
import { ParliamentChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/parliament-chart`.

## Usage

```tsx
<ParliamentChart
  title="Encuesta: servicio favorito (130 clientes)"
  data={pollVotes}
  innerRatio={0.4}
  seatShape="circle"
  majority={false}
  majorityLabel="Mayoría"
  centerLabel="votos"
  seatLabel="Votos"
  height={260}
  legend
  tooltip
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `description` | `string` |  |  |
| `data` * | `readonly Omit<UnitCategory, "icon">[]` |  | One group per entry; `value` is its number of seats (whole numbers). |
| `rows` | `number` |  | Number of arcs; computed from the seat count by default. |
| `innerRatio` | `number` | `0.4` | Radius of the innermost arc as a fraction of the outer one. |
| `seatShape` | `"circle" \| "square"` | `"circle"` |  |
| `majority` | `number \| boolean` | `false` | Draws the majority mark at the top of the arc: `true` for half the seats plus one, or an explicit number of seats. |
| `majorityLabel` | `string` | `"Majority"` | Text before the majority figure. |
| `centerLabel` | `string` |  | Word under the seat total in the middle ("escaños", "sillas"). Omit to hide the total. |
| `seatLabel` | `string` | `"Seats"` | Name of the counted thing in the tooltip and data table. |
| `height` | `number \| "fill"` | `260` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `legend` | `boolean \| "top" \| "bottom"` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` | `false` |  |
| `initialHidden` | `readonly string[]` |  |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-parliamentchart--default)
- [Majority line](/storybook/?path=/story/charts-parliamentchart--with-majority)
- [Square Seats](/storybook/?path=/story/charts-parliamentchart--square-seats)
- [Many seats (auto rows)](/storybook/?path=/story/charts-parliamentchart--many-seats)
- [Fixed Rows](/storybook/?path=/story/charts-parliamentchart--fixed-rows)
- [Loading](/storybook/?path=/story/charts-parliamentchart--loading)
- [Empty](/storybook/?path=/story/charts-parliamentchart--empty)
- [Narrow](/storybook/?path=/story/charts-parliamentchart--narrow)

## Source

`packages/ui/src/charts/parliament-chart/parliament-chart.tsx`

---

# PictogramChart

> Isotype pictogram: every icon stands for `perUnit` of something (clients, services, bottles) and the last icon of a category is cut to its remainder.

Source: https://ui.jcsoftdev.com/docs/components/pictogram-chart

Isotype pictogram: every icon stands for `perUnit` of something (clients,
services, bottles) and the last icon of a category is cut to its remainder.
Icons grow to the largest size that fits the box, up to `unitSize`.

## Import

```ts
import { PictogramChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/pictogram-chart`.

## Usage

```tsx
<PictogramChart
  title="Clientes atendidos hoy"
  data={visitsBySegment}
  perUnit={1}
  icon="person"
  layout="grid"
  unitSize={28}
  gap={0.25}
  height={200}
  unitLabel="clientes"
  valueFormat="integer"
  legend
  tooltip
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `description` | `string` |  |  |
| `data` * | `readonly UnitCategory[]` |  |  |
| `perUnit` | `number` | `1` | Value one icon stands for. The last icon of a category is clipped to its remainder. |
| `icon` | `UnitIcon` | `"person"` | Built-in icon name, a 24 x 24 path, or a `UnitShape`. |
| `layout` | `"grid" \| "rows"` | `"grid"` | "grid": categories flow one after the other; "rows": each category starts a new row. |
| `columns` | `number` |  | Fixed number of columns; by default the largest icons that fit the box decide. |
| `total` | `number` |  | Capacity drawn as empty icons after the data (grid layout), e.g. 120 seats a day. |
| `unitSize` | `number` | `32` | Largest icon side in pixels. |
| `gap` | `number` | `0.25` | Gap between icons, as a fraction of the icon size. |
| `height` | `number \| "fill"` | `200` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `valueFormat` | `ValueFormat` | `"integer"` |  |
| `unitLabel` | `string` | `"units"` | What the values count, for the key and the tooltip ("clientes"). |
| `showKey` | `boolean` |  | Shows "icon = N unitLabel" under the chart. Defaults to on when `perUnit` is not 1. |
| `legend` | `boolean \| "top" \| "bottom"` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` | `false` |  |
| `initialHidden` | `readonly string[]` |  |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-pictogramchart--default)
- [Partial units (1 icon = 5)](/storybook/?path=/story/charts-pictogramchart--partial-units)
- [Rows layout, icon per category](/storybook/?path=/story/charts-pictogramchart--rows)
- [Capacity (empty units)](/storybook/?path=/story/charts-pictogramchart--capacity)
- [Custom SVG shape](/storybook/?path=/story/charts-pictogramchart--custom-shape)
- [Silhouettes](/storybook/?path=/story/charts-pictogramchart--silhouettes)
- [Mixed Silhouettes](/storybook/?path=/story/charts-pictogramchart--mixed-silhouettes)
- [Loading](/storybook/?path=/story/charts-pictogramchart--loading)
- [Empty](/storybook/?path=/story/charts-pictogramchart--empty)
- [Narrow](/storybook/?path=/story/charts-pictogramchart--narrow)

## Source

`packages/ui/src/charts/pictogram-chart/pictogram-chart.tsx`

---

# PieChart

> A donut without the hole: same slices, rounded corners, gaps, explode on hover, outside labels and legend toggling (see `DonutChart`).

Source: https://ui.jcsoftdev.com/docs/components/pie-chart

A donut without the hole: same slices, rounded corners, gaps, explode on
hover, outside labels and legend toggling (see `DonutChart`).

## Import

```ts
import { PieChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/pie-chart`.

## Usage

```tsx
<PieChart
  title="Ventas por medio de pago"
  data={payments}
  valueFormat="currency"
  semi={false}
  cornerRadius={8}
  gap={3}
  explode={10}
  outsideLabels={false}
  height={320}
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` * | `readonly DonutDatum[]` |  |  |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `title` * | `string` |  | Accessible name of the drawing. |
| `animate` | `boolean` |  |  |
| `className` | `string` |  |  |
| `fill` | `"pattern" \| "solid" \| "gradient"` |  | `gradient` fades each slice towards the hole; `pattern` adds a texture per slice, so color is not the only cue. |
| `tooltip` | `boolean` |  |  |
| `description` | `string` |  |  |
| `height` | `number \| "fill"` |  |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `valueFormat` | `ValueFormat` |  |  |
| `loading` | `boolean` |  |  |
| `initialHidden` | `readonly string[]` |  | Ids hidden at first. |
| `labels` | `Partial<ChartLabels>` |  |  |
| `explode` | `number` |  | Pixels a hovered or focused slice moves outwards. |
| `semi` | `boolean` |  | Half circle opening upwards, like a gauge. |
| `gap` | `number` |  | Visible gap between slices, in pixels. |
| `cornerRadius` | `number` | `8` | Radius of the rounded slice corners, in pixels. 0 = sharp. |
| `startAngle` | `number` |  | Where the first slice starts, in degrees from 12 o'clock (full circle only). |
| `monochrome` | `string \| boolean` |  | One hue in shades, darkest on the largest slice. `true` uses the accent; a string sets the base color. |
| `drilldown` | `boolean` |  | Slices with `children` open on click (or Enter) with a breadcrumb to go back. |
| `rootLabel` | `string` |  | First breadcrumb item; defaults to the chart title. |
| `breadcrumbLabel` | `string` |  | Accessible name of the breadcrumb. |
| `outsideLabels` | `boolean \| "name" \| "percent" \| "both"` |  | Names / percentages on leader lines around the ring. `true` shows both. |
| `onSliceClick` | `((datum: DonutDatum) => void)` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-piechart--default)
- [Outside Labels](/storybook/?path=/story/charts-piechart--outside-labels)
- [Semi Pie](/storybook/?path=/story/charts-piechart--semi-pie)
- [Sharp No Gap](/storybook/?path=/story/charts-piechart--sharp-no-gap)
- [Monochrome](/storybook/?path=/story/charts-piechart--monochrome)
- [Loading](/storybook/?path=/story/charts-piechart--loading)
- [Empty](/storybook/?path=/story/charts-piechart--empty)
- [Narrow](/storybook/?path=/story/charts-piechart--narrow)

## Source

`packages/ui/src/charts/pie-chart/pie-chart.tsx`

---

# PlotExplorer

> Transparent overlay that owns pointer and keyboard exploration of a plot: a focusable `role="slider"` (arrows move, Home/End jump, Escape clears), the same contract as the cartesi…

Source: https://ui.jcsoftdev.com/docs/components/plot-explorer

Transparent overlay that owns pointer and keyboard exploration of a plot:
a focusable `role="slider"` (arrows move, Home/End jump, Escape clears),
the same contract as the cartesian charts.

## Import

```ts
import { PlotExplorer } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => <ExplorerDemo count={args.count} label={args.label} />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` * | `number` |  | Number of explorable items (boxes, bins, points), in reading order. |
| `active` * | `number \| null` |  |  |
| `onActiveChange` * | `(index: number \| null) => void` |  |  |
| `pick` * | `(x: number, y: number) => number \| null` |  | Item under a plot-relative pixel, or null. |
| `label` * | `string` |  | Accessible name, e.g. `labels.explore`. |
| `valueText` * | `string` |  | What a screen reader announces for the active item. |
| `margin` * | `PlotMargin` |  |  |
| `width` * | `number` |  |  |
| `height` * | `number` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-plotexplorer--default)
- [Empty](/storybook/?path=/story/charts-primitives-plotexplorer--empty)

## Source

`packages/ui/src/charts/core/distribution/explorer.tsx`

---

# PlotOverlay

> Transparent, focusable layer over a plot: one place for pointer hover and keyboard exploration, shared by the non-cartesian charts.

Source: https://ui.jcsoftdev.com/docs/components/plot-overlay

Transparent, focusable layer over a plot: one place for pointer hover and
keyboard exploration, shared by the non-cartesian charts. It is a
`role="slider"` so assistive tech announces `valueText` as the arrows move.
Arrows step, Home/End jump, Escape clears.

## Import

```ts
import { PlotOverlay } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => <OverlayDemo keys={args.keys ?? "horizontal"} />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `left` * | `number` |  | Position and size of the plot inside the chart container. |
| `top` * | `number` |  |  |
| `width` * | `number` |  |  |
| `height` * | `number` |  |  |
| `label` * | `string` |  | Accessible name (`labels.explore`). |
| `count` * | `number` |  | Number of explorable points. |
| `active` * | `number \| null` |  | Active point, or null. |
| `valueText` * | `string` |  | Reads the active point aloud: category and values. |
| `onActiveChange` * | `(index: number \| null) => void` |  |  |
| `indexAt` * | `(pointer: PlotPointer) => number \| null` |  | Maps a plot-relative pointer to a point; return null to clear (hit-testing charts). |
| `keys` | `"horizontal" \| "vertical" \| "both"` | `"horizontal"` | Which arrow keys step through the points. "both" maps Right/Down to next and Left/Up to previous. |
| `onKey` | `((event: KeyboardEvent<HTMLDivElement>) => boolean)` |  | Extra key handling, e.g. switching streams with Up/Down. Return true when handled. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-plotoverlay--default)
- [Vertical Keys](/storybook/?path=/story/charts-primitives-plotoverlay--vertical-keys)
- [Both Axes Keys](/storybook/?path=/story/charts-primitives-plotoverlay--both-axes-keys)

## Source

`packages/ui/src/charts/core/plot-overlay.tsx`

---

# PolarAreaChart

> Polar area (Nightingale rose): equal-angle sectors whose radius, or area, follows the value.

Source: https://ui.jcsoftdev.com/docs/components/polar-area-chart

Polar area (Nightingale rose): equal-angle sectors whose radius, or area,
follows the value. Reference rings, rim labels, hover and keyboard focus
with a tooltip, legend toggling.

## Import

```ts
import { PolarAreaChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/polar-area-chart`.

## Usage

```tsx
<PolarAreaChart
  title="Citas por día de la semana"
  data={weekday}
  scale="radius"
  innerRadius={0.1}
  cornerRadius={4}
  gap={3}
  levels={4}
  showLabels
  startAngle={0}
  valueFormat="integer"
  height={380}
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `description` | `string` |  |  |
| `data` * | `readonly PolarAreaDatum[]` |  |  |
| `scale` | `"area" \| "radius"` | `"radius"` | `radius`: length proportional to value. `area`: sector area proportional to value (Nightingale rose). |
| `innerRadius` | `number` | `0.1` | Hole in the middle as a fraction of the outer radius. |
| `cornerRadius` | `number` | `4` |  |
| `gap` | `number` | `3` | Gap between sectors, in pixels at the outer ring. |
| `levels` | `number` | `4` | Concentric reference rings. |
| `showLabels` | `boolean` | `true` | Names around the rim (hidden automatically in narrow containers). |
| `startAngle` | `number` | `0` | Rotation of the first sector, in degrees from 12 o'clock. |
| `monochrome` | `string \| boolean` | `false` | One hue in shades, darkest on the largest value. `true` uses the accent; a string sets the base color. |
| `height` | `number \| "fill"` | `340` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `valueFormat` | `ValueFormat` |  |  |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` | `false` |  |
| `animate` | `boolean` | `true` |  |
| `initialHidden` | `readonly string[]` |  |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-polarareachart--default)
- [Nightingale Area](/storybook/?path=/story/charts-polarareachart--nightingale-area)
- [With Hole](/storybook/?path=/story/charts-polarareachart--with-hole)
- [Monochrome](/storybook/?path=/story/charts-polarareachart--monochrome)
- [Loading](/storybook/?path=/story/charts-polarareachart--loading)
- [Empty](/storybook/?path=/story/charts-polarareachart--empty)
- [Narrow](/storybook/?path=/story/charts-polarareachart--narrow)

## Source

`packages/ui/src/charts/polar-area-chart/polar-area-chart.tsx`

---

# ProgressUnits

> Segmented progress: a rating of 4.5 of 5 stars with a half star, the steps of a booking, the cells of a battery.

Source: https://ui.jcsoftdev.com/docs/components/progress-units

Segmented progress: a rating of 4.5 of 5 stars with a half star, the steps
of a booking, the cells of a battery. Partial units are clipped exactly;
the row shrinks to fit narrow containers.

## Import

```ts
import { ProgressUnits } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/progress-units`.

## Usage

```tsx
<ProgressUnits
  label="Calificación de Kevin"
  value={4.5}
  max={5}
  count={5}
  variant="icons"
  icon="star"
  size={24}
  gap={0.18}
  showValue
  animate
  loading={false}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` * | `string` |  | Accessible name and data table caption, e.g. "Calificación de Kevin". |
| `value` * | `number` |  |  |
| `max` | `number` | `5` | Value of a full row of units (5 for a five star rating, 100 for a percentage). |
| `count` | `number` | `5` | Number of units drawn. |
| `step` | `number` |  | Rounds the value before drawing, e.g. 0.5 for half stars. Exact partial units by default. |
| `variant` | `"icons" \| "segments"` | `"icons"` | "icons": repeated icons (stars, chairs...); "segments": rounded cells like a battery or steps. |
| `icon` | `UnitIcon` | `"star"` |  |
| `color` | `string` |  | CSS color; overrides `tone`. |
| `tone` | `"danger" \| "neutral" \| "warning" \| "success" \| "accent"` |  | Status color family; the brand tone by default. |
| `size` | `number` | `24` | Largest unit side in pixels (the height of the component). |
| `gap` | `number` | `0.18` | Gap between units, as a fraction of the unit size. |
| `showValue` | `boolean` | `true` | Shows the value after the units ("4.5 / 5"). |
| `valueFormat` | `ValueFormat` |  |  |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` | `false` |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-progressunits--default)
- [Exact partial (4.3)](/storybook/?path=/story/charts-progressunits--exact-partial)
- [Rounded to half stars](/storybook/?path=/story/charts-progressunits--half-steps)
- [Segments (booking steps)](/storybook/?path=/story/charts-progressunits--booking-steps)
- [Segments (capacity cells)](/storybook/?path=/story/charts-progressunits--capacity-cells)
- [Chair icons (chairs taken)](/storybook/?path=/story/charts-progressunits--chairs)
- [Loading](/storybook/?path=/story/charts-progressunits--loading)
- [Narrow](/storybook/?path=/story/charts-progressunits--narrow)

## Source

`packages/ui/src/charts/progress-units/progress-units.tsx`

---

# RadarChart

> Radar (spider) chart: several series over shared spokes, polygon or circular grid, translucent areas, markers and a tooltip that lists every series for the hovered or focused axis.

Source: https://ui.jcsoftdev.com/docs/components/radar-chart

Radar (spider) chart: several series over shared spokes, polygon or
circular grid, translucent areas, markers and a tooltip that lists every
series for the hovered or focused axis.

## Import

```ts
import { RadarChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/radar-chart`.

## Usage

```tsx
<RadarChart
  title="Evaluación de barberos por habilidad"
  axes={skills}
  series={barbers}
  valueFormat="integer"
  levels={4}
  gridShape="polygon"
  fill
  fillOpacity={0.18}
  markers
  showValues
  startAngle={0}
  height={380}
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `description` | `string` |  |  |
| `axes` * | `readonly string[]` |  | One name per spoke (at least 3). |
| `series` * | `readonly ChartSeries[]` |  | One value per axis in each series. |
| `max` | `number` |  | Value at the outer ring. Rounded up from the data by default. |
| `min` | `number` | `0` | Value at the centre. |
| `levels` | `number` | `4` | Number of concentric grid rings. |
| `gridShape` | `"circle" \| "polygon"` | `"polygon"` |  |
| `fill` | `boolean` | `true` | Translucent fill under each series. |
| `fillOpacity` | `number` | `0.18` |  |
| `markers` | `boolean` | `true` |  |
| `showValues` | `boolean` | `true` | Ring values along the first spoke. |
| `startAngle` | `number` | `0` | Rotation of the first spoke, in degrees from 12 o'clock. |
| `height` | `number \| "fill"` | `340` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `valueFormat` | `ValueFormat` |  |  |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` | `false` |  |
| `animate` | `boolean` | `true` |  |
| `initialHidden` | `readonly string[]` |  |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-radarchart--default)
- [Circular Grid](/storybook/?path=/story/charts-radarchart--circular-grid)
- [Single Series](/storybook/?path=/story/charts-radarchart--single-series)
- [Outline Only](/storybook/?path=/story/charts-radarchart--outline-only)
- [Loading](/storybook/?path=/story/charts-radarchart--loading)
- [Empty](/storybook/?path=/story/charts-radarchart--empty)
- [Narrow](/storybook/?path=/story/charts-radarchart--narrow)

## Source

`packages/ui/src/charts/radar-chart/radar-chart.tsx`

---

# RadialBarChart

> Concentric progress rings ("actividad del día"): one ring per series with a track, rounded caps, optional gradient, labels at the start of each ring and a centre readout that foll…

Source: https://ui.jcsoftdev.com/docs/components/radial-bar-chart

Concentric progress rings ("actividad del día"): one ring per series with
a track, rounded caps, optional gradient, labels at the start of each ring
and a centre readout that follows the hovered or focused ring.

## Import

```ts
import { RadialBarChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/radial-bar-chart`.

## Usage

```tsx
<RadialBarChart
  title="Actividad del día"
  data={activity}
  max={100}
  startAngle={0}
  endAngle={270}
  gap={6}
  track
  roundedCaps
  gradient
  height={340}
  centerValue="80%"
  centerLabel="de la meta diaria"
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `description` | `string` |  |  |
| `data` * | `readonly RadialBarDatum[]` |  | Rings from the outside in. |
| `max` | `number` | `100` | Default full-ring value, 100 unless set (a datum can bring its own). |
| `height` | `number \| "fill"` | `320` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `startAngle` | `number` | `0` | Where the rings start and stop, in degrees from 12 o'clock. 0 -> 270 leaves room for ring labels. |
| `endAngle` | `number` | `270` |  |
| `thickness` | `number` |  | Ring thickness in pixels; derived from the size and ring count by default. |
| `gap` | `number` | `6` | Space between rings, in pixels. |
| `track` | `boolean` | `true` | Faint full ring behind each progress ring. |
| `roundedCaps` | `boolean` | `true` |  |
| `gradient` | `boolean` | `true` | Soft light-to-full gradient along each ring. |
| `ringLabels` | `boolean` |  | Name and value at the start of each ring (needs the 12-to-9 o'clock quadrant free). |
| `valueFormat` | `ValueFormat` |  |  |
| `centerValue` | `string` |  | Text in the centre while nothing is hovered. |
| `centerLabel` | `string` |  |  |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` | `false` |  |
| `animate` | `boolean` | `true` |  |
| `initialHidden` | `readonly string[]` |  |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-radialbarchart--default)
- [Full Circle](/storybook/?path=/story/charts-radialbarchart--full-circle)
- [Solid Sharp](/storybook/?path=/story/charts-radialbarchart--solid-sharp)
- [Single Ring](/storybook/?path=/story/charts-radialbarchart--single-ring)
- [Loading](/storybook/?path=/story/charts-radialbarchart--loading)
- [Empty](/storybook/?path=/story/charts-radialbarchart--empty)
- [Narrow](/storybook/?path=/story/charts-radialbarchart--narrow)

## Source

`packages/ui/src/charts/radial-bar-chart/radial-bar-chart.tsx`

---

# RaincloudChart

> Raincloud plot (horizontal): a half violin "cloud" for the shape, a slim box for the summary and the jittered raw observations falling below as "rain", so nothing about the distri…

Source: https://ui.jcsoftdev.com/docs/components/raincloud-chart

Raincloud plot (horizontal): a half violin "cloud" for the shape, a slim
box for the summary and the jittered raw observations falling below as
"rain", so nothing about the distribution is hidden.

## Import

```ts
import { RaincloudChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/raincloud-chart`.

## Usage

```tsx
<RaincloudChart
  title="Tiempo de espera por barbero"
  categories={barbers}
  series={[{ id: "espera", name: "Espera", data: waitMinutes }]}
  valueFormat={minutes}
  valueAxis={{ title: "minutos de espera", min: 0 }}
  rain
  pointRadius={2.5}
  showMean
  grid
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `categories` * | `readonly string[]` |  | One row per category, e.g. barbers or time slots. |
| `series` * | `readonly DistributionSeries[]` |  | `data[i]` holds the raw samples of `categories[i]`. Several series stack inside a row. |
| `valueFormat` | `ValueFormat` |  |  |
| `valueAxis` | `DistributionAxisOptions` |  |  |
| `bandwidth` | `number` |  | Kernel bandwidth in data units; Silverman's rule per cloud by default. |
| `rain` | `boolean` | `true` | Draw the raw observations under the box. |
| `pointRadius` | `number` | `2.5` | Radius of each raw point in pixels. |
| `showMean` | `boolean` | `true` |  |
| `seed` | `number` | `7` | Seed of the vertical jitter, so the rain is stable between renders. |
| `height` | `number \| "fill"` |  | Height of the drawing; grows with the number of rows by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `grid` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `labels` | `Partial<DistributionLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-raincloudchart--default)
- [Without Rain](/storybook/?path=/story/charts-raincloudchart--without-rain)
- [Weekday Vs Saturday](/storybook/?path=/story/charts-raincloudchart--weekday-vs-saturday)
- [Average Ticket](/storybook/?path=/story/charts-raincloudchart--average-ticket)
- [Narrow](/storybook/?path=/story/charts-raincloudchart--narrow)
- [Loading](/storybook/?path=/story/charts-raincloudchart--loading)
- [Empty](/storybook/?path=/story/charts-raincloudchart--empty)

## Source

`packages/ui/src/charts/raincloud-chart/raincloud-chart.tsx`

---

# RangeAreaChart

> Min–max band over time (or categories) with an optional line for the average.

Source: https://ui.jcsoftdev.com/docs/components/range-area-chart

Min–max band over time (or categories) with an optional line for the
average. Several bands overlay each other; the legend toggles them.
Ideal for ranges such as waiting time per day or price floor and ceiling.

## Import

```ts
import { RangeAreaChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/range-area-chart`.

## Usage

```tsx
<RangeAreaChart
  title="Tiempo de espera mínimo y máximo por día"
  categories={days}
  bands={[waitTime]}
  height={300}
  curve="smooth"
  showMean
  grid
  tooltip
  loading={false}
  animate
  minLabel="Mín"
  maxLabel="Máx"
  meanLabel="Prom."
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `categories` * | `readonly XValue[]` |  |  |
| `bands` * | `readonly RangeBand[]` |  |  |
| `title` * | `string` |  | Accessible name of the chart. |
| `description` | `string` |  |  |
| `height` | `number \| "fill"` | `300` | Height of the plot in pixels. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `curve` | `"linear" \| "smooth" \| "step" \| "step-before" \| "step-after"` | `"smooth"` |  |
| `showMean` | `boolean` | `true` | Draw the central line of bands that provide `mean` (default true). |
| `valueFormat` | `ValueFormat` |  |  |
| `xFormat` | `((value: XValue) => string)` |  |  |
| `xScale` | `"time" \| "auto" \| "point"` | `"auto"` | "auto" uses a real time axis when every category is a Date. |
| `yAxis` | `ValueAxisOptions` |  |  |
| `grid` | `boolean` | `true` |  |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `initialHidden` | `readonly string[]` |  |  |
| `minLabel` | `string` | `"Min"` | Words used in the tooltip and the data table. |
| `maxLabel` | `string` | `"Max"` |  |
| `meanLabel` | `string` | `"Mean"` |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-rangeareachart--default)
- [Multiple Bands](/storybook/?path=/story/charts-rangeareachart--multiple-bands)
- [Without Mean](/storybook/?path=/story/charts-rangeareachart--without-mean)
- [Fixed Axis](/storybook/?path=/story/charts-rangeareachart--fixed-axis)
- [By Category](/storybook/?path=/story/charts-rangeareachart--by-category)
- [Loading](/storybook/?path=/story/charts-rangeareachart--loading)
- [Empty](/storybook/?path=/story/charts-rangeareachart--empty)
- [Narrow](/storybook/?path=/story/charts-rangeareachart--narrow)

## Source

`packages/ui/src/charts/range-area-chart/range-area-chart.tsx`

---

# SankeyChart

> Sankey diagram: flows between columns of nodes, band widths proportional to the value.

Source: https://ui.jcsoftdev.com/docs/components/sankey-chart

Sankey diagram: flows between columns of nodes, band widths proportional to
the value. Hover (or keyboard) a node to follow its flows upstream and
downstream, or a link to isolate it; the tooltip gives value and share.

## Import

```ts
import { SankeyChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/sankey-chart`.

## Usage

```tsx
<SankeyChart
  title="Origen de clientes, servicio y medio de pago"
  nodes={nodes}
  links={links}
  columns={["Origen", "Servicio", "Pago"]}
  valueFormat="integer"
  height={400}
  nodePadding={14}
  align="justify"
  iterations={6}
  linkColor="gradient"
  linkOpacity={0.38}
  labelPosition="outside"
  showValues
  tooltip
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the drawing and caption of the data table. |
| `nodes` * | `readonly SankeyNodeInput[]` |  |  |
| `links` * | `readonly SankeyLinkInput[]` |  | Flows between node ids. Links that close a cycle are left out (with a dev warning). |
| `compare` | `readonly SankeyLinkInput[]` |  | Diff view: the flows of a previous period. `links` is then the current period; every band is colored by its change (`--chart-up` / `--chart-down`) with the previous width as a ghost behind it. |
| `pathTracing` | `boolean` |  | Hover or click traces a whole path: a link lights everything upstream of its source and downstream of its target; a click pins it. |
| `particles` | `boolean` |  | Dots travel along the bands (off under `prefers-reduced-motion`). |
| `exportable` | `boolean` | `false` | Show SVG and PNG export buttons above the drawing. |
| `legendItems` | `readonly { id: string; name: string; color: string; }[]` |  | Legend entries below the drawing; the nodes by default (an alluvial lists its categories). |
| `relax` | `boolean` |  | `false` keeps nodes in input order inside their column (see `AlluvialChart`). |
| `columns` | `readonly string[]` |  | Titles drawn above the columns, left to right, e.g. ["Origen", "Servicio", "Pago"]. |
| `height` | `number \| "fill"` | `380` |  |
| `aspectRatio` | `number` |  | Width / height ratio of the drawing; ignored with `"fill"`. |
| `valueFormat` | `ValueFormat` |  |  |
| `nodeWidth` | `number` |  | Thickness of the node bars (wider by default with inside labels). |
| `nodePadding` | `number` |  | Vertical gap between nodes of a column. |
| `align` | `"left" \| "justify"` |  | `justify` puts the final nodes in the last column; `left` keeps each at its depth. |
| `iterations` | `number` |  | Relaxation sweeps of the layout; more untangles more, at a cost. |
| `linkColor` | `"source" \| "target" \| "neutral" \| "gradient"` |  | `gradient` blends source into target; `source`/`target` use one end; `neutral` is grey. |
| `linkOpacity` | `number` |  | Resting opacity of the links (0-1). |
| `labelPosition` | `"outside" \| "inside"` |  | Node labels beside the bars (`outside`) or on wide bars (`inside`). |
| `showValues` | `boolean` |  | Value after each node label. |
| `tooltip` | `boolean` |  |  |
| `animate` | `boolean` |  |  |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<SankeyLabels>` |  |  |
| `onNodeClick` | `((node: SankeyNode) => void)` |  |  |
| `onLinkClick` | `((link: SankeyLink) => void)` |  |  |
| `onRemovedLinks` | `((removed: SankeyGraph["removed"]) => void)` |  | Links the layout left out (cycles, self links, unknown ids, invalid values). |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-sankeychart--default)
- [Source Colored](/storybook/?path=/story/charts-sankeychart--source-colored)
- [Inside Labels](/storybook/?path=/story/charts-sankeychart--inside-labels)
- [Revenue](/storybook/?path=/story/charts-sankeychart--revenue)
- [With Cycle](/storybook/?path=/story/charts-sankeychart--with-cycle)
- [Loading](/storybook/?path=/story/charts-sankeychart--loading)
- [Empty](/storybook/?path=/story/charts-sankeychart--empty)
- [Narrow](/storybook/?path=/story/charts-sankeychart--narrow)
- [Fill Parent](/storybook/?path=/story/charts-sankeychart--fill-parent)
- [Alluvial](/storybook/?path=/story/charts-sankeychart--alluvial)
- [Diff](/storybook/?path=/story/charts-sankeychart--diff)
- [Path Tracing](/storybook/?path=/story/charts-sankeychart--path-tracing)
- [Particles](/storybook/?path=/story/charts-sankeychart--particles)
- [Export](/storybook/?path=/story/charts-sankeychart--export)
- [Chord](/storybook/?path=/story/charts-sankeychart--chord)

## Source

`packages/ui/src/charts/sankey-chart/sankey-chart.tsx`

---

# ScatterChart

> Scatter plot: one dot per observation on two numeric axes, several series, an optional least-squares trend line per series and quadrant annotations.

Source: https://ui.jcsoftdev.com/docs/components/scatter-chart

Scatter plot: one dot per observation on two numeric axes, several series,
an optional least-squares trend line per series and quadrant annotations.

## Import

```ts
import { ScatterChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/scatter-chart`.

## Usage

```tsx
<ScatterChart
  title="Duración del servicio vs. ticket"
  series={[
      { id: "corte", name: "Corte", points: visits(401, 60, 10, 0.75) },
      { id: "combo", name: "Corte + barba", points: visits(402, 45, 22, 0.9) },
    ]}
  xFormat={minutes}
  yFormat="currency"
  xAxis={{ title: "Duración (min)" }}
  yAxis={{ title: "Ticket (S/)" }}
  trendLine={false}
  radius={5}
  height={340}
  grid
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `title` * | `string` |  |  |
| `animate` | `boolean` |  |  |
| `className` | `string` |  |  |
| `grid` | `boolean` |  |  |
| `tooltip` | `boolean` |  |  |
| `series` * | `readonly XYSeries[]` |  |  |
| `height` | `number \| "fill"` |  |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `xFormat` | `ValueFormat` |  |  |
| `yAxis` | `DistributionAxisOptions` |  |  |
| `brush` | `XYBrush` |  | Rectangular brush over the plot (pointer drag plus keyboard). |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<DistributionLabels>` |  |  |
| `radius` | `number` |  | Point radius when there are no sizes (pixels). |
| `yFormat` | `ValueFormat` |  |  |
| `xAxis` | `DistributionAxisOptions` |  |  |
| `trendLine` | `boolean` |  | Least-squares line per series, drawn over its x range. |
| `quadrants` | `QuadrantOptions` |  |  |
| `xType` | `"time" \| "linear"` |  | "time": `x` is epoch milliseconds and the axis shows calendar ticks. |
| `jitter` | `number \| { x?: number; y?: number; }` |  | Deterministic displacement in pixels that separates overlapping points (a number applies to both axes). Tooltips still show the true values. |
| `seed` | `number` |  | Seed of the jitter, so points are stable between renders. |
| `renderer` | `"canvas" \| "svg"` |  | "canvas" paints the marks on a canvas for tens of thousands of points; axes, tooltip and keyboard stay SVG/HTML. Falls back to SVG when points carry images or `shading` is "shaded". |
| `showLabels` | `boolean` |  | Text labels next to (or inside) the points that have a `label`. |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-scatterchart--default)
- [With Trend Lines](/storybook/?path=/story/charts-scatterchart--with-trend-lines)
- [Quadrants](/storybook/?path=/story/charts-scatterchart--quadrants)
- [Datetime](/storybook/?path=/story/charts-scatterchart--datetime)
- [Jitter](/storybook/?path=/story/charts-scatterchart--jitter)
- [With Images](/storybook/?path=/story/charts-scatterchart--with-images)
- [Canvas 50 K](/storybook/?path=/story/charts-scatterchart--canvas-50-k)
- [Narrow](/storybook/?path=/story/charts-scatterchart--narrow)
- [Loading](/storybook/?path=/story/charts-scatterchart--loading)
- [Empty](/storybook/?path=/story/charts-scatterchart--empty)

## Source

`packages/ui/src/charts/scatter-chart/scatter-chart.tsx`

---

# SlopeChart

> Two columns, one line per category: the slope is the change.

Source: https://ui.jcsoftdev.com/docs/components/slope-chart

Two columns, one line per category: the slope is the change. Labels with
values sit on both sides and are nudged apart when values are close, so
every name stays readable.

## Import

```ts
import { SlopeChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/slope-chart`.

## Usage

```tsx
<SlopeChart
  title="Citas por servicio: septiembre contra octubre"
  items={servicios}
  fromLabel="Septiembre"
  toLabel="Octubre"
  colorBy="direction"
  lowerIsBetter={false}
  valueFormat="integer"
  tooltip
  loading={false}
  animate
  deltaLabel="Cambio"
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` * | `readonly SlopeItem[]` |  |  |
| `title` * | `string` |  | Accessible name of the chart. |
| `description` | `string` |  |  |
| `fromLabel` | `string` | `"Before"` | Header of the left column, e.g. "Septiembre". |
| `toLabel` | `string` | `"After"` | Header of the right column, e.g. "Octubre". |
| `colorBy` | `"series" \| "direction"` | `"direction"` | "direction" colors by up, down or flat; "series" uses the palette. |
| `lowerIsBetter` | `boolean` | `false` | With `colorBy="direction"`, going down is the good news (e.g. cancellations). |
| `valueFormat` | `ValueFormat` |  |  |
| `height` | `number \| "fill"` |  | Height of the plot; by default it grows with the number of items. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the chart from the container width. |
| `legend` | `boolean` |  |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `deltaLabel` | `string` | `"Change"` | Word for the change column of the data table and tooltip. |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-slopechart--default)
- [Series Colors](/storybook/?path=/story/charts-slopechart--series-colors)
- [Crowded Labels](/storybook/?path=/story/charts-slopechart--crowded-labels)
- [Revenue](/storybook/?path=/story/charts-slopechart--revenue)
- [Lower Is Better](/storybook/?path=/story/charts-slopechart--lower-is-better)
- [Loading](/storybook/?path=/story/charts-slopechart--loading)
- [Empty](/storybook/?path=/story/charts-slopechart--empty)
- [Narrow](/storybook/?path=/story/charts-slopechart--narrow)

## Source

`packages/ui/src/charts/slope-chart/slope-chart.tsx`

---

# Sparkline

> Word-sized chart for KPI tiles: no axes, no legend.

Source: https://ui.jcsoftdev.com/docs/components/sparkline

Word-sized chart for KPI tiles: no axes, no legend. Hovering shows the
point's value; screen readers get a one-sentence summary (first, last,
minimum and maximum).

## Import

```ts
import { Sparkline } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/sparkline`.

## Usage

```tsx
<Sparkline
  data={salesLast14}
  label="Ventas de los últimos 14 días"
  type="line"
  height={36}
  showLast
  valueFormat="currency"
  categories={days}
  animate
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` * | `readonly (number \| null)[]` |  |  |
| `label` * | `string` |  | Accessible description, e.g. "Ventas de los últimos 14 días". |
| `type` | `"area" \| "line" \| "bar"` | `"line"` |  |
| `color` | `string` |  | CSS color; the brand tone (`accent-word`) by default. |
| `height` | `number \| "fill"` | `36` | Pixels, or "fill" to take the full height of the parent. |
| `width` | `number` |  | Fixed width; fills the container when omitted. |
| `showLast` | `boolean` | `true` | Dot on the last value (lines and areas). |
| `valueFormat` | `ValueFormat` |  | Format of the hovered value and the summary for screen readers. |
| `categories` | `readonly string[]` |  | Optional names of the points, shown next to the hovered value. |
| `highlightIndex` | `number` |  | Index of a bar drawn in full color while the others are muted (bars only). |
| `animate` | `boolean` | `true` |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-sparkline--default)
- [Area](/storybook/?path=/story/charts-sparkline--area)
- [Bars](/storybook/?path=/story/charts-sparkline--bars)
- [Falling Stock](/storybook/?path=/story/charts-sparkline--falling-stock)
- [Inside KPI tiles](/storybook/?path=/story/charts-sparkline--in-kpi-tiles)

## Source

`packages/ui/src/charts/sparkline/sparkline.tsx`

---

# StockChart

> Price chart for long daily series: candles, OHLC bars, a line or an area; a range selector and a navigator to zoom; moving averages, Bollinger bands and VWAP over the price; RSI o…

Source: https://ui.jcsoftdev.com/docs/components/stock-chart

Price chart for long daily series: candles, OHLC bars, a line or an area;
a range selector and a navigator to zoom; moving averages, Bollinger bands
and VWAP over the price; RSI or MACD in a second pane with one crosshair
across both; a last-price tag; comparison series in % change; event flags.
The indicator math lives in `core/indicators.ts`.

## Import

```ts
import { StockChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/stock-chart`.

## Usage

```tsx
<StockChart
  title="Precio de la caja de navajas importadas (S/)"
  data={navajas}
  ranges={[...spanishRanges]}
  defaultRange="6m"
  defaultSeriesType="candle"
  overlays={[
      { type: "sma", period: 20 },
      { type: "ema", period: 50 },
    ]}
  oscillator={{ type: "rsi", period: 14 }}
  valueFormat="currency"
  volumeFormat="integer"
  height={440}
  navigator
  lastPrice
  grid
  legend
  tooltip
  toolbar
  loading={false}
  animate
  texts={spanishTexts}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` * | `readonly StockBar[]` |  | Bars in ascending date order. |
| `title` * | `string` |  | Accessible name of the chart. |
| `description` | `string` |  |  |
| `seriesType` | `"area" \| "line" \| "column" \| "candle" \| "ohlc" \| "heikin-ashi" \| "renko"` |  | Controlled series type. |
| `defaultSeriesType` | `"area" \| "line" \| "column" \| "candle" \| "ohlc" \| "heikin-ashi" \| "renko"` | `"candle"` | Initial series type when uncontrolled, "candle" by default. |
| `onSeriesTypeChange` | `((type: StockSeriesType) => void)` |  |  |
| `seriesTypes` | `readonly StockSeriesType[]` | `SERIES_TYPES` | Types offered in the toolbar; an empty list hides the switch. |
| `renkoBrickSize` | `number` |  | Brick size of the Renko type; the ATR(14) of the data by default. |
| `drawingTools` | `readonly StockTool[]` | `[]` | Tools of the drawing toolbar; none (default) hides it. `DEFAULT_STOCK_TOOLS` has them all. |
| `drawings` | `readonly StockDrawing[]` |  | Controlled drawings. Anchors are moments and prices, so they survive zoom and new data. |
| `defaultDrawings` | `readonly StockDrawing[]` | `[]` |  |
| `onDrawingsChange` | `((drawings: StockDrawing[]) => void)` |  | Called with the full list after a drawing is added or deleted: persist it here. |
| `pinnable` | `boolean` | `false` | Click (or Enter) on a bar pins its tooltip; pin several to compare days. |
| `defaultPinned` | `readonly (number \| Date)[]` | `[]` | Times (ms) of the tooltips pinned at first. |
| `onPinnedChange` | `((times: number[]) => void)` |  |  |
| `onWindowChange` | `((window: StockWindow) => void)` |  | Reports the visible window whenever it or the data changes. |
| `ranges` | `readonly TimeRangePreset[]` | `DEFAULT_STOCK_RANGES` | Range selector buttons; an empty list hides them. |
| `defaultRange` | `string` |  | Id of the preset applied first; the whole series by default. |
| `overlays` | `readonly StockOverlay[]` | `[]` | Indicators over the price: SMA, EMA, Bollinger bands, VWAP. |
| `oscillator` | `StockOscillator` |  | RSI or MACD in a pane under the price, sharing the crosshair. |
| `volume` | `boolean` |  | Volume bars at the bottom of the price pane; shown when the data has volume. |
| `navigator` | `boolean` | `true` | Mini chart of the whole series with a draggable window (default true). |
| `lastPrice` | `boolean` | `true` | Dashed line and tag at the last value (default true). |
| `comparisons` | `readonly StockComparison[]` | `[]` | Other series on the same dates: the chart switches to % change from the first visible bar. |
| `flags` | `readonly StockFlag[]` | `[]` | Event flags pinned above the bars. |
| `name` | `string` |  | Name of the main series in the legend (% mode). |
| `height` | `number \| "fill"` | `420` | Pixels of the drawing (price, oscillator and navigator), 420 by default, or `"fill"`. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the chart from the container width. |
| `valueFormat` | `ValueFormat` |  |  |
| `volumeFormat` | `ValueFormat` | `"compact"` |  |
| `grid` | `boolean` | `true` |  |
| `legend` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `toolbar` | `boolean` | `true` | Toolbar with the range and series-type buttons (default true). |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `texts` | `StockTextsInput` |  |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-stockchart--default)
- [Ohlc Bollinger](/storybook/?path=/story/charts-stockchart--ohlc-bollinger)
- [Line Macd](/storybook/?path=/story/charts-stockchart--line-macd)
- [Area Vwap](/storybook/?path=/story/charts-stockchart--area-vwap)
- [Comparison](/storybook/?path=/story/charts-stockchart--comparison)
- [Flags](/storybook/?path=/story/charts-stockchart--flags)
- [Loading](/storybook/?path=/story/charts-stockchart--loading)
- [Empty](/storybook/?path=/story/charts-stockchart--empty)
- [Narrow](/storybook/?path=/story/charts-stockchart--narrow)
- [Fill Parent](/storybook/?path=/story/charts-stockchart--fill-parent)
- [Heikin Ashi](/storybook/?path=/story/charts-stockchart--heikin-ashi)
- [Renko](/storybook/?path=/story/charts-stockchart--renko)
- [Columns](/storybook/?path=/story/charts-stockchart--columns)
- [Streaming](/storybook/?path=/story/charts-stockchart--streaming)
- [Drawing Tools](/storybook/?path=/story/charts-stockchart--drawing-tools)
- [Range Measure](/storybook/?path=/story/charts-stockchart--range-measure)
- [Pinned Tooltips](/storybook/?path=/story/charts-stockchart--pinned-tooltips)
- [Stats](/storybook/?path=/story/charts-stockchart--stats)

## Source

`packages/ui/src/charts/stock-chart/stock-chart.tsx`

---

# StreamGraph

> Flowing stacked areas around a moving baseline.

Source: https://ui.jcsoftdev.com/docs/components/stream-graph

Flowing stacked areas around a moving baseline. Hover a stream to isolate it
(the others fade, the tooltip shows its value); with the keyboard, Left and
Right move through time and Up and Down switch stream.

## Import

```ts
import { StreamGraph } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/stream-graph`.

## Usage

```tsx
<StreamGraph
  title="Servicios realizados por semana"
  categories={weeks}
  series={services}
  valueFormat="integer"
  height={340}
  offset="wiggle"
  order="inside-out"
  curve="smooth"
  streamLabels
  grid
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `categories` * | `readonly XValue[]` |  |  |
| `series` * | `readonly ChartSeries[]` |  |  |
| `title` * | `string` |  | Accessible name of the chart. |
| `description` | `string` |  |  |
| `height` | `number \| "fill"` | `340` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `offset` | `"zero" \| "wiggle" \| "silhouette" \| "expand"` | `"wiggle"` | Baseline: "wiggle" (default), "silhouette", "zero" (plain stack) or "expand" (100%). |
| `order` | `"none" \| "ascending" \| "inside-out"` | `"inside-out"` | Stacking order; "inside-out" keeps the biggest streams in the middle. |
| `curve` | `"linear" \| "smooth" \| "step" \| "step-before" \| "step-after"` | `"smooth"` |  |
| `streamLabels` | `boolean` | `true` | Names written on the thickest part of each stream (default true). |
| `valueFormat` | `ValueFormat` |  |  |
| `xFormat` | `((value: XValue) => string)` |  |  |
| `xScale` | `"time" \| "auto" \| "point"` | `"auto"` |  |
| `grid` | `boolean` | `true` |  |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `initialHidden` | `readonly string[]` |  |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-streamgraph--default)
- [Silhouette](/storybook/?path=/story/charts-streamgraph--silhouette)
- [Stacked From Zero](/storybook/?path=/story/charts-streamgraph--stacked-from-zero)
- [Share](/storybook/?path=/story/charts-streamgraph--share)
- [Few Streams](/storybook/?path=/story/charts-streamgraph--few-streams)
- [Loading](/storybook/?path=/story/charts-streamgraph--loading)
- [Empty](/storybook/?path=/story/charts-streamgraph--empty)
- [Narrow](/storybook/?path=/story/charts-streamgraph--narrow)

## Source

`packages/ui/src/charts/stream-graph/stream-graph.tsx`

---

# SunburstChart

> Radial partition: the open node in the center, its descendants in rings, each slice proportional to value.

Source: https://ui.jcsoftdev.com/docs/components/sunburst-chart

Radial partition: the open node in the center, its descendants in rings,
each slice proportional to value. Clicking a segment zooms into it with an
animated transition; the center or Escape zooms back out.

## Import

```ts
import { SunburstChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/sunburst-chart`.

## Usage

```tsx
<SunburstChart
  title="Servicios por sede, barbero y servicio"
  data={servicesByBranch}
  valueFormat="integer"
  height={380}
  half={false}
  levels={3}
  drillDown
  breadcrumb
  legend
  tooltip
  centerLabel
  segmentLabels
  gap={1.5}
  sort
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the drawing and caption of the data table. |
| `data` * | `HierarchyDatum` |  | Root of the tree; its name and total sit in the center. |
| `height` | `number \| "fill"` | `360` | Height of the drawing; the disc takes the smaller of width and height. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `valueFormat` | `ValueFormat` |  |  |
| `half` | `boolean` | `false` | Half disc opening upwards (a 180 degree fan) instead of a full circle. |
| `levels` | `number` | `3` | Rings shown around the open node. |
| `drillDown` | `boolean` | `true` | Click a segment to zoom into it, the center to zoom out. |
| `breadcrumb` | `boolean` | `true` |  |
| `legend` | `boolean` | `true` | Read-only legend of the open level's branches. |
| `tooltip` | `boolean` | `true` |  |
| `centerLabel` | `boolean` | `true` | Name and total of the open node in the center. |
| `segmentLabels` | `boolean` | `true` | Labels along the segments where they fit. |
| `gap` | `number` | `1.5` | Gap between segments in pixels (measured at the inner ring). |
| `sort` | `boolean` | `true` |  |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<HierarchyLabels>` |  |  |
| `onFocusChange` | `((node: HierarchyNode) => void)` |  |  |
| `onNodeClick` | `((node: HierarchyNode) => void)` |  | Click on a segment that cannot be opened (a leaf). |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-sunburstchart--default)
- [Two Levels](/storybook/?path=/story/charts-sunburstchart--two-levels)
- [Without Labels](/storybook/?path=/story/charts-sunburstchart--without-labels)
- [Static View](/storybook/?path=/story/charts-sunburstchart--static-view)
- [Drilldown](/storybook/?path=/story/charts-sunburstchart--drilldown)
- [Semi Circle](/storybook/?path=/story/charts-sunburstchart--semi-circle)
- [Semi Circle Narrow](/storybook/?path=/story/charts-sunburstchart--semi-circle-narrow)
- [Loading](/storybook/?path=/story/charts-sunburstchart--loading)
- [Empty](/storybook/?path=/story/charts-sunburstchart--empty)
- [Narrow](/storybook/?path=/story/charts-sunburstchart--narrow)

## Source

`packages/ui/src/charts/sunburst-chart/sunburst-chart.tsx`

---

# TimelineChart

> Gantt-style time ranges: one row per resource, one bar per item.

Source: https://ui.jcsoftdev.com/docs/components/timeline-chart

Gantt-style time ranges: one row per resource, one bar per item. Bars that
overlap inside a row are stacked into lanes, so nothing is hidden. Colors
come from groups (statuses), and an optional marker shows the current time.

## Import

```ts
import { TimelineChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/timeline-chart`.

## Usage

```tsx
<TimelineChart
  title="Agenda de hoy por barbero"
  rows={rows}
  items={citas}
  groups={groups}
  laneHeight={28}
  grid
  tooltip
  loading={false}
  animate
  texts={spanishTexts}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` * | `readonly TimelineRow[]` |  |  |
| `items` * | `readonly TimelineItem[]` |  |  |
| `groups` | `readonly TimelineGroup[]` | `[]` |  |
| `title` * | `string` |  | Accessible name of the chart. |
| `description` | `string` |  |  |
| `domain` | `readonly [number \| Date, number \| Date]` |  | Visible time window; by default the items rounded out to whole hours. |
| `now` | `number \| false \| Date \| "auto"` | `false` | A "now" marker. "auto" uses the current time; false hides it. |
| `height` | `"fill"` |  | By default the height follows the lanes. `"fill"` stretches the lanes to the height of the parent; `aspectRatio` does the same from the width. |
| `aspectRatio` | `number` |  | Width / height ratio; stretches the lanes to fit it. |
| `laneHeight` | `number` | `28` | Height of one lane (a bar) in pixels, 28 by default (the minimum when stretching is 14). |
| `grid` | `boolean` | `true` |  |
| `legend` | `boolean` |  |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `initialHidden` | `readonly string[]` |  |  |
| `texts` | `Partial<TimelineTexts>` |  |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-timelinechart--default)
- [Without Now Marker](/storybook/?path=/story/charts-timelinechart--without-now-marker)
- [Fixed Business Hours](/storybook/?path=/story/charts-timelinechart--fixed-business-hours)
- [Compact](/storybook/?path=/story/charts-timelinechart--compact)
- [Now = current time](/storybook/?path=/story/charts-timelinechart--live-now)
- [Loading](/storybook/?path=/story/charts-timelinechart--loading)
- [Empty](/storybook/?path=/story/charts-timelinechart--empty)
- [Narrow](/storybook/?path=/story/charts-timelinechart--narrow)
- [Fill Parent](/storybook/?path=/story/charts-timelinechart--fill-parent)

## Source

`packages/ui/src/charts/timeline-chart/timeline-chart.tsx`

---

# TreeCard

> Default node template: a card with a color rail, an avatar (image or initials), the name, a subtitle and an optional badge.

Source: https://ui.jcsoftdev.com/docs/components/tree-card

Default node template: a card with a color rail, an avatar (image or
initials), the name, a subtitle and an optional badge. Fills its box.

## Import

```ts
import { TreeCard } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/tree-chart`.

## Usage

```tsx
<TreeCard node={root} state={idle} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `node` * | `TreeChartNode` |  |  |
| `state` * | `TreeNodeState` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-treecard--default)
- [Highlighted](/storybook/?path=/story/charts-primitives-treecard--highlighted)
- [Dimmed](/storybook/?path=/story/charts-primitives-treecard--dimmed)
- [Name Only](/storybook/?path=/story/charts-primitives-treecard--name-only)
- [With Photo](/storybook/?path=/story/charts-primitives-treecard--with-photo)

## Source

`packages/ui/src/charts/tree-chart/tree-card.tsx`

---

# TreeChart

> Org chart / hierarchy tree: tidy layout in four directions, card templates, curved, step or straight edges, animated expand/collapse, pan and zoom, and the path to the root highli…

Source: https://ui.jcsoftdev.com/docs/components/tree-chart

Org chart / hierarchy tree: tidy layout in four directions, card templates,
curved, step or straight edges, animated expand/collapse, pan and zoom,
and the path to the root highlighted on hover or keyboard focus.

## Import

```ts
import { TreeChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/tree-chart`.

## Usage

```tsx
<TreeChart
  title="Equipo de la barbería"
  data={team}
  direction="top"
  edgeStyle="curved"
  height={520}
  nodeWidth={196}
  nodeHeight={64}
  siblingGap={20}
  levelGap={56}
  collapsible
  highlightPath
  controls
  wheelZoom="modifier"
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the drawing and caption of the data table. |
| `data` * | `TreeChartDatum \| null` |  | Root of the tree; `null` shows the empty state. |
| `layout` | `"tidy" \| "radial" \| "dendrogram"` |  | `tidy` (default) is the org-chart layout; `radial` puts the root in the centre with one ring per level; `dendrogram` aligns every leaf on the last level. The last two default to compact chips. |
| `direction` | `"top" \| "bottom" \| "left" \| "right"` |  | Where the root sits: `top` (default), `bottom`, `left` or `right`. Ignored by `radial`. |
| `edgeStyle` | `"step" \| "curved" \| "straight"` |  |  |
| `height` | `number \| "fill"` | `480` | Drawing height in pixels, or `"fill"` to take the parent's height. |
| `aspectRatio` | `number` |  | Width / height ratio of the drawing; ignored with `"fill"`. |
| `nodeWidth` | `number` |  | Size of every node box (the card template fills it). |
| `nodeHeight` | `number` |  |  |
| `siblingGap` | `number` |  | Gap between neighbouring boxes of one level. |
| `levelGap` | `number` |  | Gap between levels. |
| `initialDepth` | `number` |  | Depth (root = 0) from which nodes start collapsed: `2` shows the root, its children and theirs. |
| `collapsible` | `boolean` |  | Show the expand/collapse buttons (Enter still toggles from the keyboard). |
| `highlightPath` | `boolean` |  | Highlight the path to the root of the hovered or keyboard-active node. |
| `edgeColor` | `"neutral" \| "depth" \| "branch"` |  | Edge colors: `neutral` (default), by `depth` or by top-level `branch`. |
| `searchable` | `boolean` |  | Search box over the drawing: matches are ringed, Enter steps through them and pans to each. |
| `selectable` | `boolean` |  | Clicking a node selects it and keeps its path to the root lit. |
| `selectedId` | `string \| null` |  | Controlled selection (a node id), `null` for none. |
| `defaultSelectedId` | `string \| null` |  |  |
| `onSelect` | `((node: TreeChartNode \| null) => void)` |  |  |
| `showCounts` | `boolean` |  | Show how many nodes hang below each one. |
| `groupLeaves` | `number` |  | Fold nodes with at least this many leaf children into one expandable group node. |
| `loadChildren` | `((node: TreeChartNode) => Promise<readonly TreeChartDatum[]>)` |  | Fetches the children of a `lazy` node the first time it is expanded; a spinner shows meanwhile. Resolve with the child data (an empty array makes the node a leaf). |
| `onLoadError` | `((node: TreeChartNode, error: unknown) => void)` |  |  |
| `fit` | `"auto" \| "contain" \| "readable"` |  | Initial view. `auto` (default) shows the whole tree and, when that would shrink the cards below a readable size (narrow containers), centres the root at a readable scale so you pan to the rest. `contain` always fits the whole tree; `readable` always keeps car… |
| `controls` | `boolean` |  | Zoom buttons over the drawing. |
| `wheelZoom` | `"off" \| "always" \| "modifier"` |  | See `usePanZoom`: wheel zoom only with Ctrl/⌘ (default), always, or off. |
| `minZoom` | `number` |  |  |
| `maxZoom` | `number` |  |  |
| `renderNode` | `((node: TreeChartNode, state: TreeNodeState) => ReactNode)` |  | Custom node template; receives the node and its state, fills the node box. |
| `animate` | `boolean` |  |  |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<TreeLabels>` |  |  |
| `onNodeClick` | `((node: TreeChartNode) => void)` |  |  |
| `onToggle` | `((node: TreeChartNode, expanded: boolean) => void)` |  | Called after a node is expanded (`true`) or collapsed (`false`). |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-treechart--default)
- [Left To Right](/storybook/?path=/story/charts-treechart--left-to-right)
- [Bottom To Top](/storybook/?path=/story/charts-treechart--bottom-to-top)
- [Right To Left](/storybook/?path=/story/charts-treechart--right-to-left)
- [Expand Collapse](/storybook/?path=/story/charts-treechart--expand-collapse)
- [Custom Template](/storybook/?path=/story/charts-treechart--custom-template)
- [Loading](/storybook/?path=/story/charts-treechart--loading)
- [Empty](/storybook/?path=/story/charts-treechart--empty)
- [Narrow](/storybook/?path=/story/charts-treechart--narrow)
- [Fill Parent](/storybook/?path=/story/charts-treechart--fill-parent)
- [Radial](/storybook/?path=/story/charts-treechart--radial)
- [Dendrogram](/storybook/?path=/story/charts-treechart--dendrogram)
- [Search](/storybook/?path=/story/charts-treechart--search)
- [Badges](/storybook/?path=/story/charts-treechart--badges)
- [Grouped Leaves](/storybook/?path=/story/charts-treechart--grouped-leaves)
- [Lazy Children](/storybook/?path=/story/charts-treechart--lazy-children)
- [Edge Colors](/storybook/?path=/story/charts-treechart--edge-colors)
- [Edge Colors By Depth](/storybook/?path=/story/charts-treechart--edge-colors-by-depth)
- [Dynamic Direction](/storybook/?path=/story/charts-treechart--dynamic-direction)
- [Dark](/storybook/?path=/story/charts-treechart--dark)
- [Radial Narrow](/storybook/?path=/story/charts-treechart--radial-narrow)

## Source

`packages/ui/src/charts/tree-chart/tree-chart.tsx`

---

# TreeChip

> Compact node template for the radial and dendrogram layouts: a pill with a color dot, the name and, optionally, the descendant count.

Source: https://ui.jcsoftdev.com/docs/components/tree-chip

Compact node template for the radial and dendrogram layouts: a pill with a
color dot, the name and, optionally, the descendant count.

## Import

```ts
import { TreeChip } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/tree-chart`.

## Usage

```tsx
<TreeChip node={root} state={idle} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `node` * | `TreeChartNode` |  |  |
| `state` * | `TreeNodeState` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-treechip--default)
- [Highlighted](/storybook/?path=/story/charts-primitives-treechip--highlighted)
- [Without Count](/storybook/?path=/story/charts-primitives-treechip--without-count)

## Source

`packages/ui/src/charts/tree-chart/tree-card.tsx`

---

# TreemapChart

> Squarified treemap: areas proportional to value, nested groups with a header band, click a group to open it (breadcrumb to go back).

Source: https://ui.jcsoftdev.com/docs/components/treemap-chart

Squarified treemap: areas proportional to value, nested groups with a
header band, click a group to open it (breadcrumb to go back). Each branch
wears one palette hue; its children are spread over lighter and darker
tints of it. Labels only show where they fit.

## Import

```ts
import { TreemapChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/treemap-chart`.

## Usage

```tsx
<TreemapChart
  title="Ventas por categoría y producto"
  data={salesByCategory}
  valueFormat="currency"
  height={380}
  depth={2}
  drillDown
  breadcrumb
  legend
  tooltip
  gap={3}
  radius={6}
  sort
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the drawing and caption of the data table. |
| `data` * | `HierarchyDatum` |  | Root of the tree; its name is the first breadcrumb item. |
| `height` | `number \| "fill"` | `360` | Height of the drawing in pixels. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `valueFormat` | `ValueFormat` |  |  |
| `depth` | `number` | `2` | Levels drawn at once below the open node; deeper ones appear after drilling. |
| `drillDown` | `boolean` | `true` | Click (or Enter) on a group opens it. |
| `breadcrumb` | `boolean` | `true` | Path of the open node above the drawing. |
| `legend` | `boolean` | `true` | Read-only legend of the open level's branches. |
| `tooltip` | `boolean` | `true` |  |
| `gap` | `number` | `3` | Gap between cells in pixels. |
| `radius` | `number` | `6` | Corner radius of the cells. |
| `sort` | `boolean` | `true` | Largest first (default) or data order. |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<HierarchyLabels>` |  |  |
| `onFocusChange` | `((node: HierarchyNode) => void)` |  | Called with the open node after drilling in or out. |
| `onNodeClick` | `((node: HierarchyNode) => void)` |  | Click on a cell that cannot be opened (a leaf). |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-treemapchart--default)
- [Top Level](/storybook/?path=/story/charts-treemapchart--top-level)
- [Nested](/storybook/?path=/story/charts-treemapchart--nested)
- [Drilldown](/storybook/?path=/story/charts-treemapchart--drilldown)
- [Data Order](/storybook/?path=/story/charts-treemapchart--data-order)
- [Without Legend](/storybook/?path=/story/charts-treemapchart--without-legend)
- [Loading](/storybook/?path=/story/charts-treemapchart--loading)
- [Empty](/storybook/?path=/story/charts-treemapchart--empty)
- [Narrow](/storybook/?path=/story/charts-treemapchart--narrow)

## Source

`packages/ui/src/charts/treemap-chart/treemap-chart.tsx`

---

# UnitGlyph

> One icon of a unit chart, centered in a square cell.

Source: https://ui.jcsoftdev.com/docs/components/unit-glyph

One icon of a unit chart, centered in a square cell. A partial unit draws
the track silhouette and clips the colored copy, so 0.6 of a person is
exactly 60% of its width. The outer group carries `data-unit` and a
fill-box origin, so entry animations can scale it in place.

## Import

```ts
import { UnitGlyph } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = { render: (args) => <GlyphRow {...args} /> };
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `shape` * | `ResolvedUnitShape` |  |  |
| `x` * | `number` |  | Top-left corner of the square cell, in pixels. |
| `y` * | `number` |  |  |
| `size` * | `number` |  | Side of the square cell. |
| `fill` * | `number` |  | 0 to 1: how much of the unit is filled (the rest shows the track). |
| `color` * | `string` |  |  |
| `track` | `boolean` | `true` | Draw the unfilled part in the track color. |
| `clipId` * | `string` |  | Unique id for the clip of a partial unit. |
| `direction` | `"up" \| "right"` | `"right"` | Partial units fill left to right ("right") or bottom to top ("up"). |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-unitglyph--default)
- [Fills Up](/storybook/?path=/story/charts-primitives-unitglyph--fills-up)
- [Scissors](/storybook/?path=/story/charts-primitives-unitglyph--scissors)
- [Without Track](/storybook/?path=/story/charts-primitives-unitglyph--without-track)

## Source

`packages/ui/src/charts/core/unit-glyph.tsx`

---

# ViolinChart

> Violin plot: a Gaussian kernel density mirrored around each category axis, with an optional inner box or quartile lines.

Source: https://ui.jcsoftdev.com/docs/components/violin-chart

Violin plot: a Gaussian kernel density mirrored around each category axis,
with an optional inner box or quartile lines. Two series can share one
split violin per category to compare them side by side.

## Import

```ts
import { ViolinChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/violin-chart`.

## Usage

```tsx
<ViolinChart
  title="Duración por tipo de servicio"
  categories={services}
  series={[{ id: "duracion", name: "Duración", data: durations }]}
  valueFormat={minutes}
  valueAxis={{ title: "min" }}
  orientation="vertical"
  inner="box"
  split={false}
  scale="width"
  height={340}
  grid
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `categories` * | `readonly string[]` |  |  |
| `series` * | `readonly DistributionSeries[]` |  | `data[i]` holds the raw samples of `categories[i]`. |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` |  |
| `valueFormat` | `ValueFormat` |  |  |
| `valueAxis` | `DistributionAxisOptions` |  |  |
| `inner` | `"none" \| "box" \| "quartiles"` | `"box"` | What is drawn inside each violin: a slim box, quartile lines or nothing. |
| `split` | `boolean` | `false` | Two series share one violin per category: the first on the left (top when horizontal), the second on the right. Ignored unless exactly two series are visible. |
| `bandwidth` | `number` |  | Kernel bandwidth in data units; Silverman's rule per violin by default. |
| `scale` | `"area" \| "width"` | `"width"` | "width": every violin uses its full width (shapes compare, sizes do not). "area": one density scale for all, so a wider violin means a denser peak. |
| `showPoints` | `boolean` | `false` | Every raw observation as a dot inside the violin, spread by its density. |
| `jitter` | `number` | `0.8` | Share (0-1) of the local violin width the dots spread over. |
| `pointColor` | `"value" \| "series"` | `"series"` | "value" grades each dot from pale to full colour across the value range. |
| `seed` | `number` | `11` | Seed of the jitter, so the dots are stable between renders. |
| `height` | `number \| "fill"` | `340` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `grid` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `labels` | `Partial<DistributionLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-violinchart--default)
- [Quartiles](/storybook/?path=/story/charts-violinchart--quartiles)
- [Horizontal](/storybook/?path=/story/charts-violinchart--horizontal)
- [Split](/storybook/?path=/story/charts-violinchart--split)
- [Grouped Side By Side](/storybook/?path=/story/charts-violinchart--grouped-side-by-side)
- [Waiting Times](/storybook/?path=/story/charts-violinchart--waiting-times)
- [With Points](/storybook/?path=/story/charts-violinchart--with-points)
- [Colour Graded Jitter](/storybook/?path=/story/charts-violinchart--colour-graded-jitter)
- [Narrow](/storybook/?path=/story/charts-violinchart--narrow)
- [Loading](/storybook/?path=/story/charts-violinchart--loading)
- [Empty](/storybook/?path=/story/charts-violinchart--empty)

## Source

`packages/ui/src/charts/violin-chart/violin-chart.tsx`

---

# WaffleChart

> Proportions as a grid of cells (10 x 10 by default, so one cell is 1%).

Source: https://ui.jcsoftdev.com/docs/components/waffle-chart

Proportions as a grid of cells (10 x 10 by default, so one cell is 1%).
Cells are shared with the largest remainder method, so they always add up.
Hovering, focusing a legend item or moving with the arrows highlights one
category; hidden categories leave their cells empty.

## Import

```ts
import { WaffleChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/waffle-chart`.

## Usage

```tsx
<WaffleChart
  title="Pagos del mes por medio"
  data={paymentMethods}
  rows={10}
  columns={10}
  cellShape="rounded"
  order="row"
  gap={0.14}
  height={260}
  valueFormat="integer"
  legend
  tooltip
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `description` | `string` |  |  |
| `data` * | `readonly Omit<UnitCategory, "icon">[]` |  |  |
| `rows` | `number` | `10` |  |
| `columns` | `number` | `10` |  |
| `total` | `number` |  | What the whole grid stands for. By default the categories fill every cell; with a larger `total` the rest stays empty (62 of 100 chairs). |
| `cellShape` | `"circle" \| "square" \| "rounded"` | `"rounded"` |  |
| `order` | `"row" \| "column"` | `"row"` | "row": left to right from the top; "column": bottom to top from the left. |
| `gap` | `number` | `0.14` | Gap between cells, as a fraction of the cell size. |
| `height` | `number \| "fill"` | `260` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `valueFormat` | `ValueFormat` | `"integer"` |  |
| `legend` | `boolean \| "top" \| "bottom"` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `animate` | `boolean` | `true` |  |
| `loading` | `boolean` | `false` |  |
| `initialHidden` | `readonly string[]` |  |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-wafflechart--default)
- [Squares](/storybook/?path=/story/charts-wafflechart--squares)
- [Circles](/storybook/?path=/story/charts-wafflechart--circles)
- [Part of a total (occupancy)](/storybook/?path=/story/charts-wafflechart--part-of-total)
- [Wide grid (5 x 20)](/storybook/?path=/story/charts-wafflechart--wide)
- [Small Multiples](/storybook/?path=/story/charts-wafflechart--small-multiples)
- [Small Multiples Narrow](/storybook/?path=/story/charts-wafflechart--small-multiples-narrow)
- [Loading](/storybook/?path=/story/charts-wafflechart--loading)
- [Empty](/storybook/?path=/story/charts-wafflechart--empty)
- [Narrow](/storybook/?path=/story/charts-wafflechart--narrow)

## Source

`packages/ui/src/charts/waffle-chart/waffle-chart.tsx`

---

# WaterfallChart

> Bridge from a start value to a total: increases and decreases float on the running total, subtotals and totals stand on the baseline, and dashed connectors carry the eye from one …

Source: https://ui.jcsoftdev.com/docs/components/waterfall-chart

Bridge from a start value to a total: increases and decreases float on the
running total, subtotals and totals stand on the baseline, and dashed
connectors carry the eye from one step to the next.

## Import

```ts
import { WaterfallChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/waterfall-chart`.

## Usage

```tsx
<WaterfallChart
  title="Caja del día: de la apertura al cierre"
  steps={cajaDelDia}
  valueFormat="currency"
  height={320}
  connectors
  dataLabels
  grid
  legend
  tooltip
  loading={false}
  animate
  increaseLabel="Ingreso"
  decreaseLabel="Egreso"
  totalLabel="Saldo"
  runningLabel="Acumulado"
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` * | `readonly WaterfallStep[]` |  |  |
| `title` * | `string` |  | Accessible name of the chart. |
| `description` | `string` |  |  |
| `height` | `number \| "fill"` | `320` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `valueFormat` | `ValueFormat` |  |  |
| `yAxis` | `ValueAxisOptions` |  |  |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | "horizontal" lays the steps top to bottom and the value axis left to right. |
| `connectors` | `boolean` | `true` | Dashed line from each bar to the next (default true). |
| `dataLabels` | `boolean` | `true` | Values written above the bars (default true). |
| `grid` | `boolean` | `true` |  |
| `legend` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `increaseLabel` | `string` | `"Increase"` | Words for the legend, the tooltip and the table. |
| `decreaseLabel` | `string` | `"Decrease"` |  |
| `totalLabel` | `string` | `"Total"` |  |
| `runningLabel` | `string` | `"Running total"` |  |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-waterfallchart--default)
- [Without Connectors](/storybook/?path=/story/charts-waterfallchart--without-connectors)
- [Negative Balance](/storybook/?path=/story/charts-waterfallchart--negative-balance)
- [Horizontal](/storybook/?path=/story/charts-waterfallchart--horizontal)
- [Loading](/storybook/?path=/story/charts-waterfallchart--loading)
- [Empty](/storybook/?path=/story/charts-waterfallchart--empty)
- [Narrow](/storybook/?path=/story/charts-waterfallchart--narrow)
- [Fill Parent](/storybook/?path=/story/charts-waterfallchart--fill-parent)

## Source

`packages/ui/src/charts/waterfall-chart/waterfall-chart.tsx`

---

# XYAxes

> Gridlines in both directions and the x/y axes of an `xyLayout`.

Source: https://ui.jcsoftdev.com/docs/components/xy-axes

Gridlines in both directions and the x/y axes of an `xyLayout`.

## Import

```ts
import { XYAxes } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => <AxesFrame xTitle={args.xTitle} yTitle={args.yTitle} grid={args.grid} />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `layout` * | `XYLayout` |  |  |
| `xTitle` | `string` |  |  |
| `yTitle` | `string` |  |  |
| `grid` | `boolean` | `true` |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-xyaxes--default)
- [Without Grid](/storybook/?path=/story/charts-primitives-xyaxes--without-grid)
- [Without Titles](/storybook/?path=/story/charts-primitives-xyaxes--without-titles)

## Source

`packages/ui/src/charts/core/distribution/marks.tsx`

---

# XYPointChart

> Shared engine of `ScatterChart` and `BubbleChart`: two continuous axes, multi-series points, optional bubbles, trend lines and quadrants.

Source: https://ui.jcsoftdev.com/docs/components/xy-point-chart

Shared engine of `ScatterChart` and `BubbleChart`: two continuous axes,
multi-series points, optional bubbles, trend lines and quadrants.

## Import

```ts
import { XYPointChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
<XYPointChart
  title="Duración del servicio vs. ticket"
  series={[
      { id: "corte", name: "Corte", points: visits(401, 40, 10, 0.75) },
      { id: "combo", name: "Corte + barba", points: visits(402, 30, 22, 0.9) },
    ]}
  yFormat="currency"
  xAxis={{ title: "Duración (min)" }}
  yAxis={{ title: "Ticket (S/)" }}
  trendLine={false}
  sized={false}
  radius={5}
  height={320}
  grid
  tooltip
  loading={false}
  animate
  labels={labels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `series` * | `readonly XYSeries[]` |  |  |
| `xFormat` | `ValueFormat` |  |  |
| `yFormat` | `ValueFormat` |  |  |
| `sizeFormat` | `ValueFormat` |  |  |
| `xAxis` | `DistributionAxisOptions` |  |  |
| `yAxis` | `DistributionAxisOptions` |  |  |
| `trendLine` | `boolean` | `false` | Least-squares line per series, drawn over its x range. |
| `quadrants` | `QuadrantOptions` |  |  |
| `radius` | `number` | `5` | Point radius when there are no sizes (pixels). |
| `sized` | `boolean` | `false` | Bubble mode: radius from `size`, area-proportional, the largest gets `sizeRange[1]`. |
| `sizeRange` | `readonly [number, number]` | `[4, 30]` |  |
| `xType` | `"time" \| "linear"` | `"linear"` | "time": `x` is epoch milliseconds and the axis shows calendar ticks. |
| `jitter` | `number \| { x?: number; y?: number; }` |  | Deterministic displacement in pixels that separates overlapping points (a number applies to both axes). Tooltips still show the true values. |
| `seed` | `number` | `17` | Seed of the jitter, so points are stable between renders. |
| `renderer` | `"canvas" \| "svg"` | `"svg"` | "canvas" paints the marks on a canvas for tens of thousands of points; axes, tooltip and keyboard stay SVG/HTML. Falls back to SVG when points carry images or `shading` is "shaded". |
| `brush` | `XYBrush` |  | Rectangular brush over the plot (pointer drag plus keyboard). |
| `shading` | `"flat" \| "shaded"` | `"flat"` | "shaded" fills bubbles with an off-centre radial gradient so they read as spheres. |
| `showLabels` | `boolean` | `false` | Text labels next to (or inside) the points that have a `label`. |
| `sizeLegend` | `boolean` | `sized` | Reference circles explaining the bubble sizes, under the plot. |
| `height` | `number \| "fill"` | `340` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `grid` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `labels` | `Partial<DistributionLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-xypointchart--default)
- [With Trend Line](/storybook/?path=/story/charts-primitives-xypointchart--with-trend-line)
- [Bubbles](/storybook/?path=/story/charts-primitives-xypointchart--bubbles)
- [Quadrants](/storybook/?path=/story/charts-primitives-xypointchart--quadrants)
- [Loading](/storybook/?path=/story/charts-primitives-xypointchart--loading)
- [Empty](/storybook/?path=/story/charts-primitives-xypointchart--empty)

## Source

`packages/ui/src/charts/core/distribution/xy-points.tsx`

---

# ActionBar

> Floating toolbar for bulk actions on a selection.

Source: https://ui.jcsoftdev.com/docs/components/action-bar

Floating toolbar for bulk actions on a selection. Announces the count politely.

## Import

```ts
import { ActionBar } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/action-bar`.

## Usage

```tsx
export const Default: Story = { render: () => <Demo width="32rem" /> };
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `selectedCount` * | `number` |  | Number of selected items. The bar renders nothing while it is 0. |
| `noun` | `[singular: string, plural: string]` | `["seleccionado", "seleccionados"]` | Singular and plural noun for the live count, e.g. ["cita", "citas"]. |
| `onClear` | `(() => void)` |  | Clears the selection (close button and Escape). |
| `children` | `ReactNode` |  | Bulk actions, usually Buttons. |
| `position` | `"absolute" \| "fixed" \| "static"` | `"absolute"` | `fixed` floats over the viewport; `absolute` floats inside the nearest positioned ancestor (a card, a table wrapper); `static` renders inline. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-actionbar--default)
- [Narrow](/storybook/?path=/story/containers-actionbar--narrow)
- [Brutal Preset](/storybook/?path=/story/containers-actionbar--brutal-preset)
- [Glass Preset](/storybook/?path=/story/containers-actionbar--glass-preset)

## Source

`packages/ui/src/containers/action-bar/action-bar.tsx`

---

# Banner

> `Banner` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/banner

`Banner` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { Banner } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/banner`.

## Usage

```tsx
<Banner tone="info" icon={<Info className="size-4" />}>
  Hoy la barbería abre una hora más tarde, a las 10:00.
</Banner>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"danger" \| "warning" \| "success" \| "info"` | `"info"` |  |
| `icon` | `ReactNode` |  | Decorative icon on the left; marked `aria-hidden`. |
| `action` | `ReactNode` |  | Actions on the right, e.g. a retry button. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-banner--default)
- [Success](/storybook/?path=/story/containers-banner--success)
- [Warning](/storybook/?path=/story/containers-banner--warning)
- [Danger](/storybook/?path=/story/containers-banner--danger)
- [With Action](/storybook/?path=/story/containers-banner--with-action)
- [Without Icon](/storybook/?path=/story/containers-banner--without-icon)
- [Narrow](/storybook/?path=/story/containers-banner--narrow)

## Source

`packages/ui/src/containers/banner/banner.tsx`

---

# Card

> `Card` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/card

`Card` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { Card } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/card`.

## Usage

```tsx
<Card>
  <>
          <CardHeader>
            <h3 className="m-0 font-semibold text-[14px]">Resumen del día</h3>
          </CardHeader>
          <CardBody>
            <p className="m-0 text-ink-2 text-[13px]">
              12 citas atendidas, S/ 840 en ingresos y 2 clientes nuevos.
            </p>
          </CardBody>
          <CardFooter>Actualizado hace 5 min</CardFooter>
        </>
</Card>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-card--default)
- [Body Only](/storybook/?path=/story/containers-card--body-only)
- [With Actions](/storybook/?path=/story/containers-card--with-actions)

## Source

`packages/ui/src/containers/card/card.tsx`

---

# CardBody

> `CardBody` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/card-body

`CardBody` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { CardBody } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/card`.

## Usage

```tsx
<CardBody>
  <>
          <CardHeader>
            <h3 className="m-0 font-semibold text-[14px]">Resumen del día</h3>
          </CardHeader>
          <CardBody>
            <p className="m-0 text-ink-2 text-[13px]">
              12 citas atendidas, S/ 840 en ingresos y 2 clientes nuevos.
            </p>
          </CardBody>
          <CardFooter>Actualizado hace 5 min</CardFooter>
        </>
</CardBody>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-card--default)
- [Body Only](/storybook/?path=/story/containers-card--body-only)
- [With Actions](/storybook/?path=/story/containers-card--with-actions)

## Source

`packages/ui/src/containers/card/card.tsx`

---

# CardFooter

> `CardFooter` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/card-footer

`CardFooter` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { CardFooter } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/card`.

## Usage

```tsx
<CardFooter>
  <>
          <CardHeader>
            <h3 className="m-0 font-semibold text-[14px]">Resumen del día</h3>
          </CardHeader>
          <CardBody>
            <p className="m-0 text-ink-2 text-[13px]">
              12 citas atendidas, S/ 840 en ingresos y 2 clientes nuevos.
            </p>
          </CardBody>
          <CardFooter>Actualizado hace 5 min</CardFooter>
        </>
</CardFooter>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-card--default)
- [Body Only](/storybook/?path=/story/containers-card--body-only)
- [With Actions](/storybook/?path=/story/containers-card--with-actions)

## Source

`packages/ui/src/containers/card/card.tsx`

---

# CardHeader

> `CardHeader` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/card-header

`CardHeader` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { CardHeader } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/card`.

## Usage

```tsx
<CardHeader>
  <>
          <CardHeader>
            <h3 className="m-0 font-semibold text-[14px]">Resumen del día</h3>
          </CardHeader>
          <CardBody>
            <p className="m-0 text-ink-2 text-[13px]">
              12 citas atendidas, S/ 840 en ingresos y 2 clientes nuevos.
            </p>
          </CardBody>
          <CardFooter>Actualizado hace 5 min</CardFooter>
        </>
</CardHeader>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-card--default)
- [Body Only](/storybook/?path=/story/containers-card--body-only)
- [With Actions](/storybook/?path=/story/containers-card--with-actions)

## Source

`packages/ui/src/containers/card/card.tsx`

---

# Carousel

> Scroll-snap carousel.

Source: https://ui.jcsoftdev.com/docs/components/carousel

Scroll-snap carousel. Native scrolling and swipe work with no JS; buttons, dots, arrow keys
and optional autoplay are layered on top. Slides per view follow the container width.

## Import

```ts
import { Carousel } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/carousel`.

## Usage

```tsx
<Carousel
  label="Servicios destacados"
  loop={false}
  autoplay={false}
  showDots
  showArrows
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` * | `ReactNode` |  |  |
| `label` * | `string` |  | Accessible name of the carousel. |
| `slideClassName` | `string` | `"basis-full @lg/carousel:basis-1/2 @3xl/carousel:basis-1/3"` | Classes for each slide's width. Default: 1 per view, 2 from 32rem, 3 from 48rem. |
| `loop` | `boolean` | `false` | Wrap around at the ends. |
| `autoplay` | `number \| boolean` | `false` | Opt-in autoplay: interval in ms (true = 5000). Never runs under `prefers-reduced-motion`. |
| `showDots` | `boolean` | `true` |  |
| `showArrows` | `boolean` | `true` |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-carousel--default)
- [Autoplay](/storybook/?path=/story/containers-carousel--autoplay)
- [Narrow](/storybook/?path=/story/containers-carousel--narrow)
- [Brutal Preset](/storybook/?path=/story/containers-carousel--brutal-preset)
- [Glass Preset](/storybook/?path=/story/containers-carousel--glass-preset)

## Source

`packages/ui/src/containers/carousel/carousel.tsx`

---

# Cell

> Settings-list row with a ready-made control.

Source: https://ui.jcsoftdev.com/docs/components/cell

Settings-list row with a ready-made control. It extends `SettingsRow` (same layout, divider and
wrapping) and fills its `control` slot with a switch, native select, slider or color picker, wiring
the row title as the control's accessible name.

## Import

```ts
import { Cell } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/cell`.

## Usage

```tsx
<Cell
  variant="switch"
  title="Recordatorio por WhatsApp"
  description="Se envía al cliente 2 horas antes de la cita."
  defaultChecked
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` * | `"select" \| "switch" \| "color" \| "slider"` |  |  |
| `defaultChecked` | `boolean` |  |  |
| `disabled` | `boolean` |  |  |
| `title` * | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `titleId` | `string` |  | Id for the title element, so the control can reference it with `aria-labelledby`. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-cell--default)
- [Select](/storybook/?path=/story/containers-cell--select)
- [Slider](/storybook/?path=/story/containers-cell--slider)
- [Color](/storybook/?path=/story/containers-cell--color)
- [List](/storybook/?path=/story/containers-cell--list)
- [Narrow](/storybook/?path=/story/containers-cell--narrow)
- [Brutal Preset](/storybook/?path=/story/containers-cell--brutal-preset)

## Source

`packages/ui/src/containers/cell/cell.tsx`

---

# Cols

> `Cols` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/cols

`Cols` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { Cols } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/cols`.

## Usage

```tsx
<Cols>
  <>
          <Panel title="Agenda de hoy">12 citas, 3 por confirmar.</Panel>
          <Panel title="Barberos">Diego, Mateo y Camila en turno.</Panel>
        </>
</Cols>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"rail" \| "half" \| "calc"` |  | Column proportions. Omit for the base main + side split. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-cols--default)
- [Rail](/storybook/?path=/story/containers-cols--rail)
- [Half](/storybook/?path=/story/containers-cols--half)
- [Calc](/storybook/?path=/story/containers-cols--calc)
- [With Stack](/storybook/?path=/story/containers-cols--with-stack)
- [Narrow](/storybook/?path=/story/containers-cols--narrow)

## Source

`packages/ui/src/containers/cols/cols.tsx`

---

# ColsStack

> `ColsStack` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/cols-stack

`ColsStack` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { ColsStack } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/cols`.

## Usage

```tsx
<ColsStack>
  <>
          <Panel title="Agenda de hoy">12 citas, 3 por confirmar.</Panel>
          <Panel title="Barberos">Diego, Mateo y Camila en turno.</Panel>
        </>
</ColsStack>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `wideSplit` | `boolean` |  | From 1500px of page width the stack becomes 2 columns and its first child spans both rows. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-cols--default)
- [Rail](/storybook/?path=/story/containers-cols--rail)
- [Half](/storybook/?path=/story/containers-cols--half)
- [Calc](/storybook/?path=/story/containers-cols--calc)
- [With Stack](/storybook/?path=/story/containers-cols--with-stack)
- [Narrow](/storybook/?path=/story/containers-cols--narrow)

## Source

`packages/ui/src/containers/cols/cols.tsx`

---

# Comment

> Annotation callout on a document: bold author, optional counter, body.

Source: https://ui.jcsoftdev.com/docs/components/comment

Annotation callout on a document: bold author, optional counter, body.

## Import

```ts
import { Comment } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/comment`.

## Usage

```tsx
<Comment
  tone="pending"
  author="Camila Rojas"
  label="Nota de Camila Rojas"
>
  El cliente pidió degradado alto y no usar navaja en la nuca.
</Comment>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"pending" \| "reply"` | `"pending"` |  |
| `author` * | `string` |  | Name of the commenter. |
| `label` * | `string` |  | Accessible name of the note (`role=note` takes no name from content). |
| `number` | `number` |  | Optional counter shown before the author. |
| `children` | `ReactNode` |  |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-comment--default)
- [Reply](/storybook/?path=/story/containers-comment--reply)
- [Numbered](/storybook/?path=/story/containers-comment--numbered)

## Source

`packages/ui/src/containers/comment/comment.tsx`

---

# DataGrid

> Data grid with sorting, filters, quick search, column pinning, resizing, reordering and visibility, row selection, grouping with aggregates, inline editing, virtualized rows or pa…

Source: https://ui.jcsoftdev.com/docs/components/data-grid

Data grid with sorting, filters, quick search, column pinning, resizing, reordering and
visibility, row selection, grouping with aggregates, inline editing, virtualized rows or
pagination, CSV export, and full keyboard navigation (ARIA grid pattern, roving tabindex).
It adapts to its container width: the toolbar wraps and the grid scrolls horizontally with
its pinned columns kept in place.

## Import

```ts
import { DataGrid } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/data-grid`.

## Usage

```tsx
<DataGrid
  aria-label="Ventas de octubre"
  data={ventas}
  columns={ventaColumns}
  selectable
  loading={false}
  hideToolbar={false}
  height={440}
  defaultPinned={{ left: ["id"] }}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `readonly T[]` | `EMPTY_DATA as readonly T[]` | Rows to show. Optional with `dataSource`, which loads them. |
| `columns` * | `readonly DataGridColumn<T>[]` |  |  |
| `aria-label` * | `string` |  | Accessible name of the grid. |
| `getRowId` | `((row: T, index: number) => string)` |  | Stable row id (selection, editing, keys). The data index by default. |
| `height` | `number` | `480` | Maximum height of the scrolling body in px (virtualized mode). |
| `pageSize` | `number` |  | Switches from virtualized scrolling to pagination with this page size. |
| `pageSizeOptions` | `readonly number[]` | `[25, 50, 100]` |  |
| `storageKey` | `string` |  | localStorage key that remembers column order, widths, visibility, pins and density. |
| `sort` | `readonly SortRule[]` |  |  |
| `defaultSort` | `readonly SortRule[]` | `EMPTY_SORT` |  |
| `onSortChange` | `((sort: SortRule[]) => void)` |  |  |
| `filters` | `Readonly<Record<string, FilterValue>>` |  |  |
| `defaultFilters` | `Readonly<Record<string, FilterValue>>` | `EMPTY_FILTERS` |  |
| `onFiltersChange` | `((filters: Filters) => void)` |  |  |
| `groupBy` | `readonly string[]` |  |  |
| `defaultGroupBy` | `readonly string[]` | `EMPTY_LIST` |  |
| `onGroupByChange` | `((groupBy: string[]) => void)` |  |  |
| `defaultPinned` | `{ left?: readonly string[]; right?: readonly string[]; }` |  |  |
| `defaultHidden` | `readonly string[]` |  |  |
| `density` | `"normal" \| "compact" \| "comfortable"` |  |  |
| `defaultDensity` | `"normal" \| "compact" \| "comfortable"` | `"normal"` |  |
| `onDensityChange` | `((density: Density) => void)` |  |  |
| `selectable` | `boolean` | `false` | Adds a checkbox column; Shift selects a range. |
| `selectedRowIds` | `readonly string[]` |  |  |
| `defaultSelectedRowIds` | `readonly string[]` | `EMPTY_LIST` |  |
| `onSelectionChange` | `((ids: string[]) => void)` |  |  |
| `onCellChange` | `((change: CellChange<T>) => void)` |  | Called when an inline edit is committed with a different value. The grid does not mutate `data`. |
| `onCellsChange` | `((changes: CellChange<T>[]) => void)` |  | Called once with every cell a paste, fill, undo or redo changes. Without it those changes go to `onCellChange` one by one, which loses updates if the parent sets state from stale data. |
| `history` | `boolean` | `false` | Undo / redo of cell edits, paste, fill and row changes: buttons plus Ctrl / Cmd + Z, Shift + Ctrl / Cmd + Z, Ctrl + Y. |
| `historyDepth` | `number` | `DEFAULT_HISTORY_DEPTH` | Commands kept for undo (and for redo). 100 by default. |
| `onHistoryChange` | `((history: HistorySummary) => void)` |  |  |
| `formulas` | `boolean` | `false` | Spreadsheet formulas: a cell whose text starts with `=` is evaluated (`=B2*C2`, `=SUM(D2:D9)`, `=IF(E2>100,"alto","bajo")`). Columns are lettered in the order of `columns` and rows are numbered in the order of `data`; a formula bar shows the raw content of th… |
| `createRow` | `(() => T)` |  | Adds the "add row" button: the new row is appended through `onRowsChange`. |
| `onRowsChange` | `((change: RowsChange<T>) => void)` |  | Rows added (`createRow`), removed (the toolbar button removes the selected rows) or restored by undo. |
| `dataSource` | `DataSource<T>` |  | Server-side rows. Sort, filters and quick search are sent to `getRows` instead of being applied here; with `pageSize` the grid pages through blocks of that size, without it rows are loaded as you scroll. Grouping, tree data, row pinning, pivot and detail rows… |
| `maxBlocks` | `number` |  | Blocks kept in memory in infinite mode before the least recently used are dropped. |
| `tree` | `{ getParentId: (row: T) => string \| null \| undefined; }` |  | Shows `data` as a tree: `getParentId` links a row to its parent (nullish for roots). |
| `expandedRowIds` | `readonly string[]` |  | Expanded row ids: tree nodes and rows with a detail panel. |
| `defaultExpandedRowIds` | `readonly string[]` | `EMPTY_LIST` |  |
| `onExpandedRowsChange` | `((ids: string[]) => void)` |  |  |
| `renderDetail` | `((row: T, rowId: string) => ReactNode)` |  | Detail panel (master / detail) rendered under an expanded row. |
| `detailHeight` | `number \| ((row: T) => number)` | `DEFAULT_DETAIL_HEIGHT` | Height of a detail panel in px (fixed so rows stay virtualizable). 240 by default. |
| `rowPinning` | `boolean` | `false` | Adds pin-to-top / pin-to-bottom buttons to rows; pinned rows stay in view while scrolling. |
| `pinnedRows` | `PinnedRows` |  |  |
| `defaultPinnedRows` | `PinnedRows` | `NO_PINNED_ROWS` |  |
| `onPinnedRowsChange` | `((pinned: PinnedRows) => void)` |  |  |
| `rowReorder` | `boolean` | `false` | Drag handle and Alt + arrows to reorder rows; works without sort, filters or grouping. |
| `onRowReorder` | `((event: RowReorderEvent) => void)` |  | Called with the new order; the grid does not mutate `data`. |
| `rangeSelection` | `boolean` | `false` | Rectangular cell selection by drag, Shift + click or Shift + arrows, with Ctrl + C as TSV. |
| `fillSeries` | `{ dateStep?: DateStepMode; }` |  | How the fill handle reads series. `dateStep`: "auto" (default) continues dates by months when they share the day of the month and by days otherwise; "day" and "month" force one unit. |
| `charts` | `boolean` | `false` | Adds a "Graficar" button to the range status bar (turns `rangeSelection` on): the selected cells open a bar, line, area or pie chart under the grid. The text column of the range names the categories and each numeric column is a series. The chart code is loade… |
| `advancedFilter` | `FilterGroup` |  | Advanced filter (AND / OR groups of conditions) applied after the column filters. |
| `defaultAdvancedFilter` | `FilterGroup` | `EMPTY_ADVANCED` |  |
| `onAdvancedFilterChange` | `((filter: FilterGroup) => void)` |  |  |
| `showAdvancedFilter` | `boolean` | `false` | Adds the advanced filter button to the toolbar. |
| `toolPanel` | `boolean` | `false` | Side panel to show, hide and reorder columns, group rows and set up a pivot. |
| `defaultToolPanelOpen` | `boolean` | `false` |  |
| `pivot` | `PivotConfig` |  | Pivot: row fields x pivot column x aggregated value. |
| `defaultPivot` | `PivotConfig` | `EMPTY_PIVOT` |  |
| `onPivotChange` | `((pivot: PivotConfig) => void)` |  |  |
| `loading` | `boolean` | `false` |  |
| `emptyMessage` | `ReactNode` |  | Shown when there are no rows (a filtered-out message is used when filters are active). |
| `showFooter` | `boolean` |  | Footer with the column aggregates. On when some column has `aggregate`. |
| `hideToolbar` | `boolean` | `false` | Hides search, chips, density, columns and export. |
| `exportFilename` | `string \| false` | `"datos.csv"` | CSV file name for the export button; `false` hides the button. |
| `onExport` | `((payload: ExportPayload) => void)` |  | Called with the CSV right before it is downloaded. |
| `exportXlsx` | `string \| boolean` | `false` | Adds an "Exportar XLSX" button: a file name (`"ventas.xlsx"`) or `true` for `datos.xlsx`. Same rows and columns as the CSV export, with numbers as numbers and dates as dates. The writer (`@jcsoftdev/ui/xlsx`) is loaded when the button is used, so it costs not… |
| `onExportXlsx` | `((payload: XlsxExportPayload) => void)` |  | Called with the file right before it is downloaded. |
| `toolbarActions` | `ReactNode` |  |  |
| `labels` | `Partial<DataGridLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/containers-datagrid--default)
- [Sorting / Filtering](/storybook/?path=/story/containers-datagrid--sorting-filtering)
- [Pinning](/storybook/?path=/story/containers-datagrid--pinning)
- [Grouping](/storybook/?path=/story/containers-datagrid--grouping)
- [Editing](/storybook/?path=/story/containers-datagrid--editing)
- [Virtualized 10k](/storybook/?path=/story/containers-datagrid--virtualized-10-k)
- [Pagination](/storybook/?path=/story/containers-datagrid--pagination)
- [Narrow (320 px)](/storybook/?path=/story/containers-datagrid--narrow)
- [Dark](/storybook/?path=/story/containers-datagrid--dark)
- [Loading](/storybook/?path=/story/containers-datagrid--loading)
- [Empty](/storybook/?path=/story/containers-datagrid--empty)
- [Column types](/storybook/?path=/story/containers-datagrid--column-types)
- [Validation](/storybook/?path=/story/containers-datagrid--validation)
- [Reorder / resize / hide](/storybook/?path=/story/containers-datagrid--reorder-resize-hide)
- [Column groups](/storybook/?path=/story/containers-datagrid--column-groups)
- [Column groups (320 px)](/storybook/?path=/story/containers-datagrid--column-groups-narrow)
- [Row pinning](/storybook/?path=/story/containers-datagrid--row-pinning)
- [Row reorder](/storybook/?path=/story/containers-datagrid--row-reorder)
- [Row expansion](/storybook/?path=/story/containers-datagrid--row-expansion)
- [State persistence](/storybook/?path=/story/containers-datagrid--state-persistence)
- [Keyboard navigation](/storybook/?path=/story/containers-datagrid--keyboard-navigation)
- [Tree data](/storybook/?path=/story/containers-datagrid--tree-data)
- [Remote pagination](/storybook/?path=/story/containers-datagrid--remote-pagination)
- [Infinite scroll](/storybook/?path=/story/containers-datagrid--infinite-scroll)
- [Set filter](/storybook/?path=/story/containers-datagrid--set-filter)
- [Filter builder](/storybook/?path=/story/containers-datagrid--filter-builder)
- [Filter builder (toolbar)](/storybook/?path=/story/containers-datagrid--filter-builder-toolbar)
- [Filter builder (320 px)](/storybook/?path=/story/containers-datagrid--filter-builder-narrow)
- [Range selection](/storybook/?path=/story/containers-datagrid--range-selection)
- [Range selection (320 px)](/storybook/?path=/story/containers-datagrid--range-selection-narrow)
- [Pivot](/storybook/?path=/story/containers-datagrid--pivot)
- [Master / detail](/storybook/?path=/story/containers-datagrid--master-detail)
- [Tool panel](/storybook/?path=/story/containers-datagrid--tool-panel)
- [Tool panel (320 px)](/storybook/?path=/story/containers-datagrid--tool-panel-narrow)
- [Export CSV](/storybook/?path=/story/containers-datagrid--export-csv)
- [Default](/storybook/?path=/story/containers-datagrid-filterbuilder--default)
- [Empty](/storybook/?path=/story/containers-datagrid-filterbuilder--empty)
- [Narrow](/storybook/?path=/story/containers-datagrid-filterbuilder--narrow)
- [Undo / redo](/storybook/?path=/story/containers-datagrid-spreadsheet--undo-redo)
- [Undo / redo (320 px)](/storybook/?path=/story/containers-datagrid-spreadsheet--undo-redo-narrow)
- [Undo / redo (bordered preset)](/storybook/?path=/story/containers-datagrid-spreadsheet--undo-redo-preset)
- [Formulas](/storybook/?path=/story/containers-datagrid-spreadsheet--formulas)
- [Formulas (320 px)](/storybook/?path=/story/containers-datagrid-spreadsheet--formulas-narrow)
- [Formulas (elevated preset)](/storybook/?path=/story/containers-datagrid-spreadsheet--formulas-preset)
- [Formula errors](/storybook/?path=/story/containers-datagrid-spreadsheet--formula-errors)
- [Export XLSX](/storybook/?path=/story/containers-datagrid-spreadsheet--export-xlsx)
- [Export XLSX (320 px)](/storybook/?path=/story/containers-datagrid-spreadsheet--export-xlsx-narrow)
- [Export XLSX (glass preset)](/storybook/?path=/story/containers-datagrid-spreadsheet--export-xlsx-preset)
- [Integrated charts](/storybook/?path=/story/containers-datagrid-spreadsheet--integrated-charts)
- [Integrated charts (320 px)](/storybook/?path=/story/containers-datagrid-spreadsheet--integrated-charts-narrow)
- [Integrated charts (flat preset)](/storybook/?path=/story/containers-datagrid-spreadsheet--integrated-charts-preset)
- [Sparkline column](/storybook/?path=/story/containers-datagrid-spreadsheet--sparkline-column)
- [Sparkline column (320 px)](/storybook/?path=/story/containers-datagrid-spreadsheet--sparkline-column-narrow)
- [Fill handle](/storybook/?path=/story/containers-datagrid-spreadsheet--fill-handle)
- [Fill handle (320 px)](/storybook/?path=/story/containers-datagrid-spreadsheet--fill-handle-narrow)
- [Fill handle (bordered preset)](/storybook/?path=/story/containers-datagrid-spreadsheet--fill-handle-preset)
- [Fill handle (up, left and auto-scroll)](/storybook/?path=/story/containers-datagrid-spreadsheet--fill-up-and-left)
- [Fill handle (up, left, 320 px)](/storybook/?path=/story/containers-datagrid-spreadsheet--fill-up-and-left-narrow)

## Source

`packages/ui/src/containers/data-grid/data-grid.tsx`

---

# DescriptionList

> Two-column definition list (auto term / flexible value aligned right); stacks term over value when its own container is narrower than 24rem.

Source: https://ui.jcsoftdev.com/docs/components/description-list

Two-column definition list (auto term / flexible value aligned right); stacks term over
value when its own container is narrower than 24rem.
Compose flat `<dt>`/`<dd>` pairs as children.

## Import

```ts
import { DescriptionList } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/description-list`.

## Usage

```tsx
<DescriptionList>
  <>
          <dt>Cliente</dt>
          <dd>Luis Ramírez</dd>
          <dt>Servicio</dt>
          <dd>Corte + barba</dd>
          <dt>Barbero</dt>
          <dd>Mateo Flores</dd>
          <dt>Hora</dt>
          <dd>Sábado 11:30</dd>
          <dt>Total</dt>
          <dd>S/ 45</dd>
        </>
</DescriptionList>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-descriptionlist--default)
- [Long Values](/storybook/?path=/story/containers-descriptionlist--long-values)
- [Narrow](/storybook/?path=/story/containers-descriptionlist--narrow)

## Source

`packages/ui/src/containers/description-list/description-list.tsx`

---

# Facts

> Three-column grid of key facts with a dashed top separator.

Source: https://ui.jcsoftdev.com/docs/components/facts

Three-column grid of key facts with a dashed top separator. Wrap each
`<dt>`/`<dd>` pair in its own `<div>` (one grid cell). Collapses to one
column when its own container is 560px wide or less.

## Import

```ts
import { Facts } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/facts`.

## Usage

```tsx
<Facts>
  <>
          <div>
            <dt>Visitas</dt>
            <dd>14 este año</dd>
          </div>
          <div>
            <dt>Barbero habitual</dt>
            <dd>Diego Quispe</dd>
          </div>
          <div>
            <dt>Gasto total</dt>
            <dd>S/ 560</dd>
          </div>
        </>
</Facts>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-facts--default)
- [Narrow](/storybook/?path=/story/containers-facts--narrow)

## Source

`packages/ui/src/containers/facts/facts.tsx`

---

# FileTree

> Expandable tree following the WAI-ARIA tree pattern: one tab stop with roving focus, arrows to move and open/close, Home/End, type-ahead, Enter or Space to select.

Source: https://ui.jcsoftdev.com/docs/components/file-tree

Expandable tree following the WAI-ARIA tree pattern: one tab stop with roving focus,
arrows to move and open/close, Home/End, type-ahead, Enter or Space to select.

## Import

```ts
import { FileTree } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/file-tree`.

## Usage

```tsx
<FileTree
  nodes={nodes}
  label="Archivos de la barbería"
  defaultExpandedIds={["clientes"]}
  defaultSelectedId="lista"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` * | `FileTreeNode[]` |  |  |
| `label` * | `string` |  | Accessible name of the tree. |
| `selectedId` | `string \| null` |  |  |
| `defaultSelectedId` | `string \| null` | `null` |  |
| `onSelect` | `((id: string, node: FileTreeNode) => void)` |  |  |
| `expandedIds` | `string[]` |  |  |
| `defaultExpandedIds` | `string[]` | `[]` |  |
| `onExpandedChange` | `((ids: string[]) => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/containers-filetree--default)
- [Controlled](/storybook/?path=/story/containers-filetree--controlled)
- [Narrow](/storybook/?path=/story/containers-filetree--narrow)
- [Brutal Preset](/storybook/?path=/story/containers-filetree--brutal-preset)

## Source

`packages/ui/src/containers/file-tree/file-tree.tsx`

---

# FilterBuilder

> Builds a filter of nested AND / OR groups of conditions (column, operator, value).

Source: https://ui.jcsoftdev.com/docs/components/filter-builder

Builds a filter of nested AND / OR groups of conditions (column, operator, value). It is a
controlled editor over a `FilterGroup`; `applyAdvancedFilter` evaluates it. It adapts to the
width of its container: fields stack when it is narrow.

## Import

```ts
import { FilterBuilder } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/data-grid`.

## Usage

```tsx
export const Default: Story = { render: () => <Demo start={initial} /> };
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` * | `readonly DataGridColumn<T>[]` |  |  |
| `value` * | `FilterGroup` |  |  |
| `onChange` * | `(next: FilterGroup) => void` |  |  |
| `valuesOf` | `((columnId: string) => string[])` |  | Values offered for select-like columns; a text box is used when absent or empty. |
| `labels` | `Partial<DataGridLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/containers-datagrid-filterbuilder--default)
- [Empty](/storybook/?path=/story/containers-datagrid-filterbuilder--empty)
- [Narrow](/storybook/?path=/story/containers-datagrid-filterbuilder--narrow)

## Source

`packages/ui/src/containers/data-grid/filter-builder-editor.tsx`

---

# GenericRow

> Generic 3-column row (start / flexible content / end) for heterogeneous lists.

Source: https://ui.jcsoftdev.com/docs/components/generic-row

Generic 3-column row (start / flexible content / end) for heterogeneous
lists. The start and end slots take any content (icon, avatar, chip,
button). No top border on the first row of a consecutive list.

## Import

```ts
import { GenericRow } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/generic-row`.

## Usage

```tsx
<GenericRow>
  <>
          <Avatar name="Luis Ramírez" />
          <GenericRowContent>
            <GenericRowTitle>Luis Ramírez</GenericRowTitle>
            <GenericRowMeta>Corte + barba · Hoy 16:30</GenericRowMeta>
          </GenericRowContent>
          <Chip tone="success">Confirmada</Chip>
        </>
</GenericRow>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-genericrow--default)
- [Heterogeneous List](/storybook/?path=/story/containers-genericrow--heterogeneous-list)
- [Narrow](/storybook/?path=/story/containers-genericrow--narrow)

## Source

`packages/ui/src/containers/generic-row/generic-row.tsx`

---

# GenericRowContent

> Flexible middle column wrapping title and meta.

Source: https://ui.jcsoftdev.com/docs/components/generic-row-content

Flexible middle column wrapping title and meta.

## Import

```ts
import { GenericRowContent } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/generic-row`.

## Usage

```tsx
<GenericRowContent>
  <>
          <Avatar name="Luis Ramírez" />
          <GenericRowContent>
            <GenericRowTitle>Luis Ramírez</GenericRowTitle>
            <GenericRowMeta>Corte + barba · Hoy 16:30</GenericRowMeta>
          </GenericRowContent>
          <Chip tone="success">Confirmada</Chip>
        </>
</GenericRowContent>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-genericrow--default)
- [Heterogeneous List](/storybook/?path=/story/containers-genericrow--heterogeneous-list)
- [Narrow](/storybook/?path=/story/containers-genericrow--narrow)

## Source

`packages/ui/src/containers/generic-row/generic-row.tsx`

---

# GenericRowMeta

> Secondary metadata under the title.

Source: https://ui.jcsoftdev.com/docs/components/generic-row-meta

Secondary metadata under the title.

## Import

```ts
import { GenericRowMeta } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/generic-row`.

## Usage

```tsx
<GenericRowMeta>
  <>
          <Avatar name="Luis Ramírez" />
          <GenericRowContent>
            <GenericRowTitle>Luis Ramírez</GenericRowTitle>
            <GenericRowMeta>Corte + barba · Hoy 16:30</GenericRowMeta>
          </GenericRowContent>
          <Chip tone="success">Confirmada</Chip>
        </>
</GenericRowMeta>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-genericrow--default)
- [Heterogeneous List](/storybook/?path=/story/containers-genericrow--heterogeneous-list)
- [Narrow](/storybook/?path=/story/containers-genericrow--narrow)

## Source

`packages/ui/src/containers/generic-row/generic-row.tsx`

---

# GenericRowTitle

> `GenericRowTitle` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/generic-row-title

`GenericRowTitle` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { GenericRowTitle } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/generic-row`.

## Usage

```tsx
<GenericRowTitle>
  <>
          <Avatar name="Luis Ramírez" />
          <GenericRowContent>
            <GenericRowTitle>Luis Ramírez</GenericRowTitle>
            <GenericRowMeta>Corte + barba · Hoy 16:30</GenericRowMeta>
          </GenericRowContent>
          <Chip tone="success">Confirmada</Chip>
        </>
</GenericRowTitle>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-genericrow--default)
- [Heterogeneous List](/storybook/?path=/story/containers-genericrow--heterogeneous-list)
- [Narrow](/storybook/?path=/story/containers-genericrow--narrow)

## Source

`packages/ui/src/containers/generic-row/generic-row.tsx`

---

# HBars

> Horizontal comparison bars.

Source: https://ui.jcsoftdev.com/docs/components/h-bars

Horizontal comparison bars. The visual grid is `aria-hidden`; an `sr-only`
table exposes name plus each series value as real text.

## Import

```ts
import { HBars } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/hbars`.

## Usage

```tsx
<HBars
  variant="stacked"
  scaleMax={20}
  description="Cortes y barbas por barbero esta semana"
  nameHeader="Barbero"
  series={[
      { id: "cortes", label: "Cortes" },
      { id: "barbas", label: "Barbas" },
    ]}
  rows={[
      { id: "diego", name: "Diego Quispe", values: [12, 6] },
      { id: "mateo", name: "Mateo Flores", values: [9, 4] },
      { id: "camila", name: "Camila Rojas", values: [7, 3] },
      { id: "andres", name: "Andrés Paredes", values: [3, 1], tone: "danger" },
    ]}
  ticks={ticks}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` * | `HBarRow[]` |  |  |
| `series` * | `HBarSeriesTuple` |  |  |
| `scaleMax` * | `number` |  | Domain value that maps to 100% of the bar width. |
| `ticks` | `HBarTick[]` |  | Ticks of the bottom axis; the whole row is omitted when not passed. |
| `threshold` | `number` |  | Threshold line, in the same scale as `scaleMax`. |
| `variant` | `"stacked" \| "paired"` | `"stacked"` | "stacked" (default): one fill per row split between series by `flex`. "paired": each series draws its own independent fill so two metrics on the same scale can be compared. |
| `description` * | `string` |  | Accessible table caption exposing the same numbers as the visual grid. |
| `nameHeader` * | `string` |  | Header of the name column in the accessible table. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/containers-hbars--default)
- [Paired](/storybook/?path=/story/containers-hbars--paired)
- [With Threshold](/storybook/?path=/story/containers-hbars--with-threshold)
- [Single Series Without Ticks](/storybook/?path=/story/containers-hbars--single-series-without-ticks)

## Source

`packages/ui/src/containers/hbars/hbars.tsx`

---

# HighlightLine

> Focus sentence at the top of a card; wrap the key phrase in `<strong>` to emphasize it.

Source: https://ui.jcsoftdev.com/docs/components/highlight-line

Focus sentence at the top of a card; wrap the key phrase in `<strong>` to
emphasize it. It only paints the text, it computes nothing.

## Import

```ts
import { HighlightLine } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/highlight-line`.

## Usage

```tsx
<HighlightLine>
  <>
          Hoy llevas <strong>S/ 840</strong> en ingresos, 12% más que el sábado pasado.
        </>
</HighlightLine>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-highlightline--default)
- [Plain Text](/storybook/?path=/story/containers-highlightline--plain-text)

## Source

`packages/ui/src/containers/highlight-line/highlight-line.tsx`

---

# ItemCardGroup

> Rows grouped inside a single card (settings, clients, services), with an optional heading.

Source: https://ui.jcsoftdev.com/docs/components/item-card-group

Rows grouped inside a single card (settings, clients, services), with an optional heading.

## Import

```ts
import { ItemCardGroup } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/item-card-group`.

## Usage

```tsx
<ItemCardGroup
  title="Servicios y ajustes"
  description="Lo que ven tus clientes al reservar"
  items={items}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `items` * | `ItemCardGroupItem[]` |  |  |
| `selectedId` | `string` |  | Id of the highlighted row. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-itemcardgroup--default)
- [Selectable](/storybook/?path=/story/containers-itemcardgroup--selectable)
- [Narrow](/storybook/?path=/story/containers-itemcardgroup--narrow)
- [Bordered Preset](/storybook/?path=/story/containers-itemcardgroup--bordered-preset)
- [Brutal Compact](/storybook/?path=/story/containers-itemcardgroup--brutal-compact)

## Source

`packages/ui/src/containers/item-card-group/item-card-group.tsx`

---

# Kanban

> Board of columns with draggable cards and WIP limits.

Source: https://ui.jcsoftdev.com/docs/components/kanban

Board of columns with draggable cards and WIP limits. Pointer: drag a card (touch: use the
grip). Keyboard: Space or Enter picks a card up, arrows move it, Space or Enter drops it,
Escape cancels. Moves are announced in a live region.

## Import

```ts
import { Kanban } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/kanban`.

## Usage

```tsx
<Kanban
  defaultColumns={columns}
  enforceLimit={false}
  emptyLabel="Sin citas"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `KanbanColumnData[]` |  | Controlled board. Pair with `onColumnsChange`. |
| `defaultColumns` | `KanbanColumnData[]` | `[]` |  |
| `onColumnsChange` | `((columns: KanbanColumnData[], move: KanbanMove) => void)` |  | Called after a drop (pointer release or keyboard drop) with the new board and the move. |
| `enforceLimit` | `boolean` | `false` | Refuse drops into another column that already reached its WIP limit. |
| `renderCard` | `((card: KanbanCardData) => ReactNode)` |  | Replaces the default card body. |
| `emptyLabel` | `string` | `"Sin tarjetas"` |  |
| `aria-label` | `string` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/containers-kanban--default)
- [Enforced Limit](/storybook/?path=/story/containers-kanban--enforced-limit)
- [Narrow](/storybook/?path=/story/containers-kanban--narrow)
- [Brutal Preset](/storybook/?path=/story/containers-kanban--brutal-preset)
- [Glass Compact](/storybook/?path=/story/containers-kanban--glass-compact)

## Source

`packages/ui/src/containers/kanban/kanban.tsx`

---

# Kpi

> `Kpi` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/kpi

`Kpi` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { Kpi } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/kpi`.

## Usage

```tsx
<Kpi
  label="Citas hoy"
  value="12"
  description="3 pendientes"
  variant="default"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` * | `ReactNode` |  | Short label describing the metric. |
| `value` * | `ReactNode` |  | Highlighted number, already formatted by the consumer. |
| `suffix` | `ReactNode` |  | Small suffix next to the number, e.g. "/12". |
| `description` | `ReactNode` |  | Optional subtext. |
| `variant` | `"danger" \| "default"` | `"default"` |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/containers-kpi--default)
- [With Suffix](/storybook/?path=/story/containers-kpi--with-suffix)
- [Danger](/storybook/?path=/story/containers-kpi--danger)
- [Occupancy](/storybook/?path=/story/containers-kpi--occupancy)
- [Narrow](/storybook/?path=/story/containers-kpi--narrow)

## Source

`packages/ui/src/containers/kpi/kpi.tsx`

---

# KpiGroup

> Metrics that belong together in one card, divided by hairlines.

Source: https://ui.jcsoftdev.com/docs/components/kpi-group

Metrics that belong together in one card, divided by hairlines. Columns follow the
container width: 1, 2 or 4 across.

## Import

```ts
import { KpiGroup } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/kpi-group`.

## Usage

```tsx
<KpiGroup items={items} animate />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` * | `KpiGroupItem[]` |  |  |
| `animate` | `boolean` | `true` | Animate numeric values counting up. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-kpigroup--default)
- [Narrow](/storybook/?path=/story/containers-kpigroup--narrow)
- [Two Columns](/storybook/?path=/story/containers-kpigroup--two-columns)
- [Brutal Preset](/storybook/?path=/story/containers-kpigroup--brutal-preset)
- [Glass Preset](/storybook/?path=/story/containers-kpigroup--glass-preset)

## Source

`packages/ui/src/containers/kpi-group/kpi-group.tsx`

---

# PageHeader

> Page header.

Source: https://ui.jcsoftdev.com/docs/components/page-header

Page header. No required parts: compose an eyebrow / title / lede block in
a plain `<div>` and, when the view has buttons, `PageHeaderActions` as the
second child. Actions wrap under the title when the container is too narrow.

## Import

```ts
import { PageHeader } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/page-header`.

## Usage

```tsx
<PageHeader>
  <>
          <div>
            <PageHeaderEyebrow>Sábado 11 de octubre</PageHeaderEyebrow>
            <PageHeaderTitle>
              Agenda de <span className="text-accent-word">hoy</span>
            </PageHeaderTitle>
            <PageHeaderLede>
              12 citas con 3 barberos. Quedan 2 horarios libres por la tarde.
            </PageHeaderLede>
          </div>
          <PageHeaderActions>
            <Button variant="secondary">Bloquear horario</Button>
            <Button>Nueva cita</Button>
          </PageHeaderActions>
        </>
</PageHeader>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-pageheader--default)
- [Title Only](/storybook/?path=/story/containers-pageheader--title-only)
- [Without Actions](/storybook/?path=/story/containers-pageheader--without-actions)
- [Narrow](/storybook/?path=/story/containers-pageheader--narrow)

## Source

`packages/ui/src/containers/page-header/page-header.tsx`

---

# PageHeaderActions

> `PageHeaderActions` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/page-header-actions

`PageHeaderActions` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { PageHeaderActions } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/page-header`.

## Usage

```tsx
<PageHeaderActions>
  <>
          <div>
            <PageHeaderEyebrow>Sábado 11 de octubre</PageHeaderEyebrow>
            <PageHeaderTitle>
              Agenda de <span className="text-accent-word">hoy</span>
            </PageHeaderTitle>
            <PageHeaderLede>
              12 citas con 3 barberos. Quedan 2 horarios libres por la tarde.
            </PageHeaderLede>
          </div>
          <PageHeaderActions>
            <Button variant="secondary">Bloquear horario</Button>
            <Button>Nueva cita</Button>
          </PageHeaderActions>
        </>
</PageHeaderActions>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-pageheader--default)
- [Title Only](/storybook/?path=/story/containers-pageheader--title-only)
- [Without Actions](/storybook/?path=/story/containers-pageheader--without-actions)
- [Narrow](/storybook/?path=/story/containers-pageheader--narrow)

## Source

`packages/ui/src/containers/page-header/page-header.tsx`

---

# PageHeaderEyebrow

> `PageHeaderEyebrow` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/page-header-eyebrow

`PageHeaderEyebrow` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { PageHeaderEyebrow } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/page-header`.

## Usage

```tsx
<PageHeaderEyebrow>
  <>
          <div>
            <PageHeaderEyebrow>Sábado 11 de octubre</PageHeaderEyebrow>
            <PageHeaderTitle>
              Agenda de <span className="text-accent-word">hoy</span>
            </PageHeaderTitle>
            <PageHeaderLede>
              12 citas con 3 barberos. Quedan 2 horarios libres por la tarde.
            </PageHeaderLede>
          </div>
          <PageHeaderActions>
            <Button variant="secondary">Bloquear horario</Button>
            <Button>Nueva cita</Button>
          </PageHeaderActions>
        </>
</PageHeaderEyebrow>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-pageheader--default)
- [Title Only](/storybook/?path=/story/containers-pageheader--title-only)
- [Without Actions](/storybook/?path=/story/containers-pageheader--without-actions)
- [Narrow](/storybook/?path=/story/containers-pageheader--narrow)

## Source

`packages/ui/src/containers/page-header/page-header.tsx`

---

# PageHeaderLede

> `PageHeaderLede` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/page-header-lede

`PageHeaderLede` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { PageHeaderLede } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/page-header`.

## Usage

```tsx
<PageHeaderLede>
  <>
          <div>
            <PageHeaderEyebrow>Sábado 11 de octubre</PageHeaderEyebrow>
            <PageHeaderTitle>
              Agenda de <span className="text-accent-word">hoy</span>
            </PageHeaderTitle>
            <PageHeaderLede>
              12 citas con 3 barberos. Quedan 2 horarios libres por la tarde.
            </PageHeaderLede>
          </div>
          <PageHeaderActions>
            <Button variant="secondary">Bloquear horario</Button>
            <Button>Nueva cita</Button>
          </PageHeaderActions>
        </>
</PageHeaderLede>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-pageheader--default)
- [Title Only](/storybook/?path=/story/containers-pageheader--title-only)
- [Without Actions](/storybook/?path=/story/containers-pageheader--without-actions)
- [Narrow](/storybook/?path=/story/containers-pageheader--narrow)

## Source

`packages/ui/src/containers/page-header/page-header.tsx`

---

# PageHeaderTitle

> Page title.

Source: https://ui.jcsoftdev.com/docs/components/page-header-title

Page title. Wrap a word in `<span className="text-accent-word">` to accent it.

## Import

```ts
import { PageHeaderTitle } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/page-header`.

## Usage

```tsx
<PageHeaderTitle>
  <>
          <div>
            <PageHeaderEyebrow>Sábado 11 de octubre</PageHeaderEyebrow>
            <PageHeaderTitle>
              Agenda de <span className="text-accent-word">hoy</span>
            </PageHeaderTitle>
            <PageHeaderLede>
              12 citas con 3 barberos. Quedan 2 horarios libres por la tarde.
            </PageHeaderLede>
          </div>
          <PageHeaderActions>
            <Button variant="secondary">Bloquear horario</Button>
            <Button>Nueva cita</Button>
          </PageHeaderActions>
        </>
</PageHeaderTitle>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-pageheader--default)
- [Title Only](/storybook/?path=/story/containers-pageheader--title-only)
- [Without Actions](/storybook/?path=/story/containers-pageheader--without-actions)
- [Narrow](/storybook/?path=/story/containers-pageheader--narrow)

## Source

`packages/ui/src/containers/page-header/page-header.tsx`

---

# ResizableHandle

> Draggable and keyboard-resizable separator between two panels.

Source: https://ui.jcsoftdev.com/docs/components/resizable-handle

Draggable and keyboard-resizable separator between two panels.

## Import

```ts
import { ResizableHandle } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/resizable`.

## Usage

```tsx
export const Default: Story = { render: () => <Demo direction="horizontal" /> };
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` |  | Accessible name; the default describes the two neighbouring panels. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-resizable--default)
- [Vertical](/storybook/?path=/story/containers-resizable--vertical)
- [Narrow](/storybook/?path=/story/containers-resizable--narrow)
- [Brutal Preset](/storybook/?path=/story/containers-resizable--brutal-preset)

## Source

`packages/ui/src/containers/resizable/resizable.tsx`

---

# ResizablePanel

> A panel of a ResizablePanelGroup.

Source: https://ui.jcsoftdev.com/docs/components/resizable-panel

A panel of a ResizablePanelGroup. Sizes are percentages of the group.

## Import

```ts
import { ResizablePanel } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/resizable`.

## Usage

```tsx
export const Default: Story = { render: () => <Demo direction="horizontal" /> };
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultSize` | `number` |  | Initial size in percent. Panels without one share what is left. |
| `minSize` | `number` |  | Percent, default 0. |
| `maxSize` | `number` |  | Percent, default 100. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-resizable--default)
- [Vertical](/storybook/?path=/story/containers-resizable--vertical)
- [Narrow](/storybook/?path=/story/containers-resizable--narrow)
- [Brutal Preset](/storybook/?path=/story/containers-resizable--brutal-preset)

## Source

`packages/ui/src/containers/resizable/resizable.tsx`

---

# ResizablePanelGroup

> Row or column of resizable panels.

Source: https://ui.jcsoftdev.com/docs/components/resizable-panel-group

Row or column of resizable panels. Put a ResizableHandle between every two panels.

## Import

```ts
import { ResizablePanelGroup } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/resizable`.

## Usage

```tsx
export const Default: Story = { render: () => <Demo direction="horizontal" /> };
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | `"horizontal" \| "vertical"` | `"horizontal"` |  |
| `onLayout` | `((sizes: number[]) => void)` |  | Called with the layout in percent after every change. |
| `children` * | `ReactNode` |  |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-resizable--default)
- [Vertical](/storybook/?path=/story/containers-resizable--vertical)
- [Narrow](/storybook/?path=/story/containers-resizable--narrow)
- [Brutal Preset](/storybook/?path=/story/containers-resizable--brutal-preset)

## Source

`packages/ui/src/containers/resizable/resizable.tsx`

---

# Scrolly

> Scrollytelling: text steps scroll past while a graphic stays in view and follows the active step.

Source: https://ui.jcsoftdev.com/docs/components/scrolly

Scrollytelling: text steps scroll past while a graphic stays in view and follows the active
step. The active step is the one crossing a trigger line, found with an IntersectionObserver.
Wide containers put the graphic beside the steps, narrow ones pin it above them (container
queries, so it works inside a card or a dialog too). The text is real content in reading
order, so it works with a screen reader and without scrolling effects.

## Import

```ts
import { Scrolly } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/scrolly`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <div style={{ padding: 16 }}>
      <Narrative side={args.graphicSide} />
    </div>
  ),
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `graphic` * | `(state: ScrollyGraphicState) => ReactNode` |  | The sticky graphic: receives the active step, e.g. to change the data of a chart. |
| `children` * | `ReactNode` |  | `ScrollyStep` elements, in reading order. |
| `offset` | `number` | `0.5` | Where the trigger line sits in the scroll area: 0 top, 0.5 middle (default), 1 bottom. |
| `root` | `HTMLElement \| null` | `null` | Scroll container the steps move in; the page by default. |
| `graphicHeight` | `string` | `"min(55svh, 26rem)"` | Height of the sticky graphic, any CSS length. |
| `graphicSide` | `"start" \| "end"` | `"end"` | Which side the graphic takes when the container is wide. |
| `step` | `number` |  | Controlled step; the scroll position decides when omitted. |
| `onStepChange` | `((step: number) => void)` |  |  |
| `aria-label` | `string` |  | Accessible name of the narrative. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/containers-scrolly--default)
- [Narrow](/storybook/?path=/story/containers-scrolly--narrow)
- [With Step Indicator](/storybook/?path=/story/containers-scrolly--with-step-indicator)
- [Brutal Preset](/storybook/?path=/story/containers-scrolly--brutal-preset)

## Source

`packages/ui/src/containers/scrolly/scrolly.tsx`

---

# ScrollyStep

> One block of the narrative.

Source: https://ui.jcsoftdev.com/docs/components/scrolly-step

One block of the narrative. Marked `aria-current="step"` and `data-active` while it is the active one.

## Import

```ts
import { ScrollyStep } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/scrolly`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <div style={{ padding: 16 }}>
      <Narrative side={args.graphicSide} />
    </div>
  ),
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` * | `ReactNode` |  |  |
| `minHeight` | `string` | `"70svh"` | Minimum height of the step, any CSS length; a tall step gives the reader time with the graphic. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/containers-scrolly--default)
- [Narrow](/storybook/?path=/story/containers-scrolly--narrow)
- [With Step Indicator](/storybook/?path=/story/containers-scrolly--with-step-indicator)
- [Brutal Preset](/storybook/?path=/story/containers-scrolly--brutal-preset)

## Source

`packages/ui/src/containers/scrolly/scrolly.tsx`

---

# SettingsLayout

> Two-column settings grid (side nav + content).

Source: https://ui.jcsoftdev.com/docs/components/settings-layout

Two-column settings grid (side nav + content). Collapses to one column at
940px or less of the ancestor `@container/page`.

## Import

```ts
import { SettingsLayout } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/settings-layout`.

## Usage

```tsx
<SettingsLayout>
  <>
          <SettingsLayoutNav aria-label="Secciones de configuración">
            <SettingsLayoutNavItem active>Negocio</SettingsLayoutNavItem>
            <SettingsLayoutNavItem>Horarios</SettingsLayoutNavItem>
            <SettingsLayoutNavItem>Servicios</SettingsLayoutNavItem>
            <SettingsLayoutNavItem>Notificaciones</SettingsLayoutNavItem>
          </SettingsLayoutNav>
          <SettingsLayoutMain>
            <Card>
              <CardHeader>
                <h3 className="m-0 font-semibold text-[14px]">Recordatorios</h3>
              </CardHeader>
              <SettingsRow
                title="Recordatorio por WhatsApp"
                description="Se envía 2 horas antes de la cita."
                control={<Switch defaultChecked aria-label="Recordatorio por WhatsApp" />}
              />
              <SettingsRow
                title="Reseña tras el servicio"
                description="Pide una reseña al terminar la cita."
                control={<Switch aria-label="Reseña tras el servicio" />}
              />
            </Card>
            <Card>
              <CardHeader>
                <h3 className="m-0 font-semibold text-[14px]">Cobros</h3>
              </CardHeader>
              <SettingsRow
                title="Aceptar Yape y Plin"
                control={<Switch defaultChecked aria-label="Aceptar Yape y Plin" />}
              />
            </Card>
          </SettingsLayoutMain>
        </>
</SettingsLayout>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-settingslayout--default)
- [Narrow Page](/storybook/?path=/story/containers-settingslayout--narrow-page)
- [Narrow](/storybook/?path=/story/containers-settingslayout--narrow)

## Source

`packages/ui/src/containers/settings-layout/settings-layout.tsx`

---

# SettingsLayoutMain

> Content column: a single stack that becomes a 2-column masonry at 1180px of page width, where each direct child (a card) is not split across columns.

Source: https://ui.jcsoftdev.com/docs/components/settings-layout-main

Content column: a single stack that becomes a 2-column masonry at 1180px of
page width, where each direct child (a card) is not split across columns.

## Import

```ts
import { SettingsLayoutMain } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/settings-layout`.

## Usage

```tsx
<SettingsLayoutMain>
  <>
          <SettingsLayoutNav aria-label="Secciones de configuración">
            <SettingsLayoutNavItem active>Negocio</SettingsLayoutNavItem>
            <SettingsLayoutNavItem>Horarios</SettingsLayoutNavItem>
            <SettingsLayoutNavItem>Servicios</SettingsLayoutNavItem>
            <SettingsLayoutNavItem>Notificaciones</SettingsLayoutNavItem>
          </SettingsLayoutNav>
          <SettingsLayoutMain>
            <Card>
              <CardHeader>
                <h3 className="m-0 font-semibold text-[14px]">Recordatorios</h3>
              </CardHeader>
              <SettingsRow
                title="Recordatorio por WhatsApp"
                description="Se envía 2 horas antes de la cita."
                control={<Switch defaultChecked aria-label="Recordatorio por WhatsApp" />}
              />
              <SettingsRow
                title="Reseña tras el servicio"
                description="Pide una reseña al terminar la cita."
                control={<Switch aria-label="Reseña tras el servicio" />}
              />
            </Card>
            <Card>
              <CardHeader>
                <h3 className="m-0 font-semibold text-[14px]">Cobros</h3>
              </CardHeader>
              <SettingsRow
                title="Aceptar Yape y Plin"
                control={<Switch defaultChecked aria-label="Aceptar Yape y Plin" />}
              />
            </Card>
          </SettingsLayoutMain>
        </>
</SettingsLayoutMain>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-settingslayout--default)
- [Narrow Page](/storybook/?path=/story/containers-settingslayout--narrow-page)
- [Narrow](/storybook/?path=/story/containers-settingslayout--narrow)

## Source

`packages/ui/src/containers/settings-layout/settings-layout.tsx`

---

# SettingsLayoutNav

> Sticky side nav that becomes a scrollable horizontal row on narrow pages.

Source: https://ui.jcsoftdev.com/docs/components/settings-layout-nav

Sticky side nav that becomes a scrollable horizontal row on narrow pages.

## Import

```ts
import { SettingsLayoutNav } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/settings-layout`.

## Usage

```tsx
<SettingsLayoutNav>
  <>
          <SettingsLayoutNav aria-label="Secciones de configuración">
            <SettingsLayoutNavItem active>Negocio</SettingsLayoutNavItem>
            <SettingsLayoutNavItem>Horarios</SettingsLayoutNavItem>
            <SettingsLayoutNavItem>Servicios</SettingsLayoutNavItem>
            <SettingsLayoutNavItem>Notificaciones</SettingsLayoutNavItem>
          </SettingsLayoutNav>
          <SettingsLayoutMain>
            <Card>
              <CardHeader>
                <h3 className="m-0 font-semibold text-[14px]">Recordatorios</h3>
              </CardHeader>
              <SettingsRow
                title="Recordatorio por WhatsApp"
                description="Se envía 2 horas antes de la cita."
                control={<Switch defaultChecked aria-label="Recordatorio por WhatsApp" />}
              />
              <SettingsRow
                title="Reseña tras el servicio"
                description="Pide una reseña al terminar la cita."
                control={<Switch aria-label="Reseña tras el servicio" />}
              />
            </Card>
            <Card>
              <CardHeader>
                <h3 className="m-0 font-semibold text-[14px]">Cobros</h3>
              </CardHeader>
              <SettingsRow
                title="Aceptar Yape y Plin"
                control={<Switch defaultChecked aria-label="Aceptar Yape y Plin" />}
              />
            </Card>
          </SettingsLayoutMain>
        </>
</SettingsLayoutNav>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-settingslayout--default)
- [Narrow Page](/storybook/?path=/story/containers-settingslayout--narrow-page)
- [Narrow](/storybook/?path=/story/containers-settingslayout--narrow)

## Source

`packages/ui/src/containers/settings-layout/settings-layout.tsx`

---

# SettingsLayoutNavItem

> `SettingsLayoutNavItem` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/settings-layout-nav-item

`SettingsLayoutNavItem` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { SettingsLayoutNavItem } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/settings-layout`.

## Usage

```tsx
<SettingsLayoutNavItem>
  <>
          <SettingsLayoutNav aria-label="Secciones de configuración">
            <SettingsLayoutNavItem active>Negocio</SettingsLayoutNavItem>
            <SettingsLayoutNavItem>Horarios</SettingsLayoutNavItem>
            <SettingsLayoutNavItem>Servicios</SettingsLayoutNavItem>
            <SettingsLayoutNavItem>Notificaciones</SettingsLayoutNavItem>
          </SettingsLayoutNav>
          <SettingsLayoutMain>
            <Card>
              <CardHeader>
                <h3 className="m-0 font-semibold text-[14px]">Recordatorios</h3>
              </CardHeader>
              <SettingsRow
                title="Recordatorio por WhatsApp"
                description="Se envía 2 horas antes de la cita."
                control={<Switch defaultChecked aria-label="Recordatorio por WhatsApp" />}
              />
              <SettingsRow
                title="Reseña tras el servicio"
                description="Pide una reseña al terminar la cita."
                control={<Switch aria-label="Reseña tras el servicio" />}
              />
            </Card>
            <Card>
              <CardHeader>
                <h3 className="m-0 font-semibold text-[14px]">Cobros</h3>
              </CardHeader>
              <SettingsRow
                title="Aceptar Yape y Plin"
                control={<Switch defaultChecked aria-label="Aceptar Yape y Plin" />}
              />
            </Card>
          </SettingsLayoutMain>
        </>
</SettingsLayoutNavItem>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` |  | Currently visible section. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-settingslayout--default)
- [Narrow Page](/storybook/?path=/story/containers-settingslayout--narrow-page)
- [Narrow](/storybook/?path=/story/containers-settingslayout--narrow)

## Source

`packages/ui/src/containers/settings-layout/settings-layout.tsx`

---

# SettingsRow

> `SettingsRow` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/settings-row

`SettingsRow` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { SettingsRow } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/settings-row`.

## Usage

```tsx
<SettingsRow
  title="Recordatorio por WhatsApp"
  description="Se envía al cliente 2 horas antes de la cita."
  control={<Switch defaultChecked aria-label="Recordatorio por WhatsApp" />}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `control` | `ReactNode` |  | Control on the right: a switch, a button, etc. |
| `titleId` | `string` |  | Id for the title element, so the control can reference it with `aria-labelledby`. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-settingsrow--default)
- [With Button](/storybook/?path=/story/containers-settingsrow--with-button)
- [Without Description](/storybook/?path=/story/containers-settingsrow--without-description)
- [Without Control](/storybook/?path=/story/containers-settingsrow--without-control)
- [Narrow](/storybook/?path=/story/containers-settingsrow--narrow)

## Source

`packages/ui/src/containers/settings-row/settings-row.tsx`

---

# Table

> Table inside its own horizontal scroll wrapper.

Source: https://ui.jcsoftdev.com/docs/components/table

Table inside its own horizontal scroll wrapper. Give columns a `columnId` (header and cells)
and mark header cells `pinnable` to let the user pin them to the left or right edge: pinned
columns stay sticky while the rest scrolls.

## Import

```ts
import { Table } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/table`.

## Usage

```tsx
<Table aria-label="Inventario de productos">
  <>
          <TableHead>
            <tr>
              <TableHeaderCell>Producto</TableHeaderCell>
              <TableHeaderCell>SKU</TableHeaderCell>
              <TableHeaderCell alignRight>Stock</TableHeaderCell>
              <TableHeaderCell alignRight>Precio</TableHeaderCell>
            </tr>
          </TableHead>
          <TableBody>
            {inventory.map((item) => (
              <TableRow key={item.sku}>
                <TableCell>
                  {item.name} {item.low ? <Chip tone="danger">Stock bajo</Chip> : null}
                </TableCell>
                <TableCell>{item.sku}</TableCell>
                <TableCell alignRight>{item.stock}</TableCell>
                <TableCell alignRight>{item.price}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </>
</Table>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pinnedColumns` | `PinnedColumns` |  | Controlled pinned columns (ids of `columnId`). Pair it with `onPinnedColumnsChange`. |
| `defaultPinnedColumns` | `PinnedColumns` |  | Initial pins when uncontrolled. |
| `onPinnedColumnsChange` | `((pinned: { left: string[]; right: string[]; }) => void)` |  |  |
| `pinStorageKey` | `string` |  | localStorage key that remembers the user's pins (uncontrolled only). |
| `labels` | `Partial<TableLabels>` |  | Texts of the pin buttons (Spanish by default). |
| `wrapperClassName` | `string` |  | Classes of the scroll wrapper. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-table--default)
- [Link Rows](/storybook/?path=/story/containers-table--link-rows)
- [Empty](/storybook/?path=/story/containers-table--empty)
- [PinnedColumns](/storybook/?path=/story/containers-table--pinned-left-and-right)
- [User Pinning](/storybook/?path=/story/containers-table--user-pinning)
- [Controlled Pinning](/storybook/?path=/story/containers-table--controlled-pinning)
- [Narrow](/storybook/?path=/story/containers-table--narrow)

## Source

`packages/ui/src/containers/table/table.tsx`

---

# TableBody

> `TableBody` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/table-body

`TableBody` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { TableBody } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/table`.

## Usage

```tsx
<TableBody aria-label="Inventario de productos">
  <>
          <TableHead>
            <tr>
              <TableHeaderCell>Producto</TableHeaderCell>
              <TableHeaderCell>SKU</TableHeaderCell>
              <TableHeaderCell alignRight>Stock</TableHeaderCell>
              <TableHeaderCell alignRight>Precio</TableHeaderCell>
            </tr>
          </TableHead>
          <TableBody>
            {inventory.map((item) => (
              <TableRow key={item.sku}>
                <TableCell>
                  {item.name} {item.low ? <Chip tone="danger">Stock bajo</Chip> : null}
                </TableCell>
                <TableCell>{item.sku}</TableCell>
                <TableCell alignRight>{item.stock}</TableCell>
                <TableCell alignRight>{item.price}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </>
</TableBody>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-table--default)
- [Link Rows](/storybook/?path=/story/containers-table--link-rows)
- [Empty](/storybook/?path=/story/containers-table--empty)
- [PinnedColumns](/storybook/?path=/story/containers-table--pinned-left-and-right)
- [User Pinning](/storybook/?path=/story/containers-table--user-pinning)
- [Controlled Pinning](/storybook/?path=/story/containers-table--controlled-pinning)
- [Narrow](/storybook/?path=/story/containers-table--narrow)

## Source

`packages/ui/src/containers/table/table.tsx`

---

# TableCell

> `TableCell` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/table-cell

`TableCell` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { TableCell } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/table`.

## Usage

```tsx
<TableCell aria-label="Inventario de productos">
  <>
          <TableHead>
            <tr>
              <TableHeaderCell>Producto</TableHeaderCell>
              <TableHeaderCell>SKU</TableHeaderCell>
              <TableHeaderCell alignRight>Stock</TableHeaderCell>
              <TableHeaderCell alignRight>Precio</TableHeaderCell>
            </tr>
          </TableHead>
          <TableBody>
            {inventory.map((item) => (
              <TableRow key={item.sku}>
                <TableCell>
                  {item.name} {item.low ? <Chip tone="danger">Stock bajo</Chip> : null}
                </TableCell>
                <TableCell>{item.sku}</TableCell>
                <TableCell alignRight>{item.stock}</TableCell>
                <TableCell alignRight>{item.price}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </>
</TableCell>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alignRight` | `boolean` |  |  |
| `columnId` | `string` |  | Identifies the column so it can be pinned. Use the same id on the header and its cells. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-table--default)
- [Link Rows](/storybook/?path=/story/containers-table--link-rows)
- [Empty](/storybook/?path=/story/containers-table--empty)
- [PinnedColumns](/storybook/?path=/story/containers-table--pinned-left-and-right)
- [User Pinning](/storybook/?path=/story/containers-table--user-pinning)
- [Controlled Pinning](/storybook/?path=/story/containers-table--controlled-pinning)
- [Narrow](/storybook/?path=/story/containers-table--narrow)

## Source

`packages/ui/src/containers/table/table.tsx`

---

# TableHead

> `TableHead` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/table-head

`TableHead` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { TableHead } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/table`.

## Usage

```tsx
<TableHead aria-label="Inventario de productos">
  <>
          <TableHead>
            <tr>
              <TableHeaderCell>Producto</TableHeaderCell>
              <TableHeaderCell>SKU</TableHeaderCell>
              <TableHeaderCell alignRight>Stock</TableHeaderCell>
              <TableHeaderCell alignRight>Precio</TableHeaderCell>
            </tr>
          </TableHead>
          <TableBody>
            {inventory.map((item) => (
              <TableRow key={item.sku}>
                <TableCell>
                  {item.name} {item.low ? <Chip tone="danger">Stock bajo</Chip> : null}
                </TableCell>
                <TableCell>{item.sku}</TableCell>
                <TableCell alignRight>{item.stock}</TableCell>
                <TableCell alignRight>{item.price}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </>
</TableHead>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-table--default)
- [Link Rows](/storybook/?path=/story/containers-table--link-rows)
- [Empty](/storybook/?path=/story/containers-table--empty)
- [PinnedColumns](/storybook/?path=/story/containers-table--pinned-left-and-right)
- [User Pinning](/storybook/?path=/story/containers-table--user-pinning)
- [Controlled Pinning](/storybook/?path=/story/containers-table--controlled-pinning)
- [Narrow](/storybook/?path=/story/containers-table--narrow)

## Source

`packages/ui/src/containers/table/table.tsx`

---

# TableHeaderCell

> `TableHeaderCell` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/table-header-cell

`TableHeaderCell` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { TableHeaderCell } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/table`.

## Usage

```tsx
<TableHeaderCell aria-label="Inventario de productos">
  <>
          <TableHead>
            <tr>
              <TableHeaderCell>Producto</TableHeaderCell>
              <TableHeaderCell>SKU</TableHeaderCell>
              <TableHeaderCell alignRight>Stock</TableHeaderCell>
              <TableHeaderCell alignRight>Precio</TableHeaderCell>
            </tr>
          </TableHead>
          <TableBody>
            {inventory.map((item) => (
              <TableRow key={item.sku}>
                <TableCell>
                  {item.name} {item.low ? <Chip tone="danger">Stock bajo</Chip> : null}
                </TableCell>
                <TableCell>{item.sku}</TableCell>
                <TableCell alignRight>{item.stock}</TableCell>
                <TableCell alignRight>{item.price}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </>
</TableHeaderCell>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alignRight` | `boolean` |  |  |
| `columnId` | `string` |  | Identifies the column so it can be pinned. Use the same id on the header and its cells. |
| `pinnable` | `boolean` |  |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-table--default)
- [Link Rows](/storybook/?path=/story/containers-table--link-rows)
- [Empty](/storybook/?path=/story/containers-table--empty)
- [PinnedColumns](/storybook/?path=/story/containers-table--pinned-left-and-right)
- [User Pinning](/storybook/?path=/story/containers-table--user-pinning)
- [Controlled Pinning](/storybook/?path=/story/containers-table--controlled-pinning)
- [Narrow](/storybook/?path=/story/containers-table--narrow)

## Source

`packages/ui/src/containers/table/table.tsx`

---

# TableLinkRow

> Fully navigable table row: the real link lives in the first cell and, via a stretched link (positioned `<tr>` + anchor `::before` at `inset-0`), its click area covers the whole ro…

Source: https://ui.jcsoftdev.com/docs/components/table-link-row

Fully navigable table row: the real link lives in the first cell and, via a
stretched link (positioned `<tr>` + anchor `::before` at `inset-0`), its
click area covers the whole row without duplicating the link per cell.

## Import

```ts
import { TableLinkRow } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/table`.

## Usage

```tsx
<TableLinkRow aria-label="Inventario de productos">
  <>
          <TableHead>
            <tr>
              <TableHeaderCell>Producto</TableHeaderCell>
              <TableHeaderCell>SKU</TableHeaderCell>
              <TableHeaderCell alignRight>Stock</TableHeaderCell>
              <TableHeaderCell alignRight>Precio</TableHeaderCell>
            </tr>
          </TableHead>
          <TableBody>
            {inventory.map((item) => (
              <TableRow key={item.sku}>
                <TableCell>
                  {item.name} {item.low ? <Chip tone="danger">Stock bajo</Chip> : null}
                </TableCell>
                <TableCell>{item.sku}</TableCell>
                <TableCell alignRight>{item.stock}</TableCell>
                <TableCell alignRight>{item.price}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </>
</TableLinkRow>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` * | `string` |  | Row destination: rendered as a real `<a href>` in the first cell. |
| `primary` * | `ReactNode` |  | Content of the first cell, wrapped by the anchor. |
| `primaryColumnId` | `string` |  | `columnId` of the first cell, so that column can be pinned. |
| `children` | `ReactNode` |  | Additional `<td>` cells of the row. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-table--default)
- [Link Rows](/storybook/?path=/story/containers-table--link-rows)
- [Empty](/storybook/?path=/story/containers-table--empty)
- [PinnedColumns](/storybook/?path=/story/containers-table--pinned-left-and-right)
- [User Pinning](/storybook/?path=/story/containers-table--user-pinning)
- [Controlled Pinning](/storybook/?path=/story/containers-table--controlled-pinning)
- [Narrow](/storybook/?path=/story/containers-table--narrow)

## Source

`packages/ui/src/containers/table/table.tsx`

---

# TableRow

> `TableRow` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

Source: https://ui.jcsoftdev.com/docs/components/table-row

`TableRow` is part of the Containers set, imported from `@jcsoftdev/ui/containers`.

## Import

```ts
import { TableRow } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/table`.

## Usage

```tsx
<TableRow aria-label="Inventario de productos">
  <>
          <TableHead>
            <tr>
              <TableHeaderCell>Producto</TableHeaderCell>
              <TableHeaderCell>SKU</TableHeaderCell>
              <TableHeaderCell alignRight>Stock</TableHeaderCell>
              <TableHeaderCell alignRight>Precio</TableHeaderCell>
            </tr>
          </TableHead>
          <TableBody>
            {inventory.map((item) => (
              <TableRow key={item.sku}>
                <TableCell>
                  {item.name} {item.low ? <Chip tone="danger">Stock bajo</Chip> : null}
                </TableCell>
                <TableCell>{item.sku}</TableCell>
                <TableCell alignRight>{item.stock}</TableCell>
                <TableCell alignRight>{item.price}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </>
</TableRow>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-table--default)
- [Link Rows](/storybook/?path=/story/containers-table--link-rows)
- [Empty](/storybook/?path=/story/containers-table--empty)
- [PinnedColumns](/storybook/?path=/story/containers-table--pinned-left-and-right)
- [User Pinning](/storybook/?path=/story/containers-table--user-pinning)
- [Controlled Pinning](/storybook/?path=/story/containers-table--controlled-pinning)
- [Narrow](/storybook/?path=/story/containers-table--narrow)

## Source

`packages/ui/src/containers/table/table.tsx`

---

# Timeline

> Vertical activity feed: marker rail on the left, grouped by day, newest first by convention.

Source: https://ui.jcsoftdev.com/docs/components/timeline

Vertical activity feed: marker rail on the left, grouped by day, newest first by convention.

## Import

```ts
import { Timeline } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/timeline`.

## Usage

```tsx
<Timeline items={items} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` * | `TimelineFeedItem[]` |  |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-timeline--default)
- [Ungrouped](/storybook/?path=/story/containers-timeline--ungrouped)
- [Narrow](/storybook/?path=/story/containers-timeline--narrow)
- [Brutal Preset](/storybook/?path=/story/containers-timeline--brutal-preset)

## Source

`packages/ui/src/containers/timeline/timeline.tsx`

---

# Toolbar

> Row of filters/controls above a table or grid.

Source: https://ui.jcsoftdev.com/docs/components/toolbar

Row of filters/controls above a table or grid.

## Import

```ts
import { Toolbar } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/toolbar`.

## Usage

```tsx
<Toolbar>
  <>
          <Button size="sm" variant="secondary">
            Todos los barberos
          </Button>
          <Button size="sm" variant="ghost">
            Hoy
          </Button>
          <ToolbarRight>
            <Chip tone="neutral">12 citas</Chip>
            <Button size="sm">Nueva cita</Button>
          </ToolbarRight>
        </>
</Toolbar>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-toolbar--default)
- [Filters Only](/storybook/?path=/story/containers-toolbar--filters-only)
- [Narrow](/storybook/?path=/story/containers-toolbar--narrow)

## Source

`packages/ui/src/containers/toolbar/toolbar.tsx`

---

# ToolbarRight

> Group pushed to the right edge of the toolbar.

Source: https://ui.jcsoftdev.com/docs/components/toolbar-right

Group pushed to the right edge of the toolbar.

## Import

```ts
import { ToolbarRight } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/toolbar`.

## Usage

```tsx
<ToolbarRight>
  <>
          <Button size="sm" variant="secondary">
            Todos los barberos
          </Button>
          <Button size="sm" variant="ghost">
            Hoy
          </Button>
          <ToolbarRight>
            <Chip tone="neutral">12 citas</Chip>
            <Button size="sm">Nueva cita</Button>
          </ToolbarRight>
        </>
</ToolbarRight>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-toolbar--default)
- [Filters Only](/storybook/?path=/story/containers-toolbar--filters-only)
- [Narrow](/storybook/?path=/story/containers-toolbar--narrow)

## Source

`packages/ui/src/containers/toolbar/toolbar.tsx`

---

# AccentPicker

> Exclusive swatch picker.

Source: https://ui.jcsoftdev.com/docs/components/accent-picker

Exclusive swatch picker. Controlled or uncontrolled; the root exposes
`data-accent` with the active option so consumers can read it. Applying the
value to the document is the consumer's responsibility.

## Import

```ts
import { AccentPicker } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/accent-picker`.

## Usage

```tsx
<AccentPicker
  options={options}
  defaultValue="coral"
  aria-label="Color de la barbería"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` * | `AccentOption[]` |  |  |
| `value` | `string` |  |  |
| `defaultValue` | `string` |  |  |
| `onValueChange` | `((value: string) => void)` |  |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/forms-accentpicker--default)
- [Disabled](/storybook/?path=/story/forms-accentpicker--disabled)
- [Controlled](/storybook/?path=/story/forms-accentpicker--controlled)

## Source

`packages/ui/src/forms/accent-picker/accent-picker.tsx`

---

# CheckboxButtonGroup

> Multi-select where each option is a button-like card; native checkboxes underneath.

Source: https://ui.jcsoftdev.com/docs/components/checkbox-button-group

Multi-select where each option is a button-like card; native checkboxes underneath.

## Import

```ts
import { CheckboxButtonGroup } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/checkbox-button-group`.

## Usage

```tsx
<CheckboxButtonGroup
  options={options}
  defaultValue={["corte"]}
  aria-label="Servicios"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` * | `ButtonOption[]` |  |  |
| `value` | `string[]` |  |  |
| `defaultValue` | `string[]` | `[]` |  |
| `onValueChange` | `((value: string[]) => void)` |  |  |
| `name` | `string` |  | Form field name shared by the checkboxes. |
| `disabled` | `boolean` |  |  |
| `aria-label` | `string` |  |  |
| `aria-labelledby` | `string` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/forms-checkboxbuttongroup--default)
- [Disabled](/storybook/?path=/story/forms-checkboxbuttongroup--disabled)
- [Narrow](/storybook/?path=/story/forms-checkboxbuttongroup--narrow)
- [Brutal Preset](/storybook/?path=/story/forms-checkboxbuttongroup--brutal-preset)

## Source

`packages/ui/src/forms/checkbox-button-group/checkbox-button-group.tsx`

---

# Dropzone

> `Dropzone` is part of the Forms set, imported from `@jcsoftdev/ui/forms`.

Source: https://ui.jcsoftdev.com/docs/components/dropzone

`Dropzone` is part of the Forms set, imported from `@jcsoftdev/ui/forms`.

## Import

```ts
import { Dropzone } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/dropzone`.

## Usage

```tsx
<Dropzone
  title="Arrastra la foto del corte"
  hint="PNG o JPG, máximo 2 MB"
  browseLabel="Elegir archivo"
  acceptedTypes={["image/*"]}
  maxSizeBytes={2 * 1024 * 1024}
  multiple
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onFiles` * | `(files: File[]) => void` |  |  |
| `onReject` | `((rejections: DropzoneRejection[]) => void)` |  | Called with the rejected files; the caller composes the user-facing message. |
| `acceptedTypes` | `string[]` |  | Accepted MIME types; supports wildcards such as `image/*`. |
| `maxSizeBytes` | `number` |  |  |
| `multiple` | `boolean` | `true` |  |
| `title` * | `string` |  |  |
| `hint` | `string` |  |  |
| `browseLabel` * | `string` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/forms-dropzone--default)
- [Single File](/storybook/?path=/story/forms-dropzone--single-file)
- [Only Pdf](/storybook/?path=/story/forms-dropzone--only-pdf)
- [With Feedback](/storybook/?path=/story/forms-dropzone--with-feedback)
- [Narrow](/storybook/?path=/story/forms-dropzone--narrow)

## Source

`packages/ui/src/forms/dropzone/dropzone.tsx`

---

# EmojiPicker

> Emoji panel with search, category tabs and a keyboard-navigable grid (arrows, Home/End; Enter or Space picks).

Source: https://ui.jcsoftdev.com/docs/components/emoji-picker

Emoji panel with search, category tabs and a keyboard-navigable grid (arrows, Home/End; Enter or
Space picks). The panel adapts to its container width and holds no portal, so it works inline or
inside a popover.

## Import

```ts
import { EmojiPicker } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/emoji-picker`.

## Usage

```tsx
export const Default: Story = { render: () => <WithPreview /> };
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSelect` | `((emoji: string) => void)` |  |  |
| `categories` | `EmojiCategory[]` | `EMOJI_CATEGORIES` | Replaces the built-in dataset (`EMOJI_CATEGORIES`). |
| `defaultCategory` | `string` |  | Initial category id. |
| `searchPlaceholder` | `string` | `"Buscar emoji"` |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/forms-emojipicker--default)
- [Narrow](/storybook/?path=/story/forms-emojipicker--narrow)
- [Brutal Preset](/storybook/?path=/story/forms-emojipicker--brutal-preset)

## Source

`packages/ui/src/forms/emoji-picker/emoji-picker.tsx`

---

# EmojiReactionBar

> Row of reaction chips plus an "add reaction" button that opens an emoji picker.

Source: https://ui.jcsoftdev.com/docs/components/emoji-reaction-bar

Row of reaction chips plus an "add reaction" button that opens an emoji picker.

## Import

```ts
import { EmojiReactionBar } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/emoji-reaction-button`.

## Usage

```tsx
<EmojiReactionBar emoji="🔥" count={7} reacted={false} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `reactions` * | `Reaction[]` |  |  |
| `onReact` | `((emoji: string, reacted: boolean) => void)` |  | Called with the emoji and the new reacted state, from a chip or from the picker. |
| `container` | `HTMLElement \| null` |  | Portal target for the picker; pass an element to keep a scoped `data-style`. |
| `addLabel` | `string` | `"Añadir reacción"` |  |
| `disabled` | `boolean` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/forms-emojireactionbutton--default)
- [Reacted](/storybook/?path=/story/forms-emojireactionbutton--reacted)
- [With Picker](/storybook/?path=/story/forms-emojireactionbutton--with-picker)
- [Narrow](/storybook/?path=/story/forms-emojireactionbutton--narrow)
- [Brutal Preset](/storybook/?path=/story/forms-emojireactionbutton--brutal-preset)

## Source

`packages/ui/src/forms/emoji-reaction-button/emoji-reaction-button.tsx`

---

# EmojiReactionButton

> Reaction chip: an emoji with its count, pressed when the current user reacted.

Source: https://ui.jcsoftdev.com/docs/components/emoji-reaction-button

Reaction chip: an emoji with its count, pressed when the current user reacted.

## Import

```ts
import { EmojiReactionButton } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/emoji-reaction-button`.

## Usage

```tsx
<EmojiReactionButton emoji="🔥" count={7} reacted={false} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `emoji` * | `string` |  |  |
| `count` * | `number` |  |  |
| `reacted` | `boolean` | `false` | Whether the current user has used this reaction. |
| `onToggle` | `((reacted: boolean) => void)` |  |  |
| `disabled` | `boolean` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/forms-emojireactionbutton--default)
- [Reacted](/storybook/?path=/story/forms-emojireactionbutton--reacted)
- [With Picker](/storybook/?path=/story/forms-emojireactionbutton--with-picker)
- [Narrow](/storybook/?path=/story/forms-emojireactionbutton--narrow)
- [Brutal Preset](/storybook/?path=/story/forms-emojireactionbutton--brutal-preset)

## Source

`packages/ui/src/forms/emoji-reaction-button/emoji-reaction-button.tsx`

---

# Field

> `Field` is part of the Forms set, imported from `@jcsoftdev/ui/forms`.

Source: https://ui.jcsoftdev.com/docs/components/field

`Field` is part of the Forms set, imported from `@jcsoftdev/ui/forms`.

## Import

```ts
import { Field } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/field`.

## Usage

```tsx
<Field
  label="Nombre del cliente"
  hint="Como aparecerá en la agenda"
>
  <Input placeholder="Ej. Marco Salazar" />
</Field>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` * | `string` |  |  |
| `hint` | `string` |  |  |
| `error` | `string` |  |  |
| `id` | `string` |  |  |
| `children` * | `ReactElement<ControlProps, string \| React.JSXElementConstructor<any>>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/forms-field--default)
- [With Error](/storybook/?path=/story/forms-field--with-error)
- [Hint And Error](/storybook/?path=/story/forms-field--hint-and-error)
- [With Select](/storybook/?path=/story/forms-field--with-select)
- [With Textarea](/storybook/?path=/story/forms-field--with-textarea)
- [Controlled Form](/storybook/?path=/story/forms-field--controlled-form)

## Source

`packages/ui/src/forms/field/field.tsx`

---

# FormGrid

> Grid for pairs of fields.

Source: https://ui.jcsoftdev.com/docs/components/form-grid

Grid for pairs of fields. One column in a narrow container, two columns from 620px of
container width (the wrapper is the size container; the grid keeps `className` and props).

## Import

```ts
import { FormGrid } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/form-grid`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <FormGrid {...args}>
      <Field label="Nombre">
        <Input placeholder="Marco" />
      </Field>
      <Field label="Apellido">
        <Input placeholder="Salazar" />
      </Field>
      <Field label="Teléfono">
        <Input type="tel" placeholder="987 654 321" />
      </Field>
      <Field label="Barbero">
        <Select>
          <option>Diego Quispe</option>
          <option>Luis Paredes</option>
        </Select>
      </Field>
    </FormGrid>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/forms-formgrid--default)
- [New Appointment](/storybook/?path=/story/forms-formgrid--new-appointment)
- [Narrow](/storybook/?path=/story/forms-formgrid--narrow)

## Source

`packages/ui/src/forms/form-grid/form-grid.tsx`

---

# InlineSelect

> Borderless select that reads as part of a sentence or a row ("Repetir cada [semana v]").

Source: https://ui.jcsoftdev.com/docs/components/inline-select

Borderless select that reads as part of a sentence or a row ("Repetir cada [semana v]").
Native `<select>` underneath, so the system picker and keyboard behaviour are kept.

## Import

```ts
import { InlineSelect } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/inline-select`.

## Usage

```tsx
export const Default: Story = {};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` * | `InlineSelectOption[]` |  |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/forms-inlineselect--default)
- [Disabled](/storybook/?path=/story/forms-inlineselect--disabled)
- [Narrow](/storybook/?path=/story/forms-inlineselect--narrow)
- [Brutal Preset](/storybook/?path=/story/forms-inlineselect--brutal-preset)

## Source

`packages/ui/src/forms/inline-select/inline-select.tsx`

---

# Input

> `Input` is part of the Forms set, imported from `@jcsoftdev/ui/forms`.

Source: https://ui.jcsoftdev.com/docs/components/input

`Input` is part of the Forms set, imported from `@jcsoftdev/ui/forms`.

## Import

```ts
import { Input } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/input`.

## Usage

```tsx
<Input
  placeholder="Ej. Marco Salazar"
  aria-label="Nombre del cliente"
/>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/forms-input--default)
- [With Value](/storybook/?path=/story/forms-input--with-value)
- [Telephone](/storybook/?path=/story/forms-input--telephone)
- [Invalid](/storybook/?path=/story/forms-input--invalid)
- [Disabled](/storybook/?path=/story/forms-input--disabled)
- [Read Only](/storybook/?path=/story/forms-input--read-only)

## Source

`packages/ui/src/forms/input/input.tsx`

---

# InputIcon

> `InputIcon` is part of the Forms set, imported from `@jcsoftdev/ui/forms`.

Source: https://ui.jcsoftdev.com/docs/components/input-icon

`InputIcon` is part of the Forms set, imported from `@jcsoftdev/ui/forms`.

## Import

```ts
import { InputIcon } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/input-icon`.

## Usage

```tsx
<InputIcon
  icon={<Search />}
  placeholder="Buscar cliente o servicio"
  aria-label="Buscar"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` * | `ReactNode` |  | Leading icon element (e.g. a lucide-react icon). |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/forms-inputicon--default)
- [Telephone](/storybook/?path=/story/forms-inputicon--telephone)
- [Invalid](/storybook/?path=/story/forms-inputicon--invalid)
- [Disabled](/storybook/?path=/story/forms-inputicon--disabled)

## Source

`packages/ui/src/forms/input-icon/input-icon.tsx`

---

# Label

> `Label` is part of the Forms set, imported from `@jcsoftdev/ui/forms`.

Source: https://ui.jcsoftdev.com/docs/components/label

`Label` is part of the Forms set, imported from `@jcsoftdev/ui/forms`.

## Import

```ts
import { Label } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/label`.

## Usage

```tsx
<Label htmlFor="cliente">
  Nombre del cliente
</Label>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/forms-label--default)
- [Servicio](/storybook/?path=/story/forms-label--servicio)

## Source

`packages/ui/src/forms/label/label.tsx`

---

# NativeSelect

> Styled native `<select>` (keeps the system picker on touch devices).

Source: https://ui.jcsoftdev.com/docs/components/native-select

Styled native `<select>` (keeps the system picker on touch devices). It extends the existing
`Select` styling with a data-driven `options` API, optgroups, a placeholder and a compact size.

## Import

```ts
import { NativeSelect } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/native-select`.

## Usage

```tsx
<NativeSelect
  options={options}
  placeholder="Elige un barbero"
  aria-label="Barbero"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `(NativeSelectOption \| NativeSelectGroup)[]` |  | Data-driven alternative to `<option>` children; groups render as `<optgroup>`. |
| `placeholder` | `string` |  | Disabled first option shown while nothing is chosen. |
| `size` | `"sm" \| "md"` | `"md"` |  |
| `invalid` | `boolean` |  |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/forms-nativeselect--default)
- [Small](/storybook/?path=/story/forms-nativeselect--small)
- [Invalid](/storybook/?path=/story/forms-nativeselect--invalid)
- [Narrow](/storybook/?path=/story/forms-nativeselect--narrow)
- [Brutal Preset](/storybook/?path=/story/forms-nativeselect--brutal-preset)

## Source

`packages/ui/src/forms/native-select/native-select.tsx`

---

# NumberStepper

> Counter with minus/plus buttons and a typeable value; ArrowUp/ArrowDown step it, Home/End jump.

Source: https://ui.jcsoftdev.com/docs/components/number-stepper

Counter with minus/plus buttons and a typeable value; ArrowUp/ArrowDown step it, Home/End jump.

## Import

```ts
import { NumberStepper } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/number-stepper`.

## Usage

```tsx
<NumberStepper
  defaultValue={2}
  min={0}
  max={10}
  step={1}
  aria-label="Cantidad de productos"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` |  |  |
| `defaultValue` | `number` | `0` |  |
| `onValueChange` | `((value: number) => void)` |  |  |
| `min` | `number` | `Number.NEGATIVE_INFINITY` |  |
| `max` | `number` | `Number.POSITIVE_INFINITY` |  |
| `step` | `number` | `1` |  |
| `disabled` | `boolean` |  |  |
| `unit` | `string` |  | Text after the number, e.g. "min" or "unid."; read by screen readers through aria-valuetext. |
| `name` | `string` |  |  |
| `aria-label` | `string` |  |  |
| `aria-labelledby` | `string` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/forms-numberstepper--default)
- [With Unit](/storybook/?path=/story/forms-numberstepper--with-unit)
- [Decimals](/storybook/?path=/story/forms-numberstepper--decimals)
- [Disabled](/storybook/?path=/story/forms-numberstepper--disabled)
- [Controlled Value](/storybook/?path=/story/forms-numberstepper--controlled-value)
- [Narrow](/storybook/?path=/story/forms-numberstepper--narrow)
- [Brutal Preset](/storybook/?path=/story/forms-numberstepper--brutal-preset)
- [In Shrink Wrap Row](/storybook/?path=/story/forms-numberstepper--in-shrink-wrap-row)

## Source

`packages/ui/src/forms/number-stepper/number-stepper.tsx`

---

# PinInput

> Masked numeric PIN.

Source: https://ui.jcsoftdev.com/docs/components/pin-input

Masked numeric PIN. `autocomplete` is disabled on purpose so browsers do not
mistake it for a one-time code.

## Import

```ts
import { PinInput } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/pin-input`.

## Usage

```tsx
<PinInput length={4} label="PIN del barbero" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `length` | `number` | `4` |  |
| `value` | `string` |  |  |
| `defaultValue` | `string` | `""` |  |
| `onValueChange` | `((value: string) => void)` |  |  |
| `label` | `string` | `"PIN"` | Accessible name of the input. |
| `statusLabel` | `((entered: number, length: number) => string)` | `defaultStatusLabel` | Builds the polite live-region announcement. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/forms-pininput--default)
- [Six Digits](/storybook/?path=/story/forms-pininput--six-digits)
- [Prefilled](/storybook/?path=/story/forms-pininput--prefilled)
- [Spanish Status](/storybook/?path=/story/forms-pininput--spanish-status)
- [Controlled](/storybook/?path=/story/forms-pininput--controlled)
- [Narrow](/storybook/?path=/story/forms-pininput--narrow)

## Source

`packages/ui/src/forms/pin-input/pin-input.tsx`

---

# RadioButtonGroup

> Exclusive choice where each option is a button-like card.

Source: https://ui.jcsoftdev.com/docs/components/radio-button-group

Exclusive choice where each option is a button-like card. Native radios underneath, so arrow
keys, form submission and the `radiogroup` semantics come from the browser. Distinct from
`RadioGroup` (dot indicator) and `Segmented` (2-4 compact options).

## Import

```ts
import { RadioButtonGroup } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/radio-button-group`.

## Usage

```tsx
<RadioButtonGroup
  options={options}
  defaultValue="yape"
  aria-label="Método de pago"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` * | `ButtonOption[]` |  |  |
| `value` | `string` |  |  |
| `defaultValue` | `string` |  |  |
| `onValueChange` | `((value: string) => void)` |  |  |
| `name` | `string` |  |  |
| `disabled` | `boolean` |  |  |
| `aria-label` | `string` |  |  |
| `aria-labelledby` | `string` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/forms-radiobuttongroup--default)
- [Disabled](/storybook/?path=/story/forms-radiobuttongroup--disabled)
- [Narrow](/storybook/?path=/story/forms-radiobuttongroup--narrow)
- [Brutal Preset](/storybook/?path=/story/forms-radiobuttongroup--brutal-preset)

## Source

`packages/ui/src/forms/radio-button-group/radio-button-group.tsx`

---

# Rating

> Star rating.

Source: https://ui.jcsoftdev.com/docs/components/rating

Star rating. Editable ratings are a single `role="slider"` (arrows, Home/End); read-only ones
are an `img` with the value as its label. Half values render as a half-filled star.

## Import

```ts
import { Rating } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/rating`.

## Usage

```tsx
<Rating
  defaultValue={4}
  max={5}
  precision={1}
  size="md"
  aria-label="Valoración del corte"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` |  |  |
| `defaultValue` | `number` | `0` |  |
| `onValueChange` | `((value: number) => void)` |  |  |
| `max` | `number` | `5` |  |
| `precision` | `1 \| 0.5` | `1` | 0.5 allows half stars. |
| `readOnly` | `boolean` |  |  |
| `disabled` | `boolean` |  |  |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` |  |
| `showValue` | `boolean` |  | Shows the numeric value after the stars. |
| `aria-label` | `string` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/forms-rating--default)
- [Half Stars](/storybook/?path=/story/forms-rating--half-stars)
- [Read Only](/storybook/?path=/story/forms-rating--read-only)
- [Sizes](/storybook/?path=/story/forms-rating--sizes)
- [Controlled Value](/storybook/?path=/story/forms-rating--controlled-value)
- [Narrow](/storybook/?path=/story/forms-rating--narrow)
- [Brutal Preset](/storybook/?path=/story/forms-rating--brutal-preset)

## Source

`packages/ui/src/forms/rating/rating.tsx`

---

# Select

> Wraps the native `<select>` (keeps the system picker on mobile) and draws the chevron with an icon.

Source: https://ui.jcsoftdev.com/docs/components/select

Wraps the native `<select>` (keeps the system picker on mobile) and draws
the chevron with an icon.

## Import

```ts
import { Select } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/select`.

## Usage

```tsx
<Select aria-label="Barbero">
  {options}
</Select>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/forms-select--default)
- [With Selection](/storybook/?path=/story/forms-select--with-selection)
- [Invalid](/storybook/?path=/story/forms-select--invalid)
- [Disabled](/storybook/?path=/story/forms-select--disabled)

## Source

`packages/ui/src/forms/select/select.tsx`

---

# Slider

> Single or range slider.

Source: https://ui.jcsoftdev.com/docs/components/slider

Single or range slider. The value shape decides the mode: a number gives one thumb and a
`[from, to]` tuple gives two. Each thumb is a `role="slider"` with arrow, Page and Home/End keys.

## Import

```ts
import { Slider } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/slider`.

## Usage

```tsx
<Slider
  min={0}
  max={100}
  step={5}
  defaultValue={40}
  aria-label="Descuento"
  showValue
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| RangeValue` |  |  |
| `defaultValue` | `number \| RangeValue` |  |  |
| `onValueChange` | `((value: number) => void) \| ((value: RangeValue) => void)` |  |  |
| `min` | `number` |  |  |
| `max` | `number` |  |  |
| `step` | `number` |  |  |
| `pageStep` | `number` |  | Step used by PageUp/PageDown. Defaults to 10 steps. |
| `minGap` | `number` |  | Minimum distance between the two thumbs of a range. |
| `disabled` | `boolean` |  |  |
| `marks` | `SliderMark[]` |  | Ticks on the track; a `label` renders as a caption under it. |
| `showValue` | `boolean` |  | Shows the current value above each thumb; it is emphasized while dragged or focused. |
| `formatValue` | `((value: number) => string)` |  |  |
| `aria-label` | `string` |  | Accessible name; thumbs of a range get "mínimo"/"máximo" appended. |
| `aria-labelledby` | `string` |  |  |
| `name` | `string` |  | Form field name; a range submits `${name}-min` and `${name}-max`. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/forms-slider--default)
- [With Marks](/storybook/?path=/story/forms-slider--with-marks)
- [Range](/storybook/?path=/story/forms-slider--range)
- [Disabled](/storybook/?path=/story/forms-slider--disabled)
- [Controlled Value](/storybook/?path=/story/forms-slider--controlled-value)
- [Narrow](/storybook/?path=/story/forms-slider--narrow)
- [Brutal Preset](/storybook/?path=/story/forms-slider--brutal-preset)

## Source

`packages/ui/src/forms/slider/slider.tsx`

---

# Textarea

> `Textarea` is part of the Forms set, imported from `@jcsoftdev/ui/forms`.

Source: https://ui.jcsoftdev.com/docs/components/textarea

`Textarea` is part of the Forms set, imported from `@jcsoftdev/ui/forms`.

## Import

```ts
import { Textarea } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/textarea`.

## Usage

```tsx
<Textarea
  placeholder="Notas del corte: degradado bajo, barba perfilada..."
  aria-label="Notas"
/>
```

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/forms-textarea--default)
- [With Value](/storybook/?path=/story/forms-textarea--with-value)
- [Invalid](/storybook/?path=/story/forms-textarea--invalid)
- [Disabled](/storybook/?path=/story/forms-textarea--disabled)

## Source

`packages/ui/src/forms/textarea/textarea.tsx`

---

# TimeInput

> 24h time field.

Source: https://ui.jcsoftdev.com/docs/components/time-input

24h time field. A masked text input, so it renders "15:30" whatever the browser
locale is. ArrowUp / ArrowDown change the segment under the caret (minutes move by `step`).

## Import

```ts
import { TimeInput } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/time-input`.

## Usage

```tsx
<TimeInput aria-label="Hora de la cita" defaultValue="15:30" step={5} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | 24h "HH:MM" (controlled). |
| `defaultValue` | `string` | `""` |  |
| `onValueChange` | `((value: string) => void)` |  | Called with a valid "HH:MM" string, or "" when the field is cleared. |
| `step` | `number` | `5` | Minutes added or removed by ArrowUp / ArrowDown on the minutes segment. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/forms-timeinput--default)
- [Empty](/storybook/?path=/story/forms-timeinput--empty)
- [Step 15](/storybook/?path=/story/forms-timeinput--step-15)
- [Invalid](/storybook/?path=/story/forms-timeinput--invalid)
- [Disabled](/storybook/?path=/story/forms-timeinput--disabled)
- [Controlled](/storybook/?path=/story/forms-timeinput--controlled)

## Source

`packages/ui/src/forms/time-input/time-input.tsx`

---

# FloatingToc

> Table of contents that tracks the section being read.

Source: https://ui.jcsoftdev.com/docs/components/floating-toc

Table of contents that tracks the section being read. An IntersectionObserver watches the
top band of the scroll area; the first heading inside it is current (`aria-current="location"`).

## Import

```ts
import { FloatingToc } from "@jcsoftdev/ui/navigation";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/navigation/floating-toc`.

## Usage

```tsx
export const Default: Story = { render: () => <Article /> };
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` * | `TocItem[]` |  |  |
| `title` | `string` | `"En esta página"` | Heading shown above the list. |
| `scrollRoot` | `RefObject<HTMLElement \| null>` |  | Scroll container that holds the headings. Omit to observe the viewport. Pass a ref (not the element) so it can be resolved after mount. |
| `onActiveChange` | `((id: string \| null) => void)` |  | Called when the active section changes. |
| `offsetTop` | `number` | `0` | Pixels reserved at the top (sticky headers) when jumping to a section. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/navigation-floatingtoc--default)
- [Narrow](/storybook/?path=/story/navigation-floatingtoc--narrow)
- [Brutal Preset](/storybook/?path=/story/navigation-floatingtoc--brutal-preset)

## Source

`packages/ui/src/navigation/floating-toc/floating-toc.tsx`

---

# Segmented

> Exclusive selector for 2-4 options.

Source: https://ui.jcsoftdev.com/docs/components/segmented

Exclusive selector for 2-4 options. `type="single"` gives Radix the `radiogroup` role.

## Import

```ts
import { Segmented } from "@jcsoftdev/ui/navigation";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/navigation/segmented`.

## Usage

```tsx
export const Default: Story = {};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/navigation-segmented--default)
- [Disabled](/storybook/?path=/story/navigation-segmented--disabled)
- [Two Options](/storybook/?path=/story/navigation-segmented--two-options)
- [One Item Disabled](/storybook/?path=/story/navigation-segmented--one-item-disabled)
- [Controlled](/storybook/?path=/story/navigation-segmented--controlled)
- [Narrow](/storybook/?path=/story/navigation-segmented--narrow)

## Source

`packages/ui/src/navigation/segmented/segmented.tsx`

---

# SegmentedItem

> `SegmentedItem` is part of the Navigation set, imported from `@jcsoftdev/ui/navigation`.

Source: https://ui.jcsoftdev.com/docs/components/segmented-item

`SegmentedItem` is part of the Navigation set, imported from `@jcsoftdev/ui/navigation`.

## Import

```ts
import { SegmentedItem } from "@jcsoftdev/ui/navigation";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/navigation/segmented`.

## Usage

```tsx
export const Default: Story = {};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/navigation-segmented--default)
- [Disabled](/storybook/?path=/story/navigation-segmented--disabled)
- [Two Options](/storybook/?path=/story/navigation-segmented--two-options)
- [One Item Disabled](/storybook/?path=/story/navigation-segmented--one-item-disabled)
- [Controlled](/storybook/?path=/story/navigation-segmented--controlled)
- [Narrow](/storybook/?path=/story/navigation-segmented--narrow)

## Source

`packages/ui/src/navigation/segmented/segmented.tsx`

---

# Stepper

> Step 1-N indicator for multi-stage flows.

Source: https://ui.jcsoftdev.com/docs/components/stepper

Step 1-N indicator for multi-stage flows.

## Import

```ts
import { Stepper } from "@jcsoftdev/ui/navigation";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/navigation/stepper`.

## Usage

```tsx
<Stepper steps={steps} currentStepId="barbero" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` * | `Step[]` |  |  |
| `currentStepId` * | `string` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/navigation-stepper--default)
- [First Step](/storybook/?path=/story/navigation-stepper--first-step)
- [Last Step](/storybook/?path=/story/navigation-stepper--last-step)
- [Three Steps](/storybook/?path=/story/navigation-stepper--three-steps)
- [Narrow](/storybook/?path=/story/navigation-stepper--narrow)

## Source

`packages/ui/src/navigation/stepper/stepper.tsx`

---

# Tabs

> To sync the active tab with a search param, use Radix's controlled pattern: `value={param}` + `onValueChange={(v) => updateParam(v)}`.

Source: https://ui.jcsoftdev.com/docs/components/tabs

To sync the active tab with a search param, use Radix's controlled pattern:
`value={param}` + `onValueChange={(v) => updateParam(v)}`.

## Import

```ts
import { Tabs } from "@jcsoftdev/ui/navigation";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/navigation/tabs`.

## Usage

```tsx
export const Default: Story = {};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/navigation-tabs--default)
- [With Counts](/storybook/?path=/story/navigation-tabs--with-counts)
- [Disabled Tab](/storybook/?path=/story/navigation-tabs--disabled-tab)
- [Controlled](/storybook/?path=/story/navigation-tabs--controlled)
- [Narrow](/storybook/?path=/story/navigation-tabs--narrow)

## Source

`packages/ui/src/navigation/tabs/tabs.tsx`

---

# TabsContent

> `TabsContent` is part of the Navigation set, imported from `@jcsoftdev/ui/navigation`.

Source: https://ui.jcsoftdev.com/docs/components/tabs-content

`TabsContent` is part of the Navigation set, imported from `@jcsoftdev/ui/navigation`.

## Import

```ts
import { TabsContent } from "@jcsoftdev/ui/navigation";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/navigation/tabs`.

## Usage

```tsx
export const Default: Story = {};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/navigation-tabs--default)
- [With Counts](/storybook/?path=/story/navigation-tabs--with-counts)
- [Disabled Tab](/storybook/?path=/story/navigation-tabs--disabled-tab)
- [Controlled](/storybook/?path=/story/navigation-tabs--controlled)
- [Narrow](/storybook/?path=/story/navigation-tabs--narrow)

## Source

`packages/ui/src/navigation/tabs/tabs.tsx`

---

# TabsList

> `TabsList` is part of the Navigation set, imported from `@jcsoftdev/ui/navigation`.

Source: https://ui.jcsoftdev.com/docs/components/tabs-list

`TabsList` is part of the Navigation set, imported from `@jcsoftdev/ui/navigation`.

## Import

```ts
import { TabsList } from "@jcsoftdev/ui/navigation";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/navigation/tabs`.

## Usage

```tsx
export const Default: Story = {};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/navigation-tabs--default)
- [With Counts](/storybook/?path=/story/navigation-tabs--with-counts)
- [Disabled Tab](/storybook/?path=/story/navigation-tabs--disabled-tab)
- [Controlled](/storybook/?path=/story/navigation-tabs--controlled)
- [Narrow](/storybook/?path=/story/navigation-tabs--narrow)

## Source

`packages/ui/src/navigation/tabs/tabs.tsx`

---

# TabsTrigger

> `TabsTrigger` is part of the Navigation set, imported from `@jcsoftdev/ui/navigation`.

Source: https://ui.jcsoftdev.com/docs/components/tabs-trigger

`TabsTrigger` is part of the Navigation set, imported from `@jcsoftdev/ui/navigation`.

## Import

```ts
import { TabsTrigger } from "@jcsoftdev/ui/navigation";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/navigation/tabs`.

## Usage

```tsx
export const Default: Story = {};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` |  | Optional record count shown after the label. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/navigation-tabs--default)
- [With Counts](/storybook/?path=/story/navigation-tabs--with-counts)
- [Disabled Tab](/storybook/?path=/story/navigation-tabs--disabled-tab)
- [Controlled](/storybook/?path=/story/navigation-tabs--controlled)
- [Narrow](/storybook/?path=/story/navigation-tabs--narrow)

## Source

`packages/ui/src/navigation/tabs/tabs.tsx`

---

# ContextMenu

> Menu opened by right-click, long-press or the keyboard (Menu key, Shift+F10) on its trigger area.

Source: https://ui.jcsoftdev.com/docs/components/context-menu

Menu opened by right-click, long-press or the keyboard (Menu key, Shift+F10) on its trigger
area. It reuses the dropdown-menu primitive anchored to the pointer, so roving focus,
typeahead, submenu keys, Escape and collision handling come for free.

## Import

```ts
import { ContextMenu } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/context-menu`.

## Usage

```tsx
export const Default: Story = {
  render: () => (
    <div className="w-full max-w-md">
      <Area />
    </div>
  ),
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` * | `ReactNode` |  |  |
| `onOpenChange` | `((open: boolean) => void)` |  |  |
| `defaultOpen` | `boolean` | `false` | Starts open, anchored at `position` (viewport pixels). Useful for docs and visual tests. |
| `position` | `{ x: number; y: number; }` |  | Initial anchor point in viewport pixels. Defaults to the origin until the first right-click. |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/overlays-contextmenu--default)
- [Narrow](/storybook/?path=/story/overlays-contextmenu--narrow)
- [Brutal Preset](/storybook/?path=/story/overlays-contextmenu--brutal-preset)
- [Open By Default](/storybook/?path=/story/overlays-contextmenu--open-by-default)

## Source

`packages/ui/src/overlays/context-menu/context-menu.tsx`

---

# ContextMenuCheckboxItem

> `ContextMenuCheckboxItem` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/context-menu-checkbox-item

`ContextMenuCheckboxItem` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { ContextMenuCheckboxItem } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/context-menu`.

## Usage

```tsx
export const Default: Story = {
  render: () => (
    <div className="w-full max-w-md">
      <Area />
    </div>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-contextmenu--default)
- [Narrow](/storybook/?path=/story/overlays-contextmenu--narrow)
- [Brutal Preset](/storybook/?path=/story/overlays-contextmenu--brutal-preset)
- [Open By Default](/storybook/?path=/story/overlays-contextmenu--open-by-default)

## Source

`packages/ui/src/overlays/context-menu/context-menu.tsx`

---

# ContextMenuContent

> `ContextMenuContent` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/context-menu-content

`ContextMenuContent` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { ContextMenuContent } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/context-menu`.

## Usage

```tsx
export const Default: Story = {
  render: () => (
    <div className="w-full max-w-md">
      <Area />
    </div>
  ),
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| null` |  | Portal target. Defaults to `document.body`; pass an element to keep a scoped `data-style`. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-contextmenu--default)
- [Narrow](/storybook/?path=/story/overlays-contextmenu--narrow)
- [Brutal Preset](/storybook/?path=/story/overlays-contextmenu--brutal-preset)
- [Open By Default](/storybook/?path=/story/overlays-contextmenu--open-by-default)

## Source

`packages/ui/src/overlays/context-menu/context-menu.tsx`

---

# ContextMenuItem

> `ContextMenuItem` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/context-menu-item

`ContextMenuItem` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { ContextMenuItem } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/context-menu`.

## Usage

```tsx
export const Default: Story = {
  render: () => (
    <div className="w-full max-w-md">
      <Area />
    </div>
  ),
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"danger" \| "default"` | `"default"` | Destructive action styling. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-contextmenu--default)
- [Narrow](/storybook/?path=/story/overlays-contextmenu--narrow)
- [Brutal Preset](/storybook/?path=/story/overlays-contextmenu--brutal-preset)
- [Open By Default](/storybook/?path=/story/overlays-contextmenu--open-by-default)

## Source

`packages/ui/src/overlays/context-menu/context-menu.tsx`

---

# ContextMenuLabel

> `ContextMenuLabel` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/context-menu-label

`ContextMenuLabel` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { ContextMenuLabel } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/context-menu`.

## Usage

```tsx
export const Default: Story = {
  render: () => (
    <div className="w-full max-w-md">
      <Area />
    </div>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-contextmenu--default)
- [Narrow](/storybook/?path=/story/overlays-contextmenu--narrow)
- [Brutal Preset](/storybook/?path=/story/overlays-contextmenu--brutal-preset)
- [Open By Default](/storybook/?path=/story/overlays-contextmenu--open-by-default)

## Source

`packages/ui/src/overlays/context-menu/context-menu.tsx`

---

# ContextMenuSeparator

> `ContextMenuSeparator` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/context-menu-separator

`ContextMenuSeparator` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { ContextMenuSeparator } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/context-menu`.

## Usage

```tsx
export const Default: Story = {
  render: () => (
    <div className="w-full max-w-md">
      <Area />
    </div>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-contextmenu--default)
- [Narrow](/storybook/?path=/story/overlays-contextmenu--narrow)
- [Brutal Preset](/storybook/?path=/story/overlays-contextmenu--brutal-preset)
- [Open By Default](/storybook/?path=/story/overlays-contextmenu--open-by-default)

## Source

`packages/ui/src/overlays/context-menu/context-menu.tsx`

---

# ContextMenuShortcut

> Right-aligned hint such as "Ctrl+D"; purely visual.

Source: https://ui.jcsoftdev.com/docs/components/context-menu-shortcut

Right-aligned hint such as "Ctrl+D"; purely visual.

## Import

```ts
import { ContextMenuShortcut } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/context-menu`.

## Usage

```tsx
export const Default: Story = {
  render: () => (
    <div className="w-full max-w-md">
      <Area />
    </div>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-contextmenu--default)
- [Narrow](/storybook/?path=/story/overlays-contextmenu--narrow)
- [Brutal Preset](/storybook/?path=/story/overlays-contextmenu--brutal-preset)
- [Open By Default](/storybook/?path=/story/overlays-contextmenu--open-by-default)

## Source

`packages/ui/src/overlays/context-menu/context-menu.tsx`

---

# ContextMenuTrigger

> The area that answers to right-click.

Source: https://ui.jcsoftdev.com/docs/components/context-menu-trigger

The area that answers to right-click. Wrap a card, row or canvas.

## Import

```ts
import { ContextMenuTrigger } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/context-menu`.

## Usage

```tsx
export const Default: Story = {
  render: () => (
    <div className="w-full max-w-md">
      <Area />
    </div>
  ),
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` |  |  |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-contextmenu--default)
- [Narrow](/storybook/?path=/story/overlays-contextmenu--narrow)
- [Brutal Preset](/storybook/?path=/story/overlays-contextmenu--brutal-preset)
- [Open By Default](/storybook/?path=/story/overlays-contextmenu--open-by-default)

## Source

`packages/ui/src/overlays/context-menu/context-menu.tsx`

---

# Dialog

> Wraps `DialogPrimitive.Root` so focus is restored on close even when the dialog is opened in a controlled way, without its own `DialogTrigger`.

Source: https://ui.jcsoftdev.com/docs/components/dialog

Wraps `DialogPrimitive.Root` so focus is restored on close even when the
dialog is opened in a controlled way, without its own `DialogTrigger`.

## Import

```ts
import { Dialog } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dialog`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="danger">Anular cita</Button>
      </DialogTrigger>
      <DialogContent {...args}>
        <CancelBody />
      </DialogContent>
    </Dialog>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dialog--default)
- [Open By Default](/storybook/?path=/story/overlays-dialog--open-by-default)
- [Large](/storybook/?path=/story/overlays-dialog--large)
- [Blocking](/storybook/?path=/story/overlays-dialog--blocking)
- [Controlled](/storybook/?path=/story/overlays-dialog--controlled)
- [In Scoped Container](/storybook/?path=/story/overlays-dialog--in-scoped-container)
- [In Scoped Preset](/storybook/?path=/story/overlays-dialog--in-scoped-preset)

## Source

`packages/ui/src/overlays/dialog/dialog.tsx`

---

# DialogBody

> `DialogBody` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/dialog-body

`DialogBody` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DialogBody } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dialog`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="danger">Anular cita</Button>
      </DialogTrigger>
      <DialogContent {...args}>
        <CancelBody />
      </DialogContent>
    </Dialog>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dialog--default)
- [Open By Default](/storybook/?path=/story/overlays-dialog--open-by-default)
- [Large](/storybook/?path=/story/overlays-dialog--large)
- [Blocking](/storybook/?path=/story/overlays-dialog--blocking)
- [Controlled](/storybook/?path=/story/overlays-dialog--controlled)
- [In Scoped Container](/storybook/?path=/story/overlays-dialog--in-scoped-container)
- [In Scoped Preset](/storybook/?path=/story/overlays-dialog--in-scoped-preset)

## Source

`packages/ui/src/overlays/dialog/dialog.tsx`

---

# DialogClose

> `DialogClose` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/dialog-close

`DialogClose` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DialogClose } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dialog`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="danger">Anular cita</Button>
      </DialogTrigger>
      <DialogContent {...args}>
        <CancelBody />
      </DialogContent>
    </Dialog>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dialog--default)
- [Open By Default](/storybook/?path=/story/overlays-dialog--open-by-default)
- [Large](/storybook/?path=/story/overlays-dialog--large)
- [Blocking](/storybook/?path=/story/overlays-dialog--blocking)
- [Controlled](/storybook/?path=/story/overlays-dialog--controlled)
- [In Scoped Container](/storybook/?path=/story/overlays-dialog--in-scoped-container)
- [In Scoped Preset](/storybook/?path=/story/overlays-dialog--in-scoped-preset)

## Source

`packages/ui/src/overlays/dialog/dialog.tsx`

---

# DialogContent

> `DialogContent` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/dialog-content

`DialogContent` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DialogContent } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dialog`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="danger">Anular cita</Button>
      </DialogTrigger>
      <DialogContent {...args}>
        <CancelBody />
      </DialogContent>
    </Dialog>
  ),
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `width` | `"md" \| "lg"` | `"md"` |  |
| `blocking` | `boolean` | `false` | While a mutation is in flight: `Escape`, outside click and the close button are disabled so half-saved state is not lost. |
| `closeLabel` | `string` | `"Close"` | Accessible label of the close button. |
| `container` | `HTMLElement \| null` |  | Portal target. Defaults to `document.body`; pass an element to keep a scoped `data-style`. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dialog--default)
- [Open By Default](/storybook/?path=/story/overlays-dialog--open-by-default)
- [Large](/storybook/?path=/story/overlays-dialog--large)
- [Blocking](/storybook/?path=/story/overlays-dialog--blocking)
- [Controlled](/storybook/?path=/story/overlays-dialog--controlled)
- [In Scoped Container](/storybook/?path=/story/overlays-dialog--in-scoped-container)
- [In Scoped Preset](/storybook/?path=/story/overlays-dialog--in-scoped-preset)

## Source

`packages/ui/src/overlays/dialog/dialog.tsx`

---

# DialogFooter

> `DialogFooter` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/dialog-footer

`DialogFooter` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DialogFooter } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dialog`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="danger">Anular cita</Button>
      </DialogTrigger>
      <DialogContent {...args}>
        <CancelBody />
      </DialogContent>
    </Dialog>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dialog--default)
- [Open By Default](/storybook/?path=/story/overlays-dialog--open-by-default)
- [Large](/storybook/?path=/story/overlays-dialog--large)
- [Blocking](/storybook/?path=/story/overlays-dialog--blocking)
- [Controlled](/storybook/?path=/story/overlays-dialog--controlled)
- [In Scoped Container](/storybook/?path=/story/overlays-dialog--in-scoped-container)
- [In Scoped Preset](/storybook/?path=/story/overlays-dialog--in-scoped-preset)

## Source

`packages/ui/src/overlays/dialog/dialog.tsx`

---

# DialogHeader

> `DialogHeader` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/dialog-header

`DialogHeader` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DialogHeader } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dialog`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="danger">Anular cita</Button>
      </DialogTrigger>
      <DialogContent {...args}>
        <CancelBody />
      </DialogContent>
    </Dialog>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dialog--default)
- [Open By Default](/storybook/?path=/story/overlays-dialog--open-by-default)
- [Large](/storybook/?path=/story/overlays-dialog--large)
- [Blocking](/storybook/?path=/story/overlays-dialog--blocking)
- [Controlled](/storybook/?path=/story/overlays-dialog--controlled)
- [In Scoped Container](/storybook/?path=/story/overlays-dialog--in-scoped-container)
- [In Scoped Preset](/storybook/?path=/story/overlays-dialog--in-scoped-preset)

## Source

`packages/ui/src/overlays/dialog/dialog.tsx`

---

# DialogTitle

> `DialogTitle` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/dialog-title

`DialogTitle` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DialogTitle } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dialog`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="danger">Anular cita</Button>
      </DialogTrigger>
      <DialogContent {...args}>
        <CancelBody />
      </DialogContent>
    </Dialog>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dialog--default)
- [Open By Default](/storybook/?path=/story/overlays-dialog--open-by-default)
- [Large](/storybook/?path=/story/overlays-dialog--large)
- [Blocking](/storybook/?path=/story/overlays-dialog--blocking)
- [Controlled](/storybook/?path=/story/overlays-dialog--controlled)
- [In Scoped Container](/storybook/?path=/story/overlays-dialog--in-scoped-container)
- [In Scoped Preset](/storybook/?path=/story/overlays-dialog--in-scoped-preset)

## Source

`packages/ui/src/overlays/dialog/dialog.tsx`

---

# DialogTrigger

> `DialogTrigger` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/dialog-trigger

`DialogTrigger` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DialogTrigger } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dialog`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="danger">Anular cita</Button>
      </DialogTrigger>
      <DialogContent {...args}>
        <CancelBody />
      </DialogContent>
    </Dialog>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dialog--default)
- [Open By Default](/storybook/?path=/story/overlays-dialog--open-by-default)
- [Large](/storybook/?path=/story/overlays-dialog--large)
- [Blocking](/storybook/?path=/story/overlays-dialog--blocking)
- [Controlled](/storybook/?path=/story/overlays-dialog--controlled)
- [In Scoped Container](/storybook/?path=/story/overlays-dialog--in-scoped-container)
- [In Scoped Preset](/storybook/?path=/story/overlays-dialog--in-scoped-preset)

## Source

`packages/ui/src/overlays/dialog/dialog.tsx`

---

# Drawer

> Wraps `DialogPrimitive.Root` so focus is restored on close even when the drawer is opened in a controlled way, without its own `DrawerTrigger`.

Source: https://ui.jcsoftdev.com/docs/components/drawer

Wraps `DialogPrimitive.Root` so focus is restored on close even when the
drawer is opened in a controlled way, without its own `DrawerTrigger`.

## Import

```ts
import { Drawer } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/drawer`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Drawer>
      <DrawerTrigger asChild>
        <Button variant="secondary">Ver cita</Button>
      </DrawerTrigger>
      <DrawerContent {...args}>
        <AppointmentDetail />
      </DrawerContent>
    </Drawer>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-drawer--default)
- [Open By Default](/storybook/?path=/story/overlays-drawer--open-by-default)
- [With Trigger Open](/storybook/?path=/story/overlays-drawer--with-trigger-open)
- [Blocking](/storybook/?path=/story/overlays-drawer--blocking)
- [Controlled](/storybook/?path=/story/overlays-drawer--controlled)

## Source

`packages/ui/src/overlays/drawer/drawer.tsx`

---

# DrawerClose

> `DrawerClose` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/drawer-close

`DrawerClose` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DrawerClose } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/drawer`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Drawer>
      <DrawerTrigger asChild>
        <Button variant="secondary">Ver cita</Button>
      </DrawerTrigger>
      <DrawerContent {...args}>
        <AppointmentDetail />
      </DrawerContent>
    </Drawer>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-drawer--default)
- [Open By Default](/storybook/?path=/story/overlays-drawer--open-by-default)
- [With Trigger Open](/storybook/?path=/story/overlays-drawer--with-trigger-open)
- [Blocking](/storybook/?path=/story/overlays-drawer--blocking)
- [Controlled](/storybook/?path=/story/overlays-drawer--controlled)

## Source

`packages/ui/src/overlays/drawer/drawer.tsx`

---

# DrawerContent

> Right-anchored side panel for secondary flows.

Source: https://ui.jcsoftdev.com/docs/components/drawer-content

Right-anchored side panel for secondary flows.

## Import

```ts
import { DrawerContent } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/drawer`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Drawer>
      <DrawerTrigger asChild>
        <Button variant="secondary">Ver cita</Button>
      </DrawerTrigger>
      <DrawerContent {...args}>
        <AppointmentDetail />
      </DrawerContent>
    </Drawer>
  ),
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `blocking` | `boolean` | `false` | Same semantics as `DialogContentProps.blocking`. |
| `closeLabel` | `string` | `"Close"` | Accessible label of the close button. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-drawer--default)
- [Open By Default](/storybook/?path=/story/overlays-drawer--open-by-default)
- [With Trigger Open](/storybook/?path=/story/overlays-drawer--with-trigger-open)
- [Blocking](/storybook/?path=/story/overlays-drawer--blocking)
- [Controlled](/storybook/?path=/story/overlays-drawer--controlled)

## Source

`packages/ui/src/overlays/drawer/drawer.tsx`

---

# DrawerTitle

> `DrawerTitle` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/drawer-title

`DrawerTitle` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DrawerTitle } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/drawer`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Drawer>
      <DrawerTrigger asChild>
        <Button variant="secondary">Ver cita</Button>
      </DrawerTrigger>
      <DrawerContent {...args}>
        <AppointmentDetail />
      </DrawerContent>
    </Drawer>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-drawer--default)
- [Open By Default](/storybook/?path=/story/overlays-drawer--open-by-default)
- [With Trigger Open](/storybook/?path=/story/overlays-drawer--with-trigger-open)
- [Blocking](/storybook/?path=/story/overlays-drawer--blocking)
- [Controlled](/storybook/?path=/story/overlays-drawer--controlled)

## Source

`packages/ui/src/overlays/drawer/drawer.tsx`

---

# DrawerTrigger

> `DrawerTrigger` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/drawer-trigger

`DrawerTrigger` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DrawerTrigger } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/drawer`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Drawer>
      <DrawerTrigger asChild>
        <Button variant="secondary">Ver cita</Button>
      </DrawerTrigger>
      <DrawerContent {...args}>
        <AppointmentDetail />
      </DrawerContent>
    </Drawer>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-drawer--default)
- [Open By Default](/storybook/?path=/story/overlays-drawer--open-by-default)
- [With Trigger Open](/storybook/?path=/story/overlays-drawer--with-trigger-open)
- [Blocking](/storybook/?path=/story/overlays-drawer--blocking)
- [Controlled](/storybook/?path=/story/overlays-drawer--controlled)

## Source

`packages/ui/src/overlays/drawer/drawer.tsx`

---

# DropdownMenu

> `DropdownMenu` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/dropdown-menu

`DropdownMenu` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DropdownMenu } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dropdown-menu`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="secondary">Acciones de la cita</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent {...args}>
        <DropdownMenuLabel>Luis Ramírez · 11:30</DropdownMenuLabel>
        <DropdownMenuItem>Reprogramar</DropdownMenuItem>
        <DropdownMenuItem>Cobrar S/ 45</DropdownMenuItem>
        <DropdownMenuItem disabled>Enviar recordatorio</DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem className="text-danger">Anular cita</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dropdownmenu--default)
- [Open By Default](/storybook/?path=/story/overlays-dropdownmenu--open-by-default)
- [Radio Filter](/storybook/?path=/story/overlays-dropdownmenu--radio-filter)

## Source

`packages/ui/src/overlays/dropdown-menu/dropdown-menu.tsx`

---

# DropdownMenuContent

> `DropdownMenuContent` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/dropdown-menu-content

`DropdownMenuContent` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DropdownMenuContent } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dropdown-menu`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="secondary">Acciones de la cita</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent {...args}>
        <DropdownMenuLabel>Luis Ramírez · 11:30</DropdownMenuLabel>
        <DropdownMenuItem>Reprogramar</DropdownMenuItem>
        <DropdownMenuItem>Cobrar S/ 45</DropdownMenuItem>
        <DropdownMenuItem disabled>Enviar recordatorio</DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem className="text-danger">Anular cita</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dropdownmenu--default)
- [Open By Default](/storybook/?path=/story/overlays-dropdownmenu--open-by-default)
- [Radio Filter](/storybook/?path=/story/overlays-dropdownmenu--radio-filter)

## Source

`packages/ui/src/overlays/dropdown-menu/dropdown-menu.tsx`

---

# DropdownMenuItem

> `DropdownMenuItem` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/dropdown-menu-item

`DropdownMenuItem` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DropdownMenuItem } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dropdown-menu`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="secondary">Acciones de la cita</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent {...args}>
        <DropdownMenuLabel>Luis Ramírez · 11:30</DropdownMenuLabel>
        <DropdownMenuItem>Reprogramar</DropdownMenuItem>
        <DropdownMenuItem>Cobrar S/ 45</DropdownMenuItem>
        <DropdownMenuItem disabled>Enviar recordatorio</DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem className="text-danger">Anular cita</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dropdownmenu--default)
- [Open By Default](/storybook/?path=/story/overlays-dropdownmenu--open-by-default)
- [Radio Filter](/storybook/?path=/story/overlays-dropdownmenu--radio-filter)

## Source

`packages/ui/src/overlays/dropdown-menu/dropdown-menu.tsx`

---

# DropdownMenuLabel

> `DropdownMenuLabel` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/dropdown-menu-label

`DropdownMenuLabel` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DropdownMenuLabel } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dropdown-menu`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="secondary">Acciones de la cita</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent {...args}>
        <DropdownMenuLabel>Luis Ramírez · 11:30</DropdownMenuLabel>
        <DropdownMenuItem>Reprogramar</DropdownMenuItem>
        <DropdownMenuItem>Cobrar S/ 45</DropdownMenuItem>
        <DropdownMenuItem disabled>Enviar recordatorio</DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem className="text-danger">Anular cita</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dropdownmenu--default)
- [Open By Default](/storybook/?path=/story/overlays-dropdownmenu--open-by-default)
- [Radio Filter](/storybook/?path=/story/overlays-dropdownmenu--radio-filter)

## Source

`packages/ui/src/overlays/dropdown-menu/dropdown-menu.tsx`

---

# DropdownMenuRadioGroup

> `DropdownMenuRadioGroup` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/dropdown-menu-radio-group

`DropdownMenuRadioGroup` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DropdownMenuRadioGroup } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dropdown-menu`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="secondary">Acciones de la cita</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent {...args}>
        <DropdownMenuLabel>Luis Ramírez · 11:30</DropdownMenuLabel>
        <DropdownMenuItem>Reprogramar</DropdownMenuItem>
        <DropdownMenuItem>Cobrar S/ 45</DropdownMenuItem>
        <DropdownMenuItem disabled>Enviar recordatorio</DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem className="text-danger">Anular cita</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dropdownmenu--default)
- [Open By Default](/storybook/?path=/story/overlays-dropdownmenu--open-by-default)
- [Radio Filter](/storybook/?path=/story/overlays-dropdownmenu--radio-filter)

## Source

`packages/ui/src/overlays/dropdown-menu/dropdown-menu.tsx`

---

# DropdownMenuRadioItem

> Radix sets `role="menuitemradio"` and `aria-checked`: use it for single-value filters.

Source: https://ui.jcsoftdev.com/docs/components/dropdown-menu-radio-item

Radix sets `role="menuitemradio"` and `aria-checked`: use it for single-value filters.

## Import

```ts
import { DropdownMenuRadioItem } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dropdown-menu`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="secondary">Acciones de la cita</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent {...args}>
        <DropdownMenuLabel>Luis Ramírez · 11:30</DropdownMenuLabel>
        <DropdownMenuItem>Reprogramar</DropdownMenuItem>
        <DropdownMenuItem>Cobrar S/ 45</DropdownMenuItem>
        <DropdownMenuItem disabled>Enviar recordatorio</DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem className="text-danger">Anular cita</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dropdownmenu--default)
- [Open By Default](/storybook/?path=/story/overlays-dropdownmenu--open-by-default)
- [Radio Filter](/storybook/?path=/story/overlays-dropdownmenu--radio-filter)

## Source

`packages/ui/src/overlays/dropdown-menu/dropdown-menu.tsx`

---

# DropdownMenuSeparator

> `DropdownMenuSeparator` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/dropdown-menu-separator

`DropdownMenuSeparator` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DropdownMenuSeparator } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dropdown-menu`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="secondary">Acciones de la cita</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent {...args}>
        <DropdownMenuLabel>Luis Ramírez · 11:30</DropdownMenuLabel>
        <DropdownMenuItem>Reprogramar</DropdownMenuItem>
        <DropdownMenuItem>Cobrar S/ 45</DropdownMenuItem>
        <DropdownMenuItem disabled>Enviar recordatorio</DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem className="text-danger">Anular cita</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dropdownmenu--default)
- [Open By Default](/storybook/?path=/story/overlays-dropdownmenu--open-by-default)
- [Radio Filter](/storybook/?path=/story/overlays-dropdownmenu--radio-filter)

## Source

`packages/ui/src/overlays/dropdown-menu/dropdown-menu.tsx`

---

# DropdownMenuTrigger

> `DropdownMenuTrigger` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/dropdown-menu-trigger

`DropdownMenuTrigger` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { DropdownMenuTrigger } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/dropdown-menu`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="secondary">Acciones de la cita</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent {...args}>
        <DropdownMenuLabel>Luis Ramírez · 11:30</DropdownMenuLabel>
        <DropdownMenuItem>Reprogramar</DropdownMenuItem>
        <DropdownMenuItem>Cobrar S/ 45</DropdownMenuItem>
        <DropdownMenuItem disabled>Enviar recordatorio</DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem className="text-danger">Anular cita</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-dropdownmenu--default)
- [Open By Default](/storybook/?path=/story/overlays-dropdownmenu--open-by-default)
- [Radio Filter](/storybook/?path=/story/overlays-dropdownmenu--radio-filter)

## Source

`packages/ui/src/overlays/dropdown-menu/dropdown-menu.tsx`

---

# HoverCard

> Preview card shown on hover or keyboard focus of its trigger.

Source: https://ui.jcsoftdev.com/docs/components/hover-card

Preview card shown on hover or keyboard focus of its trigger. Built on the popover
primitive for placement and collision handling; it never takes focus and closes on Escape.

## Import

```ts
import { HoverCard } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/hover-card`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <HoverCard {...args}>
      <Barbero />
    </HoverCard>
  ),
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` * | `ReactNode` |  |  |
| `open` | `boolean` |  | Controlled open state. |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `((open: boolean) => void)` |  |  |
| `openDelay` | `number` | `300` | ms before opening on hover (focus opens at once). |
| `closeDelay` | `number` | `150` | ms before closing, so the pointer can travel into the card. |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/overlays-hovercard--default)
- [Open By Default](/storybook/?path=/story/overlays-hovercard--open-by-default)
- [Narrow](/storybook/?path=/story/overlays-hovercard--narrow)
- [Brutal Preset](/storybook/?path=/story/overlays-hovercard--brutal-preset)

## Source

`packages/ui/src/overlays/hover-card/hover-card.tsx`

---

# HoverCardContent

> `HoverCardContent` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/hover-card-content

`HoverCardContent` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { HoverCardContent } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/hover-card`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <HoverCard {...args}>
      <Barbero />
    </HoverCard>
  ),
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| null` |  | Portal target. Defaults to `document.body`; pass an element to keep a scoped `data-style`. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-hovercard--default)
- [Open By Default](/storybook/?path=/story/overlays-hovercard--open-by-default)
- [Narrow](/storybook/?path=/story/overlays-hovercard--narrow)
- [Brutal Preset](/storybook/?path=/story/overlays-hovercard--brutal-preset)

## Source

`packages/ui/src/overlays/hover-card/hover-card.tsx`

---

# HoverCardTrigger

> `HoverCardTrigger` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/hover-card-trigger

`HoverCardTrigger` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { HoverCardTrigger } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/hover-card`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <HoverCard {...args}>
      <Barbero />
    </HoverCard>
  ),
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` |  | Use the child element as the trigger instead of wrapping it in a span. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-hovercard--default)
- [Open By Default](/storybook/?path=/story/overlays-hovercard--open-by-default)
- [Narrow](/storybook/?path=/story/overlays-hovercard--narrow)
- [Brutal Preset](/storybook/?path=/story/overlays-hovercard--brutal-preset)

## Source

`packages/ui/src/overlays/hover-card/hover-card.tsx`

---

# Popover

> `Popover` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/popover

`Popover` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { Popover } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/popover`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Popover>
      <PopoverTrigger asChild>
        <Button variant="secondary">Ver cliente</Button>
      </PopoverTrigger>
      <PopoverContent {...args}>
        <ClientCard />
      </PopoverContent>
    </Popover>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-popover--default)
- [Open By Default](/storybook/?path=/story/overlays-popover--open-by-default)
- [Top End](/storybook/?path=/story/overlays-popover--top-end)
- [Anchored To Element](/storybook/?path=/story/overlays-popover--anchored-to-element)

## Source

`packages/ui/src/overlays/popover/popover.tsx`

---

# PopoverAnchor

> `PopoverAnchor` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/popover-anchor

`PopoverAnchor` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { PopoverAnchor } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/popover`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Popover>
      <PopoverTrigger asChild>
        <Button variant="secondary">Ver cliente</Button>
      </PopoverTrigger>
      <PopoverContent {...args}>
        <ClientCard />
      </PopoverContent>
    </Popover>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-popover--default)
- [Open By Default](/storybook/?path=/story/overlays-popover--open-by-default)
- [Top End](/storybook/?path=/story/overlays-popover--top-end)
- [Anchored To Element](/storybook/?path=/story/overlays-popover--anchored-to-element)

## Source

`packages/ui/src/overlays/popover/popover.tsx`

---

# PopoverClose

> `PopoverClose` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/popover-close

`PopoverClose` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { PopoverClose } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/popover`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Popover>
      <PopoverTrigger asChild>
        <Button variant="secondary">Ver cliente</Button>
      </PopoverTrigger>
      <PopoverContent {...args}>
        <ClientCard />
      </PopoverContent>
    </Popover>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-popover--default)
- [Open By Default](/storybook/?path=/story/overlays-popover--open-by-default)
- [Top End](/storybook/?path=/story/overlays-popover--top-end)
- [Anchored To Element](/storybook/?path=/story/overlays-popover--anchored-to-element)

## Source

`packages/ui/src/overlays/popover/popover.tsx`

---

# PopoverContent

> Positioned contextual panel; viewport collision is handled by Radix (Floating UI).

Source: https://ui.jcsoftdev.com/docs/components/popover-content

Positioned contextual panel; viewport collision is handled by Radix (Floating UI).

## Import

```ts
import { PopoverContent } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/popover`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Popover>
      <PopoverTrigger asChild>
        <Button variant="secondary">Ver cliente</Button>
      </PopoverTrigger>
      <PopoverContent {...args}>
        <ClientCard />
      </PopoverContent>
    </Popover>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-popover--default)
- [Open By Default](/storybook/?path=/story/overlays-popover--open-by-default)
- [Top End](/storybook/?path=/story/overlays-popover--top-end)
- [Anchored To Element](/storybook/?path=/story/overlays-popover--anchored-to-element)

## Source

`packages/ui/src/overlays/popover/popover.tsx`

---

# PopoverTrigger

> `PopoverTrigger` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/popover-trigger

`PopoverTrigger` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { PopoverTrigger } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/popover`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Popover>
      <PopoverTrigger asChild>
        <Button variant="secondary">Ver cliente</Button>
      </PopoverTrigger>
      <PopoverContent {...args}>
        <ClientCard />
      </PopoverContent>
    </Popover>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-popover--default)
- [Open By Default](/storybook/?path=/story/overlays-popover--open-by-default)
- [Top End](/storybook/?path=/story/overlays-popover--top-end)
- [Anchored To Element](/storybook/?path=/story/overlays-popover--anchored-to-element)

## Source

`packages/ui/src/overlays/popover/popover.tsx`

---

# PreviousFocusProvider

> `PreviousFocusProvider` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

Source: https://ui.jcsoftdev.com/docs/components/previous-focus-provider

`PreviousFocusProvider` is part of the Overlays set, imported from `@jcsoftdev/ui/overlays`.

## Import

```ts
import { PreviousFocusProvider } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/focus-return`.

## Usage

```tsx
<PreviousFocusProvider initialOpen={false} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `focusRef` * | `FocusRef` |  |  |
| `children` * | `ReactNode` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/overlays-focusreturn--default)
- [Open By Default](/storybook/?path=/story/overlays-focusreturn--open-by-default)
- [With Provider](/storybook/?path=/story/overlays-focusreturn--with-provider)

## Source

`packages/ui/src/overlays/focus-return/focus-return.tsx`

---

# Toaster

> Ephemeral, non-critical confirmations.

Source: https://ui.jcsoftdev.com/docs/components/toaster

Ephemeral, non-critical confirmations. Pass `action: { label, onClick }` to
`toast()` for an undo button. Critical messages belong in a banner instead.

## Import

```ts
import { Toaster } from "@jcsoftdev/ui/overlays";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/overlays/toaster`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <>
      <Toaster {...args} />
      <Button onClick={() => toast("Cita agendada para Luis Ramírez, sábado 11:30")}>
        Agendar cita
      </Button>
    </>
  ),
};
```

_Source of the Storybook story._

## Props

This component declares no props of its own.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/overlays-toaster--default)
- [With Undo Action](/storybook/?path=/story/overlays-toaster--with-undo-action)
- [Open By Default](/storybook/?path=/story/overlays-toaster--open-by-default)
- [Top Right Stack](/storybook/?path=/story/overlays-toaster--top-right-stack)

## Source

`packages/ui/src/overlays/toaster/toaster.tsx`

---

# CommandPalette

> Global search/command palette built on `cmdk`, shown in a modal dialog.

Source: https://ui.jcsoftdev.com/docs/components/command-palette

Global search/command palette built on `cmdk`, shown in a modal dialog.

## Import

```ts
import { CommandPalette } from "@jcsoftdev/ui/palette";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/palette/command-palette`.

## Usage

```tsx
<CommandPalette
  open
  items={items}
  label="Buscar en la barbería"
  placeholder="Buscar clientes, servicios o acciones..."
  emptyLabel="Sin resultados"
  closeKeyLabel="Esc"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` * | `boolean` |  |  |
| `onClose` * | `() => void` |  |  |
| `items` * | `CommandPaletteItem[]` |  |  |
| `label` * | `string` |  | Accessible name of the dialog. |
| `placeholder` * | `string` |  |  |
| `emptyLabel` * | `string` |  | Text shown when nothing matches. |
| `formatResultCount` * | `(count: number) => string` |  | Screen-reader announcement of the result count, e.g. `(n) => \`${n} results\``. |
| `closeKeyLabel` | `string` | `"Esc"` | Hint for the close key shown next to the input. |
| `query` | `string` |  | Controlled query, so the parent can react to typing (e.g. debounced remote search). |
| `onQueryChange` | `((query: string) => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/palette-commandpalette--default)
- [Empty](/storybook/?path=/story/palette-commandpalette--empty)
- [Custom Close Key](/storybook/?path=/story/palette-commandpalette--custom-close-key)
- [Controlled Query](/storybook/?path=/story/palette-commandpalette--controlled-query)

## Source

`packages/ui/src/palette/command-palette/command-palette.tsx`

---

# RichTextEditor

> Rich text editor on a plain `contenteditable`, with no dependencies.

Source: https://ui.jcsoftdev.com/docs/components/rich-text-editor

Rich text editor on a plain `contenteditable`, with no dependencies. Supports bold, italic,
underline, a title, bullet and numbered lists and links (Ctrl/Cmd+B, I, U, K). Everything that
leaves the editor, including pasted content, goes through `sanitizeHtml`.

It uses `document.execCommand`: deprecated on paper but still the only dependency-free way to
edit rich text natively, and implemented by every engine.

## Import

```ts
import { RichTextEditor } from "@jcsoftdev/ui/rich-text";
```

## Usage

```tsx
<RichTextEditor
  placeholder="Describe el servicio…"
  minHeightRem={8}
  aria-label="Descripción del servicio"
  defaultValue={SAMPLE}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Controlled HTML. It is sanitized before it reaches the editor. |
| `defaultValue` | `string` | `""` |  |
| `onChange` | `((html: string) => void)` |  | Receives sanitized HTML, or "" when the editor is empty. |
| `placeholder` | `string` | `"Escribe aquí…"` |  |
| `disabled` | `boolean` |  |  |
| `minHeightRem` | `number` | `8` | Minimum height of the editing area, in rem. |
| `aria-label` | `string` |  |  |
| `aria-labelledby` | `string` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/forms-richtexteditor--default)
- [Empty](/storybook/?path=/story/forms-richtexteditor--empty)
- [Disabled](/storybook/?path=/story/forms-richtexteditor--disabled)
- [With Preview](/storybook/?path=/story/forms-richtexteditor--with-preview)
- [Hostile Input](/storybook/?path=/story/forms-richtexteditor--hostile-input)
- [Narrow](/storybook/?path=/story/forms-richtexteditor--narrow)
- [Brutal Preset](/storybook/?path=/story/forms-richtexteditor--brutal-preset)

## Source

`packages/ui/src/rich-text/rich-text-editor.tsx`

---

# RichTextView

> Read-only rendering of editor output; sanitizes again so stored HTML is never trusted.

Source: https://ui.jcsoftdev.com/docs/components/rich-text-view

Read-only rendering of editor output; sanitizes again so stored HTML is never trusted.

## Import

```ts
import { RichTextView } from "@jcsoftdev/ui/rich-text";
```

## Usage

```tsx
<RichTextView
  placeholder="Describe el servicio…"
  minHeightRem={8}
  aria-label="Descripción del servicio"
  defaultValue={SAMPLE}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `html` * | `string` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/forms-richtexteditor--default)
- [Empty](/storybook/?path=/story/forms-richtexteditor--empty)
- [Disabled](/storybook/?path=/story/forms-richtexteditor--disabled)
- [With Preview](/storybook/?path=/story/forms-richtexteditor--with-preview)
- [Hostile Input](/storybook/?path=/story/forms-richtexteditor--hostile-input)
- [Narrow](/storybook/?path=/story/forms-richtexteditor--narrow)
- [Brutal Preset](/storybook/?path=/story/forms-richtexteditor--brutal-preset)

## Source

`packages/ui/src/rich-text/rich-text-editor.tsx`

---

# AppShell

> Root of the app frame (sidebar + topbar + page).

Source: https://ui.jcsoftdev.com/docs/components/app-shell

Root of the app frame (sidebar + topbar + page). It is the `app` container: the sidebar turns
into a drawer and the topbar shows its menu button when the SHELL is under 900 px wide,
whatever the viewport is, so the same shell works in a full page, a preview or a story.

## Import

```ts
import { AppShell } from "@jcsoftdev/ui/shell";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/shell/app-shell`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => (
    <Frame>
      <ShellDemo className={args.className} />
    </Frame>
  ),
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` * | `ReactNode` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/shell-appshell--default)
- [Compact](/storybook/?path=/story/shell-appshell--compact)

## Source

`packages/ui/src/shell/app-shell/app-shell.tsx`

---

# Sidebar

> Main navigation.

Source: https://ui.jcsoftdev.com/docs/components/sidebar

Main navigation. Always visible when its app container is wide; an off-canvas drawer under
900 px of container width, `inert` while closed so it is not reachable by keyboard.
Render it inside `AppShell`: the container decides, never the viewport. Without an `AppShell`
it measures its parent element instead.

## Import

```ts
import { Sidebar } from "@jcsoftdev/ui/shell";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/shell/sidebar`.

## Usage

```tsx
<Sidebar
  groups={groups}
  ariaLabel="Navegación principal"
  header={header}
  footer={footer}
  open={false}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `groups` * | `SidebarGroup[]` |  |  |
| `ariaLabel` * | `string` |  | Accessible name of the sidebar landmark. |
| `header` | `ReactNode` |  | Brand block shown at the top. |
| `footer` | `ReactNode` |  | Block pinned to the bottom (e.g. the current user). |
| `renderLink` | `SidebarRenderLink` | `defaultRenderLink` | Link renderer; defaults to a plain anchor. |
| `open` | `boolean` | `false` | Drawer state when the app container is under 900 px. Ignored above it, where the sidebar is always visible. |
| `onClose` | `(() => void)` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/shell-sidebar--default)
- [Without Header And Footer](/storybook/?path=/story/shell-sidebar--without-header-and-footer)
- [Custom Link](/storybook/?path=/story/shell-sidebar--custom-link)
- [Mobile Drawer](/storybook/?path=/story/shell-sidebar--mobile-drawer)

## Source

`packages/ui/src/shell/sidebar/sidebar.tsx`

---

# Topbar

> `Topbar` is part of the Shell set, imported from `@jcsoftdev/ui/shell`.

Source: https://ui.jcsoftdev.com/docs/components/topbar

`Topbar` is part of the Shell set, imported from `@jcsoftdev/ui/shell`.

## Import

```ts
import { Topbar } from "@jcsoftdev/ui/shell";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/shell/topbar`.

## Usage

```tsx
<Topbar
  breadcrumbs={["Barbería", "Agenda", "Hoy"]}
  breadcrumbsLabel="Ruta de navegación"
  menuLabel="Abrir menú"
  searchLabel="Buscar"
  searchPlaceholder="Buscar cliente, cita o producto"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `breadcrumbs` * | `string[]` |  | Breadcrumb trail in order; the last entry is the current view. |
| `breadcrumbsLabel` * | `string` |  | Accessible name of the breadcrumb landmark. |
| `onOpenMenu` | `(() => void)` |  | Menu button (shown when the `AppShell` container is under 900 px, matching the Sidebar drawer) that opens the sidebar drawer. Needs an `@container/app` ancestor, which `AppShell` provides. Omitted when not set. |
| `menuLabel` | `string` |  |  |
| `menuButtonRef` | `Ref<HTMLButtonElement>` |  | Ref to the menu button so the opener can restore focus when the drawer closes. |
| `onSearch` * | `() => void` |  | Called by the search trigger and by Cmd/Ctrl+K. |
| `searchLabel` * | `string` |  |  |
| `searchPlaceholder` * | `string` |  |  |
| `actions` | `ReactNode` |  | Slot between the search trigger and the end block (status, notifications, primary action). |
| `end` | `ReactNode` |  | Slot at the far end (e.g. the account menu). |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/shell-topbar--default)
- [Single Crumb](/storybook/?path=/story/shell-topbar--single-crumb)
- [With Actions And End](/storybook/?path=/story/shell-topbar--with-actions-and-end)
- [Mobile Without Menu](/storybook/?path=/story/shell-topbar--mobile-without-menu)
- [Panel Layout](/storybook/?path=/story/shell-topbar--panel-layout)
- [Narrow](/storybook/?path=/story/shell-topbar--narrow)

## Source

`packages/ui/src/shell/topbar/topbar.tsx`

---

# EmptyState

> `EmptyState` is part of the States set, imported from `@jcsoftdev/ui/states`.

Source: https://ui.jcsoftdev.com/docs/components/empty-state

`EmptyState` is part of the States set, imported from `@jcsoftdev/ui/states`.

## Import

```ts
import { EmptyState } from "@jcsoftdev/ui/states";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/states/empty-state`.

## Usage

```tsx
<EmptyState
  icon={<CalendarX className="size-8" />}
  title="Sin citas para hoy"
  description="Cuando un cliente reserve, su cita aparecerá aquí."
  action={<Button>Nueva cita</Button>}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` |  | Decorative icon; hidden from screen readers. |
| `title` * | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `action` | `ReactNode` |  | Primary call to action. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/states-emptystate--default)
- [Title Only](/storybook/?path=/story/states-emptystate--title-only)
- [Inventory](/storybook/?path=/story/states-emptystate--inventory)
- [Narrow](/storybook/?path=/story/states-emptystate--narrow)

## Source

`packages/ui/src/states/empty-state/empty-state.tsx`

---

# ErrorState

> `ErrorState` is part of the States set, imported from `@jcsoftdev/ui/states`.

Source: https://ui.jcsoftdev.com/docs/components/error-state

`ErrorState` is part of the States set, imported from `@jcsoftdev/ui/states`.

## Import

```ts
import { ErrorState } from "@jcsoftdev/ui/states";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/states/error-state`.

## Usage

```tsx
<ErrorState
  message="No pudimos cargar la agenda del día"
  correlationId="7f3a-91c2"
  correlationLabel="ID:"
  retryLabel="Reintentar"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `message` * | `ReactNode` |  |  |
| `correlationId` | `ReactNode` |  | Correlation code for support; never a raw exception. |
| `correlationLabel` | `string` | `"ID:"` | Prefix shown before the correlation id. |
| `onRetry` | `(() => void)` |  |  |
| `retryLabel` | `string` | `"Retry"` |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/states-errorstate--default)
- [Without Retry](/storybook/?path=/story/states-errorstate--without-retry)
- [Without Correlation](/storybook/?path=/story/states-errorstate--without-correlation)
- [Narrow](/storybook/?path=/story/states-errorstate--narrow)

## Source

`packages/ui/src/states/error-state/error-state.tsx`

---

# ForbiddenState

> `ForbiddenState` is part of the States set, imported from `@jcsoftdev/ui/states`.

Source: https://ui.jcsoftdev.com/docs/components/forbidden-state

`ForbiddenState` is part of the States set, imported from `@jcsoftdev/ui/states`.

## Import

```ts
import { ForbiddenState } from "@jcsoftdev/ui/states";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/states/forbidden-state`.

## Usage

```tsx
<ForbiddenState
  title="No tienes acceso a los reportes de ingresos"
  reason="Solo el administrador de la barbería puede ver las ventas del local."
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `ReactNode` |  |  |
| `reason` | `ReactNode` |  | Reason for the block, e.g. depending on role; never just "Forbidden". |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/states-forbiddenstate--default)
- [Title Only](/storybook/?path=/story/states-forbiddenstate--title-only)

## Source

`packages/ui/src/states/forbidden-state/forbidden-state.tsx`

---

# OfflineBanner

> `OfflineBanner` is part of the States set, imported from `@jcsoftdev/ui/states`.

Source: https://ui.jcsoftdev.com/docs/components/offline-banner

`OfflineBanner` is part of the States set, imported from `@jcsoftdev/ui/states`.

## Import

```ts
import { OfflineBanner } from "@jcsoftdev/ui/states";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/states/offline-banner`.

## Usage

```tsx
<OfflineBanner
  message="Sin conexión. Los cobros se guardarán y se enviarán al reconectar."
  queuedChanges={0}
  queuedLabel="cambios pendientes"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `queuedChanges` | `number` | `0` | Number of changes queued while waiting to reconnect. |
| `queuedLabel` | `string` |  | Screen reader text for the queue counter. |
| `message` * | `ReactNode` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/states-offlinebanner--default)
- [With Queued Changes](/storybook/?path=/story/states-offlinebanner--with-queued-changes)

## Source

`packages/ui/src/states/offline-banner/offline-banner.tsx`

---

# Skeleton

> `Skeleton` is part of the States set, imported from `@jcsoftdev/ui/states`.

Source: https://ui.jcsoftdev.com/docs/components/skeleton

`Skeleton` is part of the States set, imported from `@jcsoftdev/ui/states`.

## Import

```ts
import { Skeleton } from "@jcsoftdev/ui/states";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/states/skeleton`.

## Usage

```tsx
<Skeleton variant="lines" lines={3} rows={4} label="Cargando clientes" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"table" \| "lines" \| "card"` | `"lines"` |  |
| `lines` | `number` | `3` | Number of lines for the `lines` variant. |
| `rows` | `number` | `4` | Number of rows for the `table` variant. |
| `label` | `string` | `"Loading"` | Text announced to screen readers while loading. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/states-skeleton--default)
- [Lines](/storybook/?path=/story/states-skeleton--lines)
- [Table](/storybook/?path=/story/states-skeleton--table)
- [Card](/storybook/?path=/story/states-skeleton--card)

## Source

`packages/ui/src/states/skeleton/skeleton.tsx`

---

# Exports reference

> Every public hook, function and constant of @jcsoftdev/ui that is not a React component.

Source: https://ui.jcsoftdev.com/docs/reference/exports

Hooks, helpers and constants exported next to the components. React components have their own pages under Components.

## @jcsoftdev/ui/ai

| Export | Kind | Summary |
| --- | --- | --- |
| `DATE_GROUP_LABELS` | constant | `Record<DateGroupId, string>` |
| `distanceFromBottom` | function | Distance in px (never negative) between the viewport bottom and the content bottom. |
| `groupByDate` | function | Newest first inside each group; empty groups are dropped; groups keep recency order. |
| `groupOf` | function | `(date: Date \\| string \\| number, now: Date \\| string \\| number) => DateGroupId` |
| `isNearBottom` | function | `(m: ScrollMetrics, threshold?: number) => boolean` |
| `nextStuck` | function | Next "stuck to bottom" state after a scroll event. |
| `parseMarkdown` | function | Parses Markdown into blocks. |
| `resolveLanguage` | function | Maps a fence label (`typescript`, `sh`…) to a supported language, or null. |
| `safeHref` | function | Returns the normalized URL when its protocol is http, https or mailto; otherwise null. |
| `shouldSubmit` | function | Enter submits; Shift+Enter inserts a newline; IME composition never submits. |
| `showJumpToLatest` | function | The "jump to latest" button shows only when the user left the bottom. |
| `STICK_THRESHOLD` | constant | Distance in px from the bottom that still counts as "at the bottom". |
| `tokenize` | function | `(code: string, language: string \\| undefined) => Token[]` |

## @jcsoftdev/ui/atoms

| Export | Kind | Summary |
| --- | --- | --- |
| `DEFAULT_LOCALE` | constant | `"es-PE"` |
| `easeOutCubic` | function | `(t: number) => number` |
| `formatNumber` | function | Locale-aware number formatting (currency, percent, compact, units via Intl options). |
| `formatTrend` | function | Signed percent text from a percentage value: 12.5 -> "+12.5%" (es-PE). |
| `icons` | constant | Optional name registry for `<Icon name>`. |
| `trendDirection` | function | Direction of a change; values within `epsilon` of zero are flat. |
| `trendTone` | function | Good/bad reading of a direction. |
| `tweenValue` | function | Value between `from` and `to` at linear `progress` (0..1), eased. |

## @jcsoftdev/ui/brand

| Export | Kind | Summary |
| --- | --- | --- |
| `BRAND_PALETTES` | constant | The first seven mirror the library accent palettes (fill, second tone and deep ink); the rest are classic barbershop colorways. |
| `contentColor` | function | The palette ink over pale fills, white over dark ones. |
| `copyText` | function | `(text: string) => Promise<void>` |
| `createRng` | function | Small deterministic PRNG (mulberry32): the same seed always yields the same sequence. |
| `DEFAULT_FORGE_VALUE` | constant | `LogoForgeValue` |
| `downloadBlob` | function | `(blob: Blob, filename: string) => void` |
| `escapeXml` | function | `(value: string) => string` |
| `fileSlug` | function | Browser-only helpers behind the Logo Forge export buttons. |
| `findGlyph` | function | `(id: GlyphId) => Glyph` |
| `findPalette` | function | `(id: string) => BrandPalette` |
| `FONT_STACK` | constant | `"ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif"` |
| `forgeOptions` | function | Turns the editor state into generator options. |
| `generateMark` | function | `(options: MarkOptions) => MarkDescription` |
| `generateVariations` | function | A deterministic page of `count` variations around `base`: the name, tagline, layout and wordmark stay, while shape, monogram, palette, fill and seed change. |
| `getInitials` | function | Initials of a business name: first letter of each significant word, accents removed (the Ñ is kept), articles and prepositions skipped. |
| `GLYPH_IDS` | constant | `readonly GlyphId[]` |
| `GLYPHS` | constant | Our own simple geometric paths; no third-party icon data. |
| `hashString` | function | FNV-1a over UTF-16 code units; stable across runtimes. |
| `luminance` | function | WCAG relative luminance of a hex color; other formats read as mid-dark. |
| `MARK_FILLS` | constant | `readonly ["solid", "gradient", "outline"]` |
| `MARK_LAYOUTS` | constant | `readonly ["icon", "horizontal", "stacked"]` |
| `MARK_SHAPES` | constant | `readonly ["circle", "squircle", "shield", "hexagon", "badge", "ribbon", "none"]` |
| `pick` | function | `<T>(rng: () => number, items: readonly T[]) => T` |
| `safeColor` | function | Accepts hex, rgb()/hsl() and plain color names only; anything else falls back. |
| `serializeMark` | function | Standalone SVG document string. |
| `svgBlob` | function | `(svg: string) => Blob` |
| `svgToPngBlob` | function | Rasterizes an SVG string through a canvas. |

## @jcsoftdev/ui/charts

| Export | Kind | Summary |
| --- | --- | --- |
| `activeFilterCount` | function | `(filters: CrossfilterFilters) => number` |
| `addUnits` | function | `time` moved by `count` calendar units (daylight saving safe for days and above). |
| `allDates` | function | True when every category is a Date, so a time scale makes sense. |
| `alluvialGraph` | function | Turns stage-by-stage category flows into sankey nodes and links: one node per category per stage (pinned to its column), the same color across stages, in category order. |
| `alluvialNodeId` | function | Node id of a category at a stage: `"2:vip"`. |
| `ancestorIds` | function | Ids of the ancestors of `node`, root first (the node itself excluded). |
| `ancestors` | function | Root first, `node` last. |
| `angleOf` | function | Angle of the vector (cx, cy) -> (x, y), in [0, TAU). |
| `appendBars` | function | Adds live bars to a series: a bar with the same date as the last one replaces it (the candle still forming), a newer bar is appended, an older one is ignored. |
| `applyMatrix` | function | `(matrix: Matrix, v: Vec3) => Vec3` |
| `arcLine` | function | Open centre-line arc, meant to be stroked (`strokeLinecap="round"` gives the rounded ends). |
| `arcPath` | function | Closed path of an annular sector (a pie wedge when `innerRadius` is 0), with optional rounded corners. |
| `areaPath` | function | Closed area between a top and a bottom edge sampled at the same x positions (`bottom[i]` pairs with `top[i]`). |
| `aspectRatio` | function | Width / height ratio, always >= 1. |
| `assignLanes` | function | Packs overlapping intervals into the fewest lanes: items are placed in start order into the first lane that is already free. |
| `assignUnits` | function | Category of each position when `counts` are laid one after the other. |
| `averageTrueRange` | function | Average true range over the last `period` bars (simple mean of the true ranges). |
| `bandScale` | function | `({ count, range, paddingInner, paddingOuter, }: BandScaleOptions) => BandScale` |
| `BARBER_SILHOUETTES` | constant | Barbershop silhouettes drawn for this library. |
| `barPath` | function | Bar rounded only at its value end, the way the eye reads the bar's length. |
| `beeswarm` | function | Beeswarm layout: offsets perpendicular to the value axis so that no two circles overlap. |
| `binCounts` | function | Counts `values` into the bins delimited by ascending `edges`. |
| `binEdges` | function | Bin edges for `values`: a width and a start aligned to it. |
| `binIndex` | function | Index of the bin of `value`: bins are `[edge i, edge i+1)`, the last one includes its upper edge. |
| `binRecords` | function | Count per bin of a numeric dimension, over the records that pass every OTHER filter. |
| `binsInRange` | function | Indices of the bins a range filter covers (a bin is covered when it overlaps the range). |
| `blendRings` | function | RingPoint-wise blend of two rings of equal length: `t` 0 gives `from`, 1 gives `to`. |
| `bollinger` | function | Simple average ± `k` population standard deviations of the same window. |
| `boxStats` | function | Five-number summary plus mean and Tukey outliers. |
| `boxTooltipRows` | function | Tooltip rows for a five-number summary. |
| `boxValueText` | function | One-line summary of a box for `aria-valuetext`. |
| `branchColor` | function | Base color of a node: its own `color`, otherwise the palette slot of the branch it belongs to below `focus`, so the open level always shows several hues. |
| `breakCycles` | function | Splits the links into an acyclic set and the links that close a cycle. |
| `bubbleRadiusScale` | function | Bubbles shrink in narrow frames (down to 55%) so they keep some separation. |
| `buildCategoryAxis` | function | Turns categories into pixel positions, ticks and hit-testing for charts that share a horizontal category or time axis. |
| `buildHierarchy` | function | Turns nested data into linked nodes with summed values. |
| `buildTopology` | function | Builds a TopoJSON topology from lon/lat polygons. |
| `buildTreeModel` | function | Builds the node model. |
| `calendarGrid` | function | Lays days out like a contribution calendar: one column per week (Monday first), one row per weekday. |
| `categoryGroupSpans` | function | Pixel span of each group along the category axis. |
| `categoryLayout` | function | Geometry for charts with a category axis and a continuous value axis (box plots, violins, rainclouds, beeswarms). |
| `CHART_PALETTE` | constant | Series colors. |
| `ChartSyncStore` | class | A set of named channels. |
| `chordLayout` | function | `(matrix: ReadonlyArray<readonly number[]>, { padAngle, startAngle, sortGroups, sortSubgroups, }?: ChordOptions) => Chor…` |
| `chordsOf` | function | Ribbons that touch a group (as source or target). |
| `clampView` | function | Keeps the map from being lost: its content box (`content`, in zoom 1 pixels) must stay inside the `width` x `height` viewport on each axis, or, when it is bigger than the viewport… |
| `clean` | function | Rounds away binary noise such as 0.30000000000000004. |
| `clearFilters` | function | Clears one dimension, or all of them. |
| `clipRingToHemisphere` | function | A closed ring in view coordinates cut to the visible hemisphere (z >= 0). |
| `clockTicks` | function | Round clock ticks (every 15 min ... |
| `clusterPoints` | function | Greedy screen-distance clustering: the heaviest unassigned point claims every unassigned point closer than `distance`; the cluster sits at the value-weighted centre of its members. |
| `computeLayout` | function | Computes every pixel of a cartesian chart: margins, scales, ticks, paths, bars, labels and annotations. |
| `createAxisMap` | function | Piecewise-linear map between data values and pixels, given matching samples (e.g. |
| `createRawProjection` | function | Creates a raw projection: - `equirectangular`: plate carrée (x = lon, y = -lat) with an optional standard parallel; - `mercator`: conformal, latitudes clamped to ±85.05°; - `equal… |
| `createRegionIndex` | function | Looks a record up by the id or by the name of a region. |
| `criticalPath` | function | Critical path method over finish-to-start dependencies. |
| `cursorAction` | function | `(tool: "ruler" \\| "ink", key: " " \\| "Enter" \\| "Escape", points: readonly DataPoint[], cursor: DataPoint) => CursorAction` |
| `curveCommands` | function | Commands through `points`. |
| `datetimeColumnLabels` | function | Column labels for a heatmap whose columns are consecutive points in time. |
| `DAY_MS` | constant | `86400000` |
| `dayKey` | function | Local midnight key of a date, for holiday lookups. |
| `decodeArcs` | function | Minimal TopoJSON decoder for area objects. |
| `DECORATIVE` | constant | Spread on purely visual SVG groups and text that screen readers get from the data table instead. |
| `DEFAULT_CHORD_LABELS` | constant | `ChordLabels` |
| `DEFAULT_CROSSFILTER_LABELS` | constant | `CrossfilterLabels` |
| `DEFAULT_EXPORT_TEXTS` | constant | `ExportTexts` |
| `DEFAULT_GLOBE_LABELS` | constant | `GlobeLabels` |
| `DEFAULT_HEATMAP_LABELS` | constant | `HeatmapLabels` |
| `DEFAULT_HIERARCHY_LABELS` | constant | `HierarchyLabels` |
| `DEFAULT_INK_LABELS` | constant | `InkLabels` |
| `DEFAULT_LABELS` | constant | `ChartLabels` |
| `DEFAULT_LIMITS` | constant | `ViewLimits` |
| `DEFAULT_MAP_LABELS` | constant | `MapLabels` |
| `DEFAULT_SANKEY_LABELS` | constant | `SankeyLabels` |
| `DEFAULT_SCALE_COLORS` | constant | `Required<ScaleColors>` |
| `DEFAULT_STAT_LABELS` | constant | `StatLabels` |
| `DEFAULT_STOCK_RANGES` | constant | 1W, 1M, 3M, 6M, 1Y, All. |
| `DEFAULT_STOCK_TOOLS` | constant | `readonly StockTool[]` |
| `DEFAULT_TREE_LABELS` | constant | `TreeLabels` |
| `defaultBrickSize` | function | Brick size used when none is given: the ATR(14), never below 0.01. |
| `defaultCategoryLabel` | function | Short default label: "6 oct" for dates, the value itself otherwise. |
| `defaultMapHeight` | function | Height that suits `map` at `width`: its own projected height / width ratio, so a tall country gets a tall box and a world map a wide one (within 220 and 640 px). |
| `defaultXLabel` | function | Default category label: Spanish short dates, grouped numbers, strings as given. |
| `degToRad` | function | `(degrees: number) => number` |
| `dendrogramLayout` | function | Dendrogram (cluster layout): like the tidy tree, but every leaf is drawn on the last level, so the leaves line up and the branches read as a hierarchy of groupings. |
| `descendants` | function | Pre-order list: `node`, then its subtree. |
| `describeNode` | function | Spoken summary of a node for the live region and `aria-valuetext`. |
| `DIRECTION_COLORS` | constant | Direction of change: `chart-up` and `chart-down` tokens, `chart-total` when flat or a total. |
| `directionOf` | function | `up` / `down` / `flat` for a change; changes within `epsilon` count as flat. |
| `divergingColor` | function | Diverging scale: `low` below `center`, `mid` at it, `high` above. |
| `downloadPng` | function | Rasterizes through an `<img>` and a canvas; `scale` 2 gives retina sharpness. |
| `downloadSvg` | function | `(input: SVGSVGElement \\| readonly SVGSVGElement[], { fileName, ...options }: ExportOptions) => void` |
| `downsample` | function | LTTB over `{ x, y }` points: at most `threshold` points that keep the visual shape. |
| `dragRotation` | function | New rotation after dragging `dx`, `dy` pixels: the surface follows the pointer (one disc radius is one radian), so a small globe turns faster per pixel than a big one. |
| `EASE_OUT` | constant | `"cubic-bezier(.22,1,.36,1)"` |
| `easeOutCubic` | function | Cubic ease-out for `requestAnimationFrame` transitions, `t` in 0..1. |
| `EDGE_SAMPLES` | constant | Samples per edge: four edges, so a ring holds `4 * EDGE_SAMPLES` points. |
| `edgeColorOf` | function | Color of the edge that enters `node`. |
| `ema` | function | Exponential moving average with smoothing `2 / (period + 1)`. |
| `EMPTY_INK` | constant | `InkState` |
| `estimateTextWidth` | function | Approximate rendered width of a tick label at 11px (tabular figures). |
| `evenEdges` | function | Bin edges (`count + 1` of them) that split `[min, max]` evenly. |
| `explodeBins` | function | Stacks for every bin with one shared radius (the smallest that makes the fullest bin fit), so all the dots of a histogram look alike. |
| `exportFileName` | function | File name from a chart title: lower case, accents removed, dashes, with the extension. |
| `extent` | function | Min and max of the finite numbers in `values`, or null when there are none. |
| `fadeIn` | function | Fades an element in. |
| `FALLBACK_HEIGHT` | constant | Height used before the first measurement when a chart fills its parent. |
| `FALLBACK_WIDTH` | constant | Width used for the server render and the first client paint before measuring. |
| `featurePositions` | function | Every outer-ring vertex of the features, for fitting a projection. |
| `fibLevels` | function | Retracement levels between two prices: ratio 0 sits at `a`, ratio 1 at `b`. |
| `filterRecords` | function | Records that pass every filter. |
| `findNode` | function | `(root: HierarchyNode, id: string) => HierarchyNode \\| null` |
| `fitLabel` | function | Label that fits in `maxWidth`: the full text, a shortened one with an ellipsis, or `null` when not even four characters fit. |
| `fitLaneHeight` | function | Lane height that makes the rows fill `available` exactly: `sum(count * (lane + gap) - gap + 2 * rowPad) = available`, clamped to `[min, max]`. |
| `fitProjection` | function | Projects `positions` and scales them to fill `width` x `height` (minus padding) keeping the aspect ratio, centred. |
| `fitRadius` | function | Largest radius at which `count` dots fit a `width` x `height` box, or the minimum radius. |
| `fitUnitGrid` | function | Picks the column count that gives the largest units inside `width` x `height`. |
| `fitView` | function | View that shows a `contentWidth` x `contentHeight` drawing centred in a `width` x `height` viewport, `padding` from the edges, never enlarged past `maxFit`. |
| `foldText` | function | Lower-case text without accents, for forgiving searches. |
| `formatClock` | function | "09:30" in 24-hour time. |
| `formatCompact` | function | 1234 -> "1,2 mil"; 2500000 -> "2,5 M". |
| `formatCurrency` | function | "S/ 1 234.50" |
| `formatDate` | function | "lun 6 oct 2026": the full label used by tooltips and the data table. |
| `formatDuration` | function | Elapsed time as a short text: "3 d", "2.5 h", "40 min". |
| `formatNumber` | function | "12 345.68" |
| `formatPercent` | function | 0.125 -> "12.5%" |
| `freedmanDiaconisWidth` | function | Freedman–Diaconis bin width: `2 · IQR · n^(-1/3)`; 0 when the IQR is 0. |
| `fromVec` | function | Unit vector to `[lon, lat]` in degrees. |
| `fullCategoryLabel` | function | Long label for tooltips and tables: "mar 6 oct 2026" for dates. |
| `funnelStages` | function | Stage geometry along one axis: each stage spans its slice of `length`, starts as wide as its own value and ends as wide as the next stage, so the outline is continuous. |
| `GANTT_ZOOM_ORDER` | constant | `readonly GanttZoom[]` |
| `GANTT_ZOOMS` | constant | `Record<GanttZoom, GanttZoomLevel>` |
| `ganttDomain` | function | Visible window for a zoom: the tasks padded by one `pad` unit on each side, on unit boundaries. |
| `ganttHeader` | function | Both header rows of a zoom level. |
| `ganttRows` | function | Depth-first rows of the task tree, children right after their parent in input order. |
| `ganttScale` | function | Linear date → x scale. |
| `gaussianKde` | function | Gaussian kernel density estimate, evaluated on an even grid. |
| `geometryExtent` | function | Extent of the outer boundary of a geometry in lon/lat. |
| `geometryPath` | function | SVG path (`d`) of an area: one closed subpath per ring. |
| `geometryRings` | function | All rings of a geometry, flattened (outer rings and holes). |
| `GLOBE_MAX_LAT` | constant | Maximum latitude of the view center: the poles themselves are a singular view. |
| `globeArc` | function | Points of the great circle from `a` to `b` as world vectors, optionally lifted off the surface (`lift` is the extra radius at the middle, as a fraction of the globe radius) so an … |
| `globeLinePieces` | function | Visible stretches of a polyline of world vectors, projected: a path leaving the visible hemisphere is cut at the horizon so lines never wrap behind the globe. |
| `globeRingsPath` | function | SVG path of rings drawn on the globe. |
| `graticuleLines` | function | Meridians and parallels every `step` degrees, as polylines of `[lon, lat]`. |
| `greatCircle` | function | Points of the great circle (the shortest path on the globe) from `a` to `b`, `steps + 1` of them, as `[lon, lat]`. |
| `greatCircleDistance` | function | Angular length of the great circle between two positions, in degrees. |
| `gridCell` | function | Cell of the `index`-th unit. |
| `gridColumns` | function | Columns that fit a container: as many as keep every panel at least `minPanelWidth` wide (gaps included), never more than `maxColumns` or `count`, never fewer than one. |
| `groupAt` | function | Index of the group whose arc contains `angle`, or -1 (in the padding or outside). |
| `groupLeaves` | function | Folds runs of leaf siblings into one group node, so a manager with twenty apprentices shows "20 apprentices" instead of twenty cards. |
| `groupRecords` | function | Totals per value of `dimension`, over the records that pass every OTHER filter. |
| `groupSeed` | function | Seed of one box or violin, so every group gets its own stable jitter. |
| `headerCells` | function | Cells of one header row, clipped to the scale. |
| `heatmapScale` | function | Builds the color function of a heatmap from its options and every finite value. |
| `heightOf` | function | Number of levels below `node` (0 for a leaf). |
| `heikinAshi` | function | Heikin-Ashi candles: each bar opens at the midpoint of the previous HA bar and closes at the average of the raw bar, which smooths the trend. |
| `hexAt` | function | Index of the tile whose hexagon contains the point, or -1. |
| `hexLayout` | function | `({ rows, columns, width, height }: HexLayoutInput) => HexLayout` |
| `hexNeighbors` | function | Ids of the tiles that share an edge with `tile` (odd-r offset neighbours). |
| `hexPath` | function | Closed path of a pointy-top hexagon centred at `(cx, cy)`. |
| `hexPoints` | function | The six corners of a pointy-top hexagon as an SVG `points` value; `inset` shrinks it for the gap. |
| `HIERARCHY_FRAME_CLASS` | constant | Class for the `ChartFrame` of a hierarchy chart: makes it a size container (`@container/chart`) so the header and legend below can react to its width. |
| `hierarchyKey` | function | Keyboard handling shared by the hierarchy charts: arrows move between the children of the focused node, Enter opens the active one, Escape goes up. |
| `histogram` | function | Bins `values` with the chosen rule. |
| `HOUR_MS` | constant | `3600000` |
| `IDENTITY_VIEW` | constant | `MapView` |
| `initialCollapsed` | function | Ids collapsed at first: nodes flagged `collapsed`, and every node at `initialDepth`. |
| `initials` | function | "AR" for "Ana Rojas", "K" for "Kevin". |
| `inkOn` | function | Text color readable on a `tint(color, percent)` fill. |
| `inkPath` | function | The pen path of a stroke given in pixels: thinned, smoothed, then splined. |
| `inkReducer` | function | `(state: InkState, action: InkAction) => InkState` |
| `interpolateView` | function | `(from: PartitionView, to: PartitionView, t: number) => PartitionView` |
| `invertOrthographic` | function | The `[lon, lat]` under a screen pixel, or `null` outside the disc. |
| `isSelected` | function | True when `value` is inside the dimension's filter (or the dimension has none). |
| `isUnitIconName` | function | `(value: unknown) => value is UnitIconName` |
| `jitterValues` | function | Deterministic jitter for raw observations. |
| `keyRotation` | function | Rotation after an arrow key: left and right turn the globe, up and down tilt it. |
| `labelAnchor` | function | A point well inside the region, for its label: the point of the largest polygon farthest from every edge (a coarse "pole of inaccessibility": grid search, then two refinements). |
| `largestRemainder` | function | Shares `total` whole units between weights so they add up exactly (largest remainder method). |
| `layoutHexGrid` | function | Largest hexagons that fit `tiles` in a `width` x `height` area, centered. |
| `levelStrength` | function | Strength (0-100) of the branch hue for a partition cell (sunburst ring or icicle band): strong next to the open node, lighter further out, with a small spread between siblings so … |
| `linearRegression` | function | Ordinary least squares fit `y = slope · x + intercept`; null below two distinct x. |
| `linearScale` | function | `({ domain, range, nice, tickCount, }: LinearScaleOptions) => ContinuousScale` |
| `linearTicks` | function | Evenly spaced round values inside `[min, max]`. |
| `linePath` | function | Line through the points; `null` entries break the line. |
| `logScale` | function | Base-10 logarithmic scale, extended to whole decades. |
| `lttbIndices` | function | Indices LTTB keeps from `points` (ascending, always including the first and last). |
| `macd` | function | Moving average convergence divergence, 12 / 26 / 9 by default. |
| `mapFeatures` | function | Decoded features of a map (once per map object, not per render). |
| `matchesFilter` | function | `(filter: CrossfilterFilter, value: DimensionValue) => boolean` |
| `matchKey` | function | Lowercase, accent-free key so "Áncash", "ancash" and "ANCASH" join. |
| `mean` | function | `(values: readonly number[]) => number` |
| `measureRange` | function | What a drag between two anchors measures. |
| `measureSegment` | function | Difference between two points of the chart, in data units. |
| `MERCATOR_MAX_LAT` | constant | Web Mercator cannot show the poles; latitudes are clamped here. |
| `mondayOf` | function | Monday on or before `date`. |
| `MONOCHROME_BASE` | constant | Base hue of a monochrome chart: the active brand accent. |
| `monochromeByValue` | function | Shades for `values`, darkest on the largest value, so rank reads as intensity. |
| `monochromeShade` | function | Shade `step` of `count` in one hue: step 0 is the full color, the last step the palest tint (40%), mixed towards the surface so it works in both themes. |
| `monotoneTangents` | function | Tangents for a monotone cubic through `points` (Fritsch–Butland): the curve never overshoots between two samples, so a peak in the data is a peak on screen. |
| `moveCursor` | function | One arrow-key step of the crosshair in data units: a category on index axes (a fiftieth of the window on time axes) and a fiftieth of the value window vertically; `big` moves five… |
| `nearestPoint` | function | Index of the item closest to `(x, y)` within `radius` pixels, or null. |
| `niceDomain` | function | Widens `[min, max]` so both ends land on a tick. |
| `niceRadarMax` | function | Rounds `value` up to a tidy multiple so `levels` rings land on round numbers. |
| `NO_FILTERS` | constant | `Readonly<Record<string, CrossfilterFilter>>` |
| `nodePath` | function | "Miraflores › Kevin" relative to `from` (excluded). |
| `nodeTooltipRows` | function | `(node: HierarchyNode, focus: HierarchyNode, format: ValueFormatter, labels: HierarchyLabels, color: string) => TooltipR…` |
| `nonWorkingSpans` | function | Contiguous spans of non-working days inside the domain: days whose weekday (0 = Sunday) is not in `workingDays`, plus `holidays`. |
| `normalize` | function | Clamped position of `value` in [min, max], 0-1. |
| `normalizeAngle` | function | Wraps any angle into [0, TAU). |
| `normalizeRotation` | function | Keeps a rotation valid: longitude wrapped, latitude clamped. |
| `normalPdf` | function | Standard normal density scaled to `mean` and `sd`. |
| `packDots` | function | Dot-plot stack for one bin: dots fill rows from the baseline up, each row centred in the lane. |
| `panelWidth` | function | Width of one panel for a container width and a column count. |
| `parliamentLayout` | function | Seats of a hemicycle. |
| `parliamentRows` | function | Fewest arcs that hold `seats` without crowding. |
| `partitionLayout` | function | Adjacency partition: every node gets a slice of its parent's span proportional to its value. |
| `PATTERN_NAMES` | constant | `readonly ["stripes", "stripes-reverse", "dots", "crosshatch", "grid", "zigzag", "checks", "diamonds", "waves"]` |
| `patternAt` | function | Cycles the built-in designs, handy for "one pattern per series" charts. |
| `patternFill` | function | Paint value that fills a mark with the pattern of `id`. |
| `patternId` | function | Id safe for `url(#id)`: letters, digits, dashes and underscores only. |
| `PERU_HEX_TILES` | constant | Peru as 25 tiles (24 departments + Callao), north-west at the top left and the south-east at the bottom right, with the Pacific coast down the left edge. |
| `pickLabels` | function | Which labels to draw: left to right, a label is kept unless it overlaps an already kept one horizontally while sitting less than `lineHeight` away vertically. |
| `PICTOGRAM_SILHOUETTES` | constant | Human figures and everyday silhouettes for pictograms, in gallery order. |
| `pixelToPlot` | function | Data point under a plot-relative pixel, clamped to the plot box. |
| `plotDomain` | function | Visible data window of a plot, for the keyboard cursor. |
| `plotToPixel` | function | Plot-relative pixel of a data point, whichever way the plot is laid out. |
| `pointScale` | function | `({ count, range, padding }: PointScaleOptions) => BandScale` |
| `polarPoint` | function | Point at `radius` from (cx, cy) in the direction of `angle`. |
| `popUnits` | function | Pops every `[data-unit]` in document order: a short scale-and-fade with a stagger that keeps the whole sequence under about a second. |
| `positionsExtent` | function | Extent of a set of positions: [west, south, east, north]. |
| `progressFractions` | function | Fill of each of `count` units sharing `max`: a 4.5 rating out of 5 stars is `[1, 1, 1, 1, 0.5]`. |
| `projectOrthographic` | function | Orthographic projection of `[lon, lat]`, or `null` on the far side of the globe. |
| `projectSpan` | function | Position of a span inside a view: x in 0-1 of the view (may fall outside), level relative to it. |
| `quantile` | function | Quantile `p` of unsorted values. |
| `quantileSorted` | function | Quantile `p` (0-1) of an ascending array, interpolating linearly between the two closest ranks (the "type 7" definition used by most spreadsheets). |
| `raceItems` | function | State at a fractional frame `position`: values move linearly, ranks follow a smoothstep so a bar glides into its new row instead of jumping. |
| `radialEdgePath` | function | Edge between two points of a radial layout. |
| `radialTreeLayout` | function | Radial tidy tree: the root sits in the centre, each level on its own ring, leaves share the angle evenly and every parent points at the middle of its leaves. |
| `radToDeg` | function | `(radians: number) => number` |
| `rangeColor` | function | Fill of a stepped range: its own `color`, a `tone` (its ink at 55% over the surface, readable with ink text in both themes), or a step of the brand scale by position. |
| `rangeIndex` | function | Index of the first range containing `value`, or -1. |
| `rangeOfBins` | function | Interval covered by bins `from..to` (inclusive indices), as a range filter value. |
| `rangeWindow` | function | Inclusive index window `[from, last]` for a preset over ascending `dates`: the first date on or after the last date minus the preset. |
| `ranksOf` | function | Rank of every value, 0 for the largest; ties keep the entity order. |
| `rebase` | function | Change relative to the value at `base` (0.1 = +10%), for comparing series that live on different scales. |
| `rectRing` | function | Rectangle as a clockwise polygon starting at the top-left corner: top edge, right edge, bottom edge, left edge. |
| `renko` | function | Renko bricks from the closes. |
| `resolveAxes` | function | Axes in drawing order. |
| `resolveAxisFormat` | function | Shorter variant for axis ticks: currency drops the cents and turns compact from ten thousand up ("S/ 12 mil"); plain numbers turn compact from 10 000. |
| `resolveDistributionLabels` | function | `(labels?: Partial<DistributionLabels>) => DistributionLabels` |
| `resolveDrawingHeight` | function | Height of the drawing: the measured slot when filling, `width / aspectRatio` when a ratio is given, else the pixel height. |
| `resolveFormat` | function | Turns a `ValueFormat` into a function. |
| `resolveHeatmapLabels` | function | `(labels?: Partial<HeatmapLabels>) => HeatmapLabels` |
| `resolveHierarchyLabels` | function | `(labels?: Partial<HierarchyLabels>) => HierarchyLabels` |
| `resolveLabels` | function | `(labels?: Partial<ChartLabels>) => ChartLabels` |
| `resolveMapLabels` | function | `(labels?: Partial<MapLabels>) => MapLabels` |
| `resolvePattern` | function | The tile of a named design or of a custom pattern (custom tiles are clamped to a sane size). |
| `resolveRoutes` | function | `(routes: readonly MapRoute[], points: readonly MapPoint[]) => ResolvedRoute[]` |
| `resolveUnitShape` | function | `(icon: UnitIcon) => ResolvedUnitShape` |
| `revealClip` | function | Reveals children left to right by scaling a clip rectangle. |
| `revealPoint` | function | Pans the view the least that brings the zoom 1 point (`x`, `y`) inside the viewport. |
| `ribbonPath` | function | Closed ribbon between the two ends of a chord at `radius`: along the source arc, a curve through the centre to the target arc, along it, and back. |
| `ringArea` | function | Signed area of a ring (shoelace); positive when counter-clockwise in a y-up plane. |
| `ringCenter` | function | Mean of the polygon's points; for these convex-ish shapes it sits inside the shape. |
| `ringPath` | function | Closed SVG path through the points. |
| `roundedPolyline` | function | SVG path through orthogonal points with corners rounded by up to `radius`. |
| `roundedRectPath` | function | Rectangle with an independent radius per corner, clamped to fit. |
| `roundToStep` | function | Rounds to the nearest multiple of `step` (e.g. |
| `routeArcPath` | function | SVG path of a quadratic arc. |
| `routeControl` | function | Control point of a quadratic curve from `a` to `b`: the midpoint pushed sideways by `bend` times the distance (0 is a straight line, 0.25 a soft arch). |
| `routeDependency` | function | Finish-to-start arrow from the end of a predecessor (`from`) to the start of its successor (`to`), with right angles only. |
| `routePolylinePath` | function | SVG path of a polyline given as separate pieces (`greatCircle` output once projected). |
| `rsi` | function | Relative strength index with Wilder smoothing: the first average gain and loss are plain means of `period` changes, later ones are `(previous * (period - 1) + current) / period`. |
| `sankeyDiff` | function | Merges the flows of two periods by `source -> target` (repeated pairs are summed). |
| `sankeyFlowOf` | function | Ids of the links and nodes upstream and downstream of a node (the node included). |
| `sankeyLayout` | function | Lays out a sankey diagram in a `width` x `height` box. |
| `sankeyLinkPath` | function | Centre line of a link band, drawn with `stroke-width = link.width`. |
| `sankeyTraceOf` | function | The path through a link: the link itself, everything that feeds its source (upstream) and everything its target feeds (downstream). |
| `scaleGradient` | function | CSS gradient for a legend bar of a continuous scale. |
| `searchTree` | function | Nodes whose name, subtitle or badge contains every word of `query`, in pre-order (document order). |
| `sectorPath` | function | Annular sector ("donut slice") path. |
| `sectorRing` | function | Annular sector as a polygon with the same edge order as `rectRing`: the outer arc plays the top edge, the end radius the right edge, the inner arc the bottom edge and the start ra… |
| `seededRandom` | function | Deterministic pseudo-random numbers in [0, 1) (mulberry32), so jitter is stable across renders. |
| `segments` | function | Splits a sequence at `null` gaps into drawable runs. |
| `selectRegions` | function | A map restricted to some regions (by id), e.g. |
| `sequentialColor` | function | Sequential scale: `mid` (empty) to `high`. |
| `serializeSvg` | function | Serializes one drawing, or several stacked vertically (e.g. |
| `seriesColor` | function | Color for the series at `index`, unless the series brings its own. |
| `setRangeFilter` | function | `(filters: CrossfilterFilters, dimension: string, range: readonly [number, number] \\| null) => CrossfilterFilters` |
| `sharedDomain` | function | One domain for every panel, so the same height means the same value everywhere. |
| `sharedSampleIndices` | function | Indices to keep so several series that share one category axis stay aligned: the union of the LTTB picks of each series (computed on its non-null values), plus the neighbours of e… |
| `shareOf` | function | `(node: HierarchyNode, of: HierarchyNode) => number` |
| `shiftDate` | function | `date` moved back by `count` units, in local calendar time (months clamp to the last day). |
| `shortMonth` | function | Short Spanish month without the period Intl appends ("oct", not "oct."). |
| `shortWeekday` | function | Short Spanish weekday without the trailing period ("lun"). |
| `signed` | function | A signed number with its sign always shown: "+4", "-2.5", "0". |
| `silvermanBandwidth` | function | Silverman's rule of thumb for a Gaussian kernel: `0.9 · min(sd, IQR / 1.34) · n^(-1/5)`. |
| `simplifyLine` | function | Douglas-Peucker line simplification (iterative, so long coastlines cannot overflow the stack). |
| `sliceAngles` | function | Splits [startAngle, endAngle] proportionally to `values`. |
| `slotAt` | function | Index of the equal-width slot centred on `offset + i * TAU / count` that `angle` falls in. |
| `sma` | function | Simple moving average over `period` points; null until a full window of numbers exists. |
| `smoothPath` | function | SVG path through the points as a Catmull-Rom spline converted to cubic Béziers: smooth, passing through every point. |
| `smoothPoints` | function | Moving average over three points, `passes` times; the ends stay where the pen started and stopped. |
| `snapTime` | function | Rounds `time` to the nearest hour (`step` under a day) or the nearest local midnight. |
| `sortedFinite` | function | Finite values, sorted ascending (a new array). |
| `spinRotation` | function | Rotation after `seconds` of the idle spin at `speed` degrees per second (eastwards view drift). |
| `spreadLabels` | function | Vertical collision avoidance for a column of labels. |
| `spreadSlopeLabels` | function | Moves labels apart so neighbours keep at least `gap` pixels between their centers, staying inside `[min, max]` and keeping their original order. |
| `squarify` | function | Squarified treemap: splits `rect` into one rectangle per value, areas proportional to the values, keeping them as close to squares as possible. |
| `stackAxes` | function | Margins and offsets for axes that stack outward from the plot on each side, in the order given. |
| `stackLayers` | function | Stacks series on top of each other per index. |
| `stackLayout` | function | Offsets of drawings stacked top to bottom, and the size of the whole stack. |
| `standardDeviation` | function | Sample standard deviation (n - 1 in the denominator); 0 below two values. |
| `startCursor` | function | Where the crosshair appears when a plot is focused: the middle of the window. |
| `startOf` | function | Start of the calendar unit holding `time`, in local time. |
| `stitchRing` | function | Walks the arc list of one ring; `~i` is arc `i` backwards. |
| `stockStats` | function | Summary numbers of a price series: returns, volatility, extremes and the maximum drawdown. |
| `streamLayout` | function | Baseline-shifted stacking for stream graphs. |
| `streamOrder` | function | Stacking order. |
| `sturgesBinCount` | function | Sturges' rule: `ceil(log2 n) + 1` bins. |
| `subtreeSize` | function | Every node below `node`. |
| `syncKeyOf` | function | `(value: XValue) => SyncKey` |
| `TAU` | constant | `number` |
| `thinPoints` | function | Drops points closer than `minDistance` to the previous kept one; the last point is always kept. |
| `thinTicks` | function | Drops labels that would collide, keeping an even rhythm (every 2nd, 3rd, ...) so the first label always stays. |
| `tickStep` | function | Step between ticks: 1, 2 or 5 times a power of ten, close to `span / count`. |
| `timeScale` | function | `({ domain, range }: TimeScaleOptions) => TimeScale` |
| `timeTicks` | function | Calendar-aligned ticks (local midnight, Mondays, first of the month, January) with es-PE labels. |
| `tint` | function | Mixes `percent`% of `color` into `base` (the surface by default). |
| `toggleValue` | function | Adds the value to a set filter, or removes it; a set that becomes empty clears the dimension. |
| `TONE_COLORS` | constant | Stroke/text color and soft fill for annotations and status marks. |
| `tooltipFit` | function | Keeps the tooltip inside narrow frames: below 480 px it flips at the middle and its width is capped to half the container (`cqw`, the chart frame is a size container). |
| `tooltipLeft` | function | Left edge of a tooltip `width` wide next to anchor `x`, kept inside `containerWidth`. |
| `toPolar` | function | Angle (0 at twelve o'clock, clockwise) and distance of a point around `center`. |
| `topologyFeatures` | function | Regions of a topology object as lon/lat features. |
| `toScreen` | function | Screen position of a point drawn at zoom 1. |
| `toVec` | function | `[lon, lat]` in degrees to a unit vector. |
| `toXY` | function | `[value, cross]` to screen `x,y`, swapping axes for horizontal charts. |
| `treeEdgePath` | function | SVG path from a parent box to a child box. |
| `treeKeyMove` | function | Maps an arrow key to a tree move relative to the drawing: in a top-down chart Down goes to the first child and Right to the next sibling; in a left-to-right chart Right goes to th… |
| `treeLayout` | function | Tidy layout of a tree: parents centred over their children, no two boxes on the same level closer than `siblingGap`, levels `levelGap` apart. |
| `treemapLayout` | function | Nested squarified layout of `root`'s subtree inside `rect`. |
| `treeNeighbor` | function | Node reached from `id` by `move` among the laid-out (visible) nodes. |
| `treePathToRoot` | function | Ids from the root down to `id` (inclusive), following `parentId`. |
| `truncateLabel` | function | Shortens `label` with an ellipsis so it fits `maxWidth` pixels at `fontSize`. |
| `unionExtent` | function | Smallest range covering every extent; null when none is finite. |
| `UNIT_FRAME_CLASS` | constant | Unit charts make their frame a named container, so the HTML around the drawing follows the chart width instead of the viewport. |
| `UNIT_ICONS` | constant | `{ readonly person: { readonly path: "M12 2.5a4 4 0 1 1 0 8a4 4 0 1 1 0-8zM4.5 21.5v-2.8c0-3.6 3.3-6.2 7.5-6.2s7.5 2.6 7…` |
| `UNIT_LEGEND_CLASS` | constant | Legend under the drawing in narrow containers, at its requested place from `@sm` up. |
| `unitCount` | function | 23 people at 5 per icon -> 4 full icons and a 0.6 icon. |
| `unitFractions` | function | Fill of every unit a value takes: `unitFractions(23, 5)` -> `[1, 1, 1, 1, 0.6]`. |
| `useAnimatedNumber` | hook | Eases a displayed number towards `target` (cubic ease-out). |
| `useAnimatedView` | hook | Animates a partition view (the zoom window of a sunburst or icicle) towards `target` with `requestAnimationFrame`. |
| `useCategoryExplorer` | hook | Hover and keyboard cursor for charts whose marks belong to categories (units, cells, seats, rows). |
| `useChartInk` | hook | State and overlay of the ruler and freehand-ink tools. |
| `useChartSize` | hook | Tracks the content box of an element with a ResizeObserver. |
| `useChartSync` | hook | Subscribes to a sync channel; with no `syncId` it is inert and never re-renders. |
| `useChartWidth` | hook | Width only (kept for charts that do not need the height). |
| `useCrossfilter` | hook | The shared dataset and filters of the nearest `CrossfilterProvider`. |
| `useDistributionLegend` | hook | Colors, legend toggling and highlight for a list of series. |
| `useDrill` | hook | Builds the hierarchy once per data set and keeps the focused (zoomed) node. |
| `useEntryAnimation` | hook | Plays an entry animation once per `replayKey` with the Web Animations API. |
| `useIndexNavigation` | hook | Active-item state for charts made of discrete items (slices, axes, stages). |
| `useIsomorphicLayoutEffect` | hook | Layout effect in the browser, plain effect on the server (no SSR warning). |
| `useMapGeometry` | hook | Fits `map` into `width` x `height`. |
| `useMapView` | hook | Zoom and pan state of a map: wheel, drag, two-finger pinch, and imperative `zoomBy` / `fit` / `focusBox` for buttons, keyboard and cluster clicks. |
| `usePanZoom` | hook | Pan (drag), zoom (wheel, pinch, buttons) for an element that holds a transformed stage. |
| `useReducedMotion` | hook | True when the user asked the OS for less motion. |
| `useSeriesState` | hook | Legend-driven visibility and highlight, shared by every chart type. |
| `useStockStream` | hook | State for a live price series. |
| `viewFitting` | function | View that frames a box given in zoom 1 pixels inside the viewport. |
| `viewMatrix` | function | Rows of the view basis: east, north and the direction towards the viewer at the rotation's center. |
| `viewToScreen` | function | View coordinates to screen pixels (y grows downwards). |
| `violinPath` | function | Closed outline of a (half) violin from a density curve. |
| `visibleMax` | function | Largest value among the `limit` bars that are on screen at this moment. |
| `visibleTree` | function | The part of the tree that is visible, as layout input. |
| `vwap` | function | Volume weighted average price anchored at `from`: running sum of the typical price `(high + low + close) / 3` times volume, over the running volume. |
| `waffleCounts` | function | Cells per category in a waffle of `cells` cells. |
| `waterfallLayout` | function | Running totals for a list of steps. |
| `wrapLon` | function | Longitude wrapped into [-180, 180). |
| `xyLayout` | function | Two continuous axes (scatter, bubble, histogram). |
| `zoomAround` | function | Scales `view` by `factor` keeping the screen point `px, py` fixed. |
| `zoomAt` | function | Multiplies the zoom by `factor` keeping the screen point (`cx`, `cy`) fixed. |

## @jcsoftdev/ui/containers

| Export | Kind | Summary |
| --- | --- | --- |
| `addChild` | function | Adds `child` at the end of the group `groupId`. |
| `aggregateValues` | function | Aggregates numeric values; `count` counts non-empty values. |
| `ancestorsOf` | function | Ancestors of `id`, root first; empty when unknown. |
| `applyAdvancedFilter` | function | `<T>(rows: readonly T[], columns: readonly DataGridColumn<T>[], node: FilterGroup \\| undefined) => T[]` |
| `BlockCache` | class | Fixed-size blocks of rows fetched on demand. |
| `buildDisplayRows` | function | Flattens rows into what the grid renders: with `groupBy`, a group row per distinct value (by level, carrying the count and the column aggregates of all its rows) followed by its c… |
| `buildHeaderGroups` | function | One list of cells per header level, outermost first. |
| `buildPivot` | function | `<T>(data: readonly T[], columns: readonly DataGridColumn<T>[], config: PivotConfig) => PivotResult` |
| `buildSheet` | function | Finds every formula cell, links the dependency graph and evaluates the sheet. |
| `buildTreeRows` | function | Depth-first flattening. |
| `canRedo` | function | `(state: HistoryState<unknown>) => boolean` |
| `canUndo` | function | `(state: HistoryState<unknown>) => boolean` |
| `cellAddress` | function | `B3` for row 2, column 1 (0-based). |
| `cellToNumber` | function | Finite number of a numeric-like cell value (dates become their time), null otherwise. |
| `cellToTime` | function | Epoch milliseconds of a date-like cell value, null when it is not one. |
| `checkedSetValues` | function | Checked values of a set filter: every option while the filter is inactive. |
| `clampWidth` | function | `<T>(width: number, column: DataGridColumn<T>) => number` |
| `columnAlign` | function | `<T>(column: DataGridColumn<T>) => ColumnAlign` |
| `columnIndex` | function | A -> 0, AA -> 26; -1 when the text is not a column label. |
| `columnLabel` | function | 0 -> A, 25 -> Z, 26 -> AA. |
| `commandSize` | function | Number of cells or rows a command touches (for announcements). |
| `compareValues` | function | Ascending order; empty values always go last (callers keep them last in descending too). |
| `computeAggregates` | function | `<T>(rows: readonly T[], columns: readonly DataGridColumn<T>[]) => Record<string, number \\| null>` |
| `computeVariableWindow` | function | Windowing for rows of different heights (detail panels between data rows). |
| `computeVirtualWindow` | function | `({ count, rowHeight, viewportHeight, scrollTop, overscan, }: VirtualWindowInput) => VirtualWindow` |
| `countActiveFilters` | function | `(filters: Filters) => number` |
| `countConditions` | function | `(node: FilterNode) => number` |
| `createHistory` | function | `<R = unknown>(depth?: number) => HistoryState<R>` |
| `DEFAULT_DATA_GRID_LABELS` | constant | `DataGridLabels` |
| `DEFAULT_HISTORY_DEPTH` | constant | `100` |
| `defaultWidth` | function | Starting width: the column's own or the type default, never narrower than its header. |
| `describeFilter` | function | Readable summary, for example `(Barbero es Luis Y Total > 30)`. |
| `dirtyCells` | function | Cells that must be recalculated after `key` changes: itself and everything that reads it. |
| `displayValue` | function | The value a grid cell shows: formula results as plain values, errors as their code. |
| `distinctValues` | function | Distinct select-filter values of a column, sorted. |
| `downloadCSV` | function | Starts a CSV download in the browser (no-op on the server). |
| `downloadFile` | function | Starts a file download in the browser (no-op on the server). |
| `dropIndex` | function | Insert index for a pointer at `y`, from the vertical midpoints of the cards left in a column. |
| `emptyGroup` | function | `(logic?: FilterLogic, id?: string) => FilterGroup` |
| `evaluateCondition` | function | `<T>(row: T, condition: FilterCondition, columns: readonly DataGridColumn<T>[]) => boolean` |
| `evaluateFormula` | function | Evaluates a parsed formula to a single value (a bare range is an error, like in a cell). |
| `evaluateNode` | function | `<T>(row: T, node: FilterNode, columns: readonly DataGridColumn<T>[]) => boolean` |
| `extendRange` | function | Moves the focus corner by `dr` / `dc` inside the limits (Shift + arrows). |
| `fillColumnWidths` | function | Widths that fill `available` pixels: when the columns add up to less (`reserved` is the width of fixed extras such as the selection column), the leftover goes to the flexible colu… |
| `filterKindOf` | function | `<T>(column: DataGridColumn<T>) => FilterKind` |
| `filterRows` | function | Keeps rows that pass every column filter and, when `search` is given, contain every word of it in some searchable column (raw or formatted text, accents ignored). |
| `flattenTree` | function | Rows currently visible, in display order, given the set of expanded folder ids. |
| `folderIds` | function | Ids of every folder (used to expand all by default). |
| `formatAggregate` | function | Formats an aggregate with the column formatter; counts are plain integers. |
| `formatCellValue` | function | `<T>(value: CellValue, column: DataGridColumn<T>) => string` |
| `FORMULA_FUNCTIONS` | constant | Names of the functions a formula may call. |
| `formulaError` | function | `(code: ErrorCode) => FormulaError` |
| `FormulaError` | class | `typeof FormulaError` |
| `formulaText` | function | `(value: FormulaValue) => string` |
| `getCellValue` | function | `<T>(row: T, column: DataGridColumn<T>) => CellValue` |
| `gridToSheet` | function | Sheet with one column per grid column (header text, typed values) and one row per grid row. |
| `groupPathOf` | function | `<T>(column: DataGridColumn<T>) => string[]` |
| `growWeight` | function | Share of the leftover width a column takes: `grow`, else 1 for text columns and 0 for the rest. |
| `headerFitWidth` | function | Width the uppercase header label needs next to its sort and menu buttons. |
| `inRange` | function | `(range: CellRange \\| null, r: number, c: number) => boolean` |
| `insertDetailRows` | function | Inserts a detail row after every data row whose key is in `expanded`. |
| `invertCommand` | function | The command that cancels `command`. |
| `isConditionActive` | function | A condition counts once it has what its operator needs. |
| `isErrorText` | function | Whether a displayed value is the text of a formula error. |
| `isFilterActive` | function | `(filter: FilterValue \\| undefined) => boolean` |
| `isFormulaError` | function | `(value: unknown) => value is FormulaError` |
| `isFormulaText` | function | `(value: unknown) => value is string` |
| `isNodeActive` | function | Empty groups and incomplete conditions are ignored; a group with no active child matches all. |
| `isNoop` | function | A command that changes nothing is not worth an undo step. |
| `isoDayBounds` | function | Epoch milliseconds of an ISO `yyyy-mm-dd` day, local midnight or the end of that day. |
| `isPivotValid` | function | `<T>(config: PivotConfig \\| undefined, columns: readonly DataGridColumn<T>[]) => config is PivotConfig` |
| `keyboardDelta` | function | Keyboard step in percent for a separator key, or null when the key is not handled. |
| `keyboardTarget` | function | Where a grabbed card goes for an arrow key: sideways keeps the row, vertical reorders. |
| `lineRootMargin` | function | The `rootMargin` that shrinks the observed area to a thin band at `offset`, to wake up when a step crosses the line. |
| `locateCard` | function | `(columns: KanbanColumnData[], cardId: string) => { columnId: string; index: number; } \\| null` |
| `matchesFilter` | function | `<T>(value: CellValue, filter: FilterValue, column: DataGridColumn<T>) => boolean` |
| `MAX_COLUMN_WIDTH` | constant | `640` |
| `MIN_COLUMN_WIDTH` | constant | `60` |
| `moveCard` | function | Moves a card. |
| `moveColumn` | function | Moves `id` one step (`delta` -1 / +1) in `order`. |
| `moveColumnTo` | function | Moves `id` before or after `targetId` (drag and drop). |
| `moveRowBy` | function | Moves a row one step (keyboard). |
| `moveRowTo` | function | Moves a row before or after another one (drag and drop). |
| `nearestIndex` | function | Index of the slide whose left edge is closest to `scrollLeft`. |
| `newCondition` | function | `<T>(column: DataGridColumn<T>) => FilterCondition` |
| `newFilterId` | function | `(prefix?: string) => string` |
| `NO_PINNED_ROWS` | constant | `PinnedRows` |
| `normalizeSizes` | function | Initial layout in percent summing to 100. |
| `normalizeText` | function | Lower case, without accents, so "peluqueria" finds "Peluquería". |
| `operatorNeedsValue` | function | `(operator: FilterOperator) => boolean` |
| `operatorsFor` | function | `<T>(column: DataGridColumn<T>) => FilterOperator[]` |
| `pageCount` | function | `(total: number, pageSize: number) => number` |
| `pageStep` | function | Rows that fit in the viewport: the PageUp/PageDown step. |
| `parseAddress` | function | Reads `B3`, `$B$3` or `R3C2`; null for anything else. |
| `parseFormula` | function | Parses a formula; the leading `=` is optional. |
| `parseLooseNumber` | function | A number from pasted text such as `S/ 1,234.50`, `12,5` or `-3`: currency marks and spaces are dropped, a lone comma followed by one or two digits is a decimal comma, other commas… |
| `parseStoredLayout` | function | `(raw: string \\| null) => Partial<GridLayout> \\| null` |
| `parseTSV` | function | Parses tab separated text (the clipboard format of spreadsheets): quoted fields may hold tabs, quotes (`""`) and line breaks. |
| `pickActiveStep` | function | The step a reader is on: the one that contains the trigger `line` (a y coordinate). |
| `pinnedSideOf` | function | `(pinned: PinnedRows, key: string) => RowPinSide \\| null` |
| `PIVOT_TOTAL_ID` | constant | `"pivot:total"` |
| `pivotColumns` | function | Grid columns of a pivot: one per row field, one per pivot key and a trailing total. |
| `pivotFooter` | function | Footer values for the pivot columns (exact for every aggregate kind). |
| `planFill` | function | Cells a fill writes and where each value comes from: `down` copies the first row, `right` the first column. |
| `planPaste` | function | Cells a paste writes. |
| `precedentsOf` | function | Cells the formula at (r, c) reads, as `[row, col]` pairs. |
| `pushCommand` | function | Records a command; the redo branch is dropped and the oldest commands past `depth` fall off. |
| `rangeBetween` | function | Ids between `anchor` and `target` (inclusive) in display order; just `target` without anchor. |
| `rangeBounds` | function | `(range: CellRange) => RangeBounds` |
| `rangeStats` | function | Count, sum, average, min and max of the numbers in a range (`undefined` skips the cell). |
| `rangeToTSV` | function | Tab separated text of a range. |
| `rawToFormulaValue` | function | A raw cell as a formula operand: dates are ISO text, anything unreadable is empty. |
| `reconcileLayout` | function | Reconciles a stored layout with the current columns: unknown ids drop, new ones append. |
| `redoCommand` | function | Moves the last undone command back to the past; null when there is nothing to redo. |
| `referencesOf` | function | Every cell a formula reads, ranges expanded; references and ranges outside the sheet are left out (they evaluate to #REF!). |
| `removeNode` | function | Removes the node with `id`; the root itself stays. |
| `resizePair` | function | Moves the boundary between panel `index` and `index + 1` by `delta` percent. |
| `sameCellValue` | function | Whether an edited value equals the previous one (numbers by identity, the rest by text). |
| `scrollLeftToReveal` | function | Horizontal scroll that reveals a scrolling (unpinned) column at `[left, left + width)` without it hiding under the pinned columns of either edge. |
| `scrollTopToReveal` | function | Scroll position that brings row `index` fully into view, moving as little as possible. |
| `scrollTopToRevealSpan` | function | Like `scrollTopToReveal` for a row at any `top` with any `height`, keeping it clear of rows that stay on screen on their own (pinned rows): `insetTop` / `insetBottom` px of the vi… |
| `searchOptions` | function | Options that contain the search text (accents and case ignored). |
| `selectKey` | function | Value used by the select filter and by grouping: dates by day, booleans as Sí / No, the rest as text. |
| `SET_NONE` | constant | Select-filter value that matches no row: "nothing checked" in a set filter. |
| `setHistoryDepth` | function | Shrinks (or grows) the depth, trimming the oldest commands. |
| `sheetValue` | function | Result of a cell, formulas evaluated. |
| `shiftFormula` | function | Moves the relative references of a formula by `dr` rows and `dc` columns, the way a spreadsheet does when a formula is filled down or right; `$` references stay. |
| `sortRows` | function | Stable multi-column sort. |
| `splitPinnedRows` | function | Pulls the pinned data rows out of the flat display list, in pin order. |
| `stepIndex` | function | Next slide index; wraps when `loop`, otherwise stays at the ends. |
| `stepProgress` | function | Scroll progress through a step, 0 when its top meets the line and 1 when its bottom does. |
| `summarizeHistory` | function | `(state: HistoryState<unknown>) => HistorySummary` |
| `toCSV` | function | CSV with a header row. |
| `togglePinnedRow` | function | Pins `key` to `side`, or unpins it when it is already there. |
| `toggleSetMember` | function | `(set: ReadonlySet<string>, key: string) => Set<string>` |
| `toggleSetValues` | function | Checks or unchecks `values` in a set filter and returns the new filter: `undefined` when every option ends up checked (no filtering), the `SET_NONE` marker when none is. |
| `toggleSort` | function | Header click: asc, then desc, then off. |
| `treeStep` | function | WAI-ARIA tree navigation: what a key does on the row `currentId`. |
| `triggerLine` | function | Viewport coordinate of the trigger line: `offset` is its fraction (0 top, 1 bottom) of the scroll area. |
| `typeahead` | function | Next row whose name starts with `query`, searching after `currentId` and wrapping. |
| `undoCommand` | function | Moves the last command to the redo branch; null when there is nothing to undo. |
| `updateCell` | function | Sets one cell and recalculates only what depends on it. |
| `updateNode` | function | Replaces the node with `id` (immutably). |
| `valueKindOf` | function | `<T>(column: DataGridColumn<T>) => ValueKind` |
| `wipStatus` | function | `(count: number, limit?: number) => WipStatus` |
| `withAncestors` | function | Keeps `matches` plus every ancestor of a match, in the order of `all`, so a filtered tree still shows the path to each hit. |
| `xlsxFilename` | function | File name with the `.xlsx` extension. |

## @jcsoftdev/ui/forms

| Export | Kind | Summary |
| --- | --- | --- |
| `clampValue` | function | `(value: number, min: number, max: number) => number` |
| `EMOJI_CATEGORIES` | constant | Small curated set, kept in its own module so apps that never open a picker do not ship it. |
| `gridMove` | function | Next index in a grid of `count` cells and `columns` columns for an arrow/Home/End key. |
| `keyboardValue` | function | Next value for a slider key, or null when the key is not handled. |
| `nearestThumb` | function | Thumb a pointer press should grab: the closest one; on a tie, the one the press is outside of. |
| `ratingFromPointer` | function | Rating under the pointer: the left half of a star counts as .5 when halves are allowed. |
| `ratingKey` | function | Next rating for a keyboard key, or null when the key is not handled. |
| `ratioOf` | function | Position of a value along the track, 0..1. |
| `roundRating` | function | Rounds a value to the nearest `precision` (1 = whole stars, 0.5 = halves) inside [0, max]. |
| `searchEmojis` | function | Entries whose name contains every word of the query (accents and case ignored). |
| `setRangeThumb` | function | Moves one thumb of a range, never crossing the other one and keeping `minGap` between them. |
| `snapToStep` | function | Snaps to the nearest multiple of `step` counted from `min` (or from 0 when `min` is not finite), kept inside [min, max]. |
| `starFill` | function | Fill of star `index` (0-based) for a rating: 0, 0.5 or 1. |
| `valueFromRatio` | function | `(ratio: number, min: number, max: number, step: number) => number` |

## @jcsoftdev/ui/navigation

| Export | Kind | Summary |
| --- | --- | --- |
| `pickActive` | function | Active section from the headings currently intersecting the observation band: the first visible one in document order. |

## @jcsoftdev/ui/overlays

| Export | Kind | Summary |
| --- | --- | --- |
| `restoreFocusOnClose` | function | Compose inside `onCloseAutoFocus` of a `*.Content`. |
| `useCapturePreviousFocus` | hook | Radix can only return focus to the opener of a Dialog/Drawer when that opener is the component's own `Trigger`. |
| `usePreviousFocus` | hook | `() => FocusRef \\| null` |

## @jcsoftdev/ui/rich-text

| Export | Kind | Summary |
| --- | --- | --- |
| `htmlToText` | function | Plain text of sanitized HTML, used to detect an empty editor. |
| `isSafeUrl` | function | True for http(s), mailto, tel and scheme-less (relative or fragment) URLs. |
| `richTextContentClass` | constant | Typography for editor and read-only content; preflight resets lists and headings. |
| `sanitizeHtml` | function | Returns safe, balanced HTML containing only the editor's vocabulary. |

## @jcsoftdev/ui/shell

| Export | Kind | Summary |
| --- | --- | --- |
| `APP_SHELL_BREAKPOINT` | constant | Container width (px) below which the shell is compact: the sidebar becomes a drawer. |
| `useAppShell` | hook | `null` outside an `AppShell`; otherwise whether the shell is narrower than 900 px. |

## @jcsoftdev/ui/utils

| Export | Kind | Summary |
| --- | --- | --- |
| `cn` | function | Merge class names, resolving conflicting Tailwind utilities (last one wins). |
| `usePrefersReducedMotion` | hook | True when the user asked the OS for reduced motion; false during SSR. |

## @jcsoftdev/ui/xlsx

| Export | Kind | Summary |
| --- | --- | --- |
| `buildXlsx` | function | Builds the bytes of an .xlsx file: workbook, one worksheet per sheet, shared strings, styles (bold header, number and date formats) and document properties. |
| `columnName` | function | A, B, … Z, AA … for a 0-based column index. |
| `crc32` | function | CRC-32 of `bytes`. |
| `createZip` | function | Builds a ZIP archive holding `entries` uncompressed. |
| `dosDateTime` | function | MS-DOS date and time fields (local time, 2 second resolution, years 1980 to 2107). |
| `escapeXml` | function | Escapes text for an XML element or attribute and drops characters XML cannot hold. |
| `excelSerial` | function | Excel serial number of a local date and time (1900 date system). |
| `sheetName` | function | Tab name Excel accepts: no `[]:*?/\`, 1 to 31 characters, unique among `taken` (case-insensitive). |
| `XLSX_MIME` | constant | `"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"` |