diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 3cc47f0..9a3b165 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -36,7 +36,7 @@ importers:
ui:
dependencies:
'@unitae/tokens':
- specifier: ^0.1.0 || ^0.2.0
+ specifier: ^0.1.0 || ^0.2.0 || ^0.3.0
version: 0.1.0(@fontsource/ibm-plex-sans@5.3.0)
class-variance-authority:
specifier: ^0.7.1
diff --git a/tokens/README.md b/tokens/README.md
index d650202..46765ad 100644
--- a/tokens/README.md
+++ b/tokens/README.md
@@ -50,6 +50,10 @@ Also set by the theme:
- **Radius** — one family: 6 px containers, 5 px controls. The Tailwind scale is deliberately remapped
(`rounded-xl` → 6 px, `rounded-2xl` → 8 px) so existing markup adopts the new geometry; prefer
`rounded-lg` / `rounded-md` in new code.
+- **Type** — semantic sizes beside Tailwind's own (`text-xs` … `text-xl` keep their sizes): `text-body` 14 px for
+ running text, `text-h1` 24 px for the page title, `text-h2` 15 px for a section or panel title, `text-metric` 26 px
+ for a headline number. Each sets its line height, and the titles their weight and tracking. `base.css` sets the body
+ to `text-body`; an app without it sets `body` itself.
- **Motion** — every `transition` utility defaults to 120 ms with `cubic-bezier(0.2, 0, 0, 1)`;
`ease-standard` is available, and `base.css` honours `prefers-reduced-motion`.
- **Shadows** — light by design: separate with borders, keep elevation for floating surfaces.
@@ -94,8 +98,10 @@ const style = mapStyle({
- Only the pins wear colour: no places, shops, transport, shields, one-way arrows or house numbers (the pins
already carry the numbers the lists show).
-- Labels use the `MAP_FONTS` glyph stacks (IBM Plex Sans Regular, Medium, Italic); names written in Devanagari ask
- for `Noto Sans Devanagari Regular v1`, as Protomaps does.
+- Labels use the `MAP_FONTS` glyph stacks, `Unitae Map Regular`, `Medium` and `Italic`: IBM Plex Sans turned into map
+ glyphs. They carry another name because the font's licence (OFL 1.1) reserves « Plex » for unmodified versions;
+ serve them with the OFL and IBM's copyright. Names written in Devanagari ask for `Noto Sans Devanagari Regular v1`,
+ as Protomaps does.
- Nothing draws an icon, so the style needs no sprite.
- Credit `MAP_ATTRIBUTION` wherever the map shows: OpenStreetMap's licence wants it visible.
- The tests check, in both modes, that labels reach 4.5:1 on their halo (the ground), that a pin — primary in a
diff --git a/tokens/package.json b/tokens/package.json
index c742f26..8ffed3d 100644
--- a/tokens/package.json
+++ b/tokens/package.json
@@ -1,6 +1,6 @@
{
"name": "@unitae/tokens",
- "version": "0.2.0",
+ "version": "0.3.0",
"description": "Design tokens for Unitae: colours, type, radius, motion, chart palettes and the map style, as CSS variables, a Tailwind v4 theme and a JS API.",
"license": "MIT",
"type": "module",
diff --git a/tokens/src/css.ts b/tokens/src/css.ts
index 4e4d28a..93bd7fe 100644
--- a/tokens/src/css.ts
+++ b/tokens/src/css.ts
@@ -1,4 +1,4 @@
-import { type ColorName, colorNames, colors, fonts, motion, radii, shadows } from './tokens.ts'
+import { type ColorName, colorNames, colors, fonts, motion, radii, shadows, typeScale } from './tokens.ts'
/**
* Tailwind / shadcn colour names → Unitae tokens. These are the exact names the apps' components
@@ -99,6 +99,28 @@ function declarations(entries: [string, string][], indent = ' '): string {
}
/** Raw tokens as `--u-*` custom properties: light on `:root`, dark on `.dark` / `[data-theme="dark"]`. */
+/** The type scale as raw tokens: `--u-text-h1`, `--u-text-h1-line-height`, `--u-text-h1-weight`… */
+function typeTokens(): [string, string][] {
+ return Object.entries(typeScale).flatMap(([name, step]): [string, string][] => [
+ [`--u-text-${name}`, step.size],
+ [`--u-text-${name}-line-height`, step.lineHeight],
+ ...('weight' in step ? [[`--u-text-${name}-weight`, step.weight] as [string, string]] : []),
+ ...('letterSpacing' in step ? [[`--u-text-${name}-letter-spacing`, step.letterSpacing] as [string, string]] : []),
+ ])
+}
+
+/** The type scale as Tailwind text utilities: `text-h1` sets the size with its line height, weight and tracking. */
+function typeTheme(): [string, string][] {
+ return Object.entries(typeScale).flatMap(([name, step]): [string, string][] => [
+ [`--text-${name}`, `var(--u-text-${name})`],
+ [`--text-${name}--line-height`, `var(--u-text-${name}-line-height)`],
+ ...('weight' in step ? [[`--text-${name}--font-weight`, `var(--u-text-${name}-weight)`] as [string, string]] : []),
+ ...('letterSpacing' in step
+ ? [[`--text-${name}--letter-spacing`, `var(--u-text-${name}-letter-spacing)`] as [string, string]]
+ : []),
+ ])
+}
+
export function tokensCss(version: string): string {
const lightColors = colorNames.map((n): [string, string] => [`--u-${n}`, colors.light[n]])
const darkColors = colorNames.map((n): [string, string] => [`--u-${n}`, colors.dark[n]])
@@ -111,6 +133,7 @@ export function tokensCss(version: string): string {
['--u-duration-fast', motion.fast],
['--u-duration-slow', motion.slow],
['--u-ease', motion.ease],
+ ...typeTokens(),
]
return `${header(version, 'raw tokens')}
:root {
@@ -150,6 +173,7 @@ ${declarations([
['--font-mono', 'var(--u-font-mono)'],
...radiusEntries,
...shadowEntries,
+ ...typeTheme(),
['--ease-standard', 'var(--u-ease)'],
['--default-transition-duration', 'var(--u-duration-fast)'],
['--default-transition-timing-function', 'var(--u-ease)'],
@@ -179,6 +203,8 @@ export function baseCss(version: string): string {
background-color: var(--u-bg);
color: var(--u-fg);
font-family: var(--u-font-sans);
+ font-size: var(--u-text-body);
+ line-height: var(--u-text-body-line-height);
}
}
diff --git a/tokens/src/index.ts b/tokens/src/index.ts
index 9f83283..237b566 100644
--- a/tokens/src/index.ts
+++ b/tokens/src/index.ts
@@ -3,7 +3,7 @@ import { type ColorName, type ColorScale, colorNames, colors, type Mode } from '
export { chroma, contrast, lightness, toHex } from './color.ts'
export type { ColorName, ColorScale, Mode } from './tokens.ts'
-export { categorical, colorNames, colors, fonts, motion, ordinal, radii, shadows } from './tokens.ts'
+export { categorical, colorNames, colors, fonts, motion, ordinal, radii, shadows, typeScale } from './tokens.ts'
function toHexScale(scale: ColorScale): ColorScale {
const out = {} as ColorScale
diff --git a/tokens/src/map-style.ts b/tokens/src/map-style.ts
index 8120e62..822fbb9 100644
--- a/tokens/src/map-style.ts
+++ b/tokens/src/map-style.ts
@@ -1,5 +1,5 @@
/**
- * The Unitae map style: Protomaps vector tiles painted with the map tokens, labels in IBM Plex.
+ * The Unitae map style: Protomaps vector tiles painted with the map tokens, labels in IBM Plex letterforms.
*
* A quiet grey ground for our pins: no places, shops, transport, shields or one-way arrows, and no house numbers —
* the pins already carry the numbers the lists show, and a second set of numbers would confuse. Nothing draws an
@@ -11,11 +11,15 @@ import { type Flavor, layers } from '@protomaps/basemaps'
import { hexColors } from './index.ts'
import type { Mode } from './tokens.ts'
-/** The glyph font stacks the style asks for. The host serves them under the `glyphs` address. */
+/**
+ * The glyph font stacks the style asks for; the host serves them under the `glyphs` address. They are IBM Plex Sans
+ * turned into map glyphs, under another name: the font's licence (OFL 1.1) reserves the name « Plex » for unmodified
+ * versions, and glyphs are a modified version. Ship the OFL and IBM's copyright with them.
+ */
export const MAP_FONTS = {
- regular: 'IBM Plex Sans Regular',
- medium: 'IBM Plex Sans Medium',
- italic: 'IBM Plex Sans Italic',
+ regular: 'Unitae Map Regular',
+ medium: 'Unitae Map Medium',
+ italic: 'Unitae Map Italic',
} as const
/** Who must be credited wherever the map shows: the tiles and the data under them. */
diff --git a/tokens/src/tokens.ts b/tokens/src/tokens.ts
index debba05..cbb4a75 100644
--- a/tokens/src/tokens.ts
+++ b/tokens/src/tokens.ts
@@ -333,6 +333,18 @@ export const radii = {
'3xl': '10px',
} as const
+/**
+ * Type scale, at the round-1 density (14 px body), from the canvas tokens of direction D. Semantic names only:
+ * Tailwind's own `text-xs` … `text-xl` keep their sizes, so existing markup does not move. `h1` is the page title,
+ * `h2` a section or panel title, `metric` a headline number, `body` the running text.
+ */
+export const typeScale = {
+ body: { size: '0.875rem', lineHeight: '1.375rem' },
+ h2: { size: '0.9375rem', lineHeight: '1.375rem', weight: '600' },
+ h1: { size: '1.5rem', lineHeight: '2rem', weight: '600', letterSpacing: '-0.01em' },
+ metric: { size: '1.625rem', lineHeight: '2rem', weight: '600', letterSpacing: '-0.01em' },
+} as const
+
/** Motion: fast and keyboard-like. Respect `prefers-reduced-motion` (see base.css). */
export const motion = {
fast: '120ms',
diff --git a/tokens/test/__snapshots__/tokens.test.ts.snap b/tokens/test/__snapshots__/tokens.test.ts.snap
index 7605212..22715e1 100644
--- a/tokens/test/__snapshots__/tokens.test.ts.snap
+++ b/tokens/test/__snapshots__/tokens.test.ts.snap
@@ -22,6 +22,8 @@ exports[`generated CSS > base.css 1`] = `
background-color: var(--u-bg);
color: var(--u-fg);
font-family: var(--u-font-sans);
+ font-size: var(--u-text-body);
+ line-height: var(--u-text-body-line-height);
}
}
@@ -142,6 +144,19 @@ exports[`generated CSS > theme.css 1`] = `
--shadow-lg: var(--u-shadow-lg);
--shadow-xl: var(--u-shadow-xl);
--shadow-2xl: var(--u-shadow-2xl);
+ --text-body: var(--u-text-body);
+ --text-body--line-height: var(--u-text-body-line-height);
+ --text-h2: var(--u-text-h2);
+ --text-h2--line-height: var(--u-text-h2-line-height);
+ --text-h2--font-weight: var(--u-text-h2-weight);
+ --text-h1: var(--u-text-h1);
+ --text-h1--line-height: var(--u-text-h1-line-height);
+ --text-h1--font-weight: var(--u-text-h1-weight);
+ --text-h1--letter-spacing: var(--u-text-h1-letter-spacing);
+ --text-metric: var(--u-text-metric);
+ --text-metric--line-height: var(--u-text-metric-line-height);
+ --text-metric--font-weight: var(--u-text-metric-weight);
+ --text-metric--letter-spacing: var(--u-text-metric-letter-spacing);
--ease-standard: var(--u-ease);
--default-transition-duration: var(--u-duration-fast);
--default-transition-timing-function: var(--u-ease);
@@ -247,6 +262,19 @@ exports[`generated CSS > tokens.css 1`] = `
--u-duration-fast: 120ms;
--u-duration-slow: 240ms;
--u-ease: cubic-bezier(0.2, 0, 0, 1);
+ --u-text-body: 0.875rem;
+ --u-text-body-line-height: 1.375rem;
+ --u-text-h2: 0.9375rem;
+ --u-text-h2-line-height: 1.375rem;
+ --u-text-h2-weight: 600;
+ --u-text-h1: 1.5rem;
+ --u-text-h1-line-height: 2rem;
+ --u-text-h1-weight: 600;
+ --u-text-h1-letter-spacing: -0.01em;
+ --u-text-metric: 1.625rem;
+ --u-text-metric-line-height: 2rem;
+ --u-text-metric-weight: 600;
+ --u-text-metric-letter-spacing: -0.01em;
}
.dark,
diff --git a/tokens/test/map-style.test.ts b/tokens/test/map-style.test.ts
index d3ecf36..20f0370 100644
--- a/tokens/test/map-style.test.ts
+++ b/tokens/test/map-style.test.ts
@@ -5,6 +5,8 @@ import type { Mode } from '../src/tokens.ts'
const modes: Mode[] = ['light', 'dark']
const HEX = /#[0-9a-f]{6}\b/gi
+// A font stack named in a layer: « Unitae Map Regular », « Noto Sans Devanagari Regular v1 »…
+const FONT_NAME = /"[^"]* (?:Regular|Medium|Italic|Bold)(?: v\d+)?"/g
const style = (mode: Mode, lang = 'fr') =>
mapStyle({ mode, lang, tiles: '/tiles/2026-11/{z}/{x}/{y}.mvt', glyphs: '/map-fonts/{fontstack}/{range}.pbf' })
@@ -73,7 +75,7 @@ describe('mapStyle', () => {
expect(ids).toContain('buildings')
})
- it('sets every label in IBM Plex (Devanagari names keep the Noto face Protomaps asks for)', () => {
+ it('sets every label in the map fonts (Devanagari names keep the Noto face Protomaps asks for)', () => {
const allowed = new Set([...Object.values(MAP_FONTS), 'Noto Sans Devanagari Regular v1'])
const fonts = style('light')
.layers.filter((layer) => layer.type === 'symbol')
@@ -83,7 +85,7 @@ describe('mapStyle', () => {
('text-font' in layout && layout['text-font']) || [],
'text-field' in layout ? layout['text-field'] : [],
])
- return text.match(/"[^"]*Sans[^"]*"/g) ?? []
+ return text.match(FONT_NAME) ?? []
})
.map((quoted) => JSON.parse(quoted) as string)
expect(fonts).toContain(MAP_FONTS.regular)
diff --git a/tokens/test/tokens.test.ts b/tokens/test/tokens.test.ts
index cc7b46b..d296c19 100644
--- a/tokens/test/tokens.test.ts
+++ b/tokens/test/tokens.test.ts
@@ -3,7 +3,7 @@ import { describe, expect, it } from 'vitest'
import { chroma, contrast, lightness } from '../src/color.ts'
import { baseCss, fontsCss, themeColors, themeCss, tokensCss } from '../src/css.ts'
import { hexColors } from '../src/index.ts'
-import { type ColorName, colorNames, colors, type Mode, ordinal } from '../src/tokens.ts'
+import { type ColorName, colorNames, colors, type Mode, ordinal, typeScale } from '../src/tokens.ts'
const modes: Mode[] = ['light', 'dark']
const HEX = /^#[0-9a-f]{6}$/
@@ -114,6 +114,12 @@ describe('map', () => {
expect(ratio(mode, 'primary', 'map-ground')).toBeGreaterThanOrEqual(3)
})
+ it(`${mode}: a free entrance's dashed ring stands out from the ground (3:1)`, () => {
+ // MapDot « free »: a dashed ring in the faint grey (light) or the muted grey (dark), over the map's ground.
+ const ring = mode === 'light' ? colors.light['fg-faint'] : colors.dark['fg-muted']
+ expect(contrast(ring, colors[mode]['map-ground'])).toBeGreaterThanOrEqual(3)
+ })
+
it(`${mode}: the map stays grey — no fill is more colourful than a hint`, () => {
for (const fill of ['map-ground', ...fills] as ColorName[]) {
expect(chroma(colors[mode][fill])).toBeLessThan(0.03)
@@ -219,6 +225,41 @@ describe('Tailwind theme', () => {
})
})
+describe('type scale', () => {
+ // Round 1 set the density at a 14 px body; the canvas tokens of direction D draw a 24 px page title, 15 px section
+ // titles and 26 px headline numbers. The apps' own text-xs / sm / base keep their Tailwind sizes.
+ const px = (rem: string) => Number.parseFloat(rem) * 16
+
+ it('sets the body at 14 px, the page title at 24, section titles at 15 and headline numbers at 26', () => {
+ expect(px(typeScale.body.size)).toBe(14)
+ expect(px(typeScale.h1.size)).toBe(24)
+ expect(px(typeScale.h2.size)).toBe(15)
+ expect(px(typeScale.metric.size)).toBe(26)
+ })
+
+ it('gives every step a line height at least as tall as its size', () => {
+ for (const step of Object.values(typeScale)) expect(px(step.lineHeight)).toBeGreaterThanOrEqual(px(step.size))
+ })
+
+ it('maps each step onto a Tailwind text utility with its line height, and its weight where it has one', () => {
+ const theme = themeCss('0.0.0')
+ for (const [name, step] of Object.entries(typeScale)) {
+ expect(theme).toContain(`--text-${name}: var(--u-text-${name});`)
+ expect(theme).toContain(`--text-${name}--line-height: var(--u-text-${name}-line-height);`)
+ if ('weight' in step) expect(theme).toContain(`--text-${name}--font-weight: var(--u-text-${name}-weight);`)
+ }
+ })
+
+ it('leaves Tailwind’s own text sizes alone, so existing markup keeps its size', () => {
+ const theme = themeCss('0.0.0')
+ for (const name of ['xs', 'sm', 'base', 'lg', 'xl']) expect(theme).not.toContain(`--text-${name}:`)
+ })
+
+ it('sets the body size in the optional element defaults', () => {
+ expect(baseCss('0.0.0')).toContain('font-size: var(--u-text-body);')
+ })
+})
+
describe('fonts', () => {
it('imports only files that exist in @fontsource/ibm-plex-sans', () => {
const require = createRequire(import.meta.url)
diff --git a/ui/README.md b/ui/README.md
index 794873e..5d2772e 100644
--- a/ui/README.md
+++ b/ui/README.md
@@ -25,37 +25,40 @@ Tell Tailwind v4 to read the classes the components use, next to the tokens impo
## Components
-| Component | Use it for |
-| ------------------------- | ------------------------------------------------------------------------------------------- |
-| `StatTile`, `MetricStrip` | Headline numbers in one bordered strip, separated by hairlines |
-| `ChartCard` | A chart with title, legend and a Chart / Table switch (`table` + `viewLabels`) |
-| `LineChart` | Trends over time; `area` for the series the chart is about, `context` for a grey comparison |
-| `ColumnChart` | Magnitudes per period; one highlighted period over muted context, `stack`, `goal`, gaps |
-| `BarList` | Ranked horizontal bars, one hue; `other` for the folded tail |
-| `SegmentedBar` | One whole split in ≤ 6 parts; values print inside where they fit |
-| `Sparkline` | Tiny decorative columns beside a number; `goal` line, gaps for future / missing periods |
-| `ProgressBar` | A share of a whole as a thin bar; decorative unless it gets an `aria-label` |
-| `PeriodStepper` | Previous / next period around the current label; `renderLink` for the app's router |
-| `Status`, `StatusIcon` | A state as shape + label (`success`, `warning`, `danger`, `neutral`) |
-| `Tag`, `Kbd` | Quiet attribute labels, keyboard hints |
-| `Avatar` | A person's initials in a quiet disc, next to their name (`initials(name)` is exported too) |
-| `SelectionBar` | Floating actions on a list selection; announces the count, Escape clears |
-| `SegmentedControl` | 2–5 exclusive choices with a sliding indicator and arrow-key navigation; `null` = no choice |
-| `FactList` | Facts as label / value pairs in a `
`; empty values left out, or `emptyLabel` for them |
-| `DateChip` | A day as a small tile, month over day, beside a row that says the full date |
-| `FormSection` | One part of a long form: title, kicker and actions left, fields right (`col-span-full`) |
-| `SaveBar` | A form's save actions at the bottom, with the unsaved-changes dot and an announced label |
-| `Panel` | A bordered block of a page: title and actions, rows edge to edge or `padded` fields, footer |
-| `SectionHeading` | The line above a block: title, quiet count, tag, actions; `collapsible` shows and hides it |
-| `SidePanel` | Edits the selected item beside the main column; sticky, Escape closes, focus goes back |
-| `MapPin` | A place on a map, numbered like the list beside it; a button with hovered / selected states |
-| `MapDot` | An entrance's state in a map editor: on, free, elsewhere, to add, to remove |
-| `MapCluster` | Places too close to tell apart: a quiet disc with their count, a button that zooms in |
-| `MapControls` | Zoom and « Recentrer » over the map; `MapControlGroup` / `MapControlButton` for more |
-| `MapCaption`, `MapCard` | A line about the map (top left); a picked place's card (corner, or full width below 1280) |
-| `MapAttribution` | The data credit, always visible bottom right (pass `MAP_ATTRIBUTION` from the tokens) |
-| `MapStatus` | Loading or failed tiles, in the middle of the map's frame |
-| `Mark`, `Lockup` | The Unitae mark, alone or with the wordmark |
+| Component | Use it for |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `StatTile`, `MetricStrip` | Headline numbers in one bordered strip, separated by hairlines |
+| `ChartCard` | A chart with title, legend and a Chart / Table switch (`table` + `viewLabels`) |
+| `LineChart` | Trends over time; `area` for the series the chart is about, `context` for a grey comparison |
+| `ColumnChart` | Magnitudes per period; one highlighted period over muted context, `stack`, `goal`, gaps |
+| `BarList` | Ranked horizontal bars, one hue; `other` for the folded tail |
+| `SegmentedBar` | One whole split in ≤ 6 parts; values print inside where they fit |
+| `Sparkline` | Tiny decorative columns beside a number; `goal` line, gaps for future / missing periods |
+| `ProgressBar` | A share of a whole as a thin bar; decorative unless it gets an `aria-label` |
+| `ProgressRing` | A share in a list column (« 5/7 »): a thin arc over a track, success once complete |
+| `PeriodStepper` | Previous / next period around the current label; `renderLink` for the app's router |
+| `Status`, `StatusIcon` | A state as shape + label (`success`, `warning`, `danger`, `neutral`) |
+| `Tag`, `Kbd` | Quiet attribute labels, keyboard hints |
+| `Avatar` | A person's initials in a quiet disc, next to their name (`initials(name)` is exported too) |
+| `SelectionBar` | Floating actions on a list selection; announces the count, Escape clears |
+| `SegmentedControl` | 2–5 exclusive choices with a sliding indicator and arrow-key navigation; `null` = no choice |
+| `FactList` | Facts as label / value pairs in a `
`; empty values left out, or `emptyLabel` for them |
+| `DateChip` | A day as a small tile, month over day, beside a row that says the full date |
+| `FormSection` | One part of a long form: title, kicker and actions left, fields right (`col-span-full`) |
+| `SaveBar` | A form's save actions at the bottom, with the unsaved-changes dot and an announced label |
+| `Panel` | A bordered block of a page: title and actions, rows edge to edge or `padded` fields, footer |
+| `SectionHeading` | The line above a block: title, quiet count, tag, actions; `collapsible` shows and hides it |
+| `SidePanel` | Edits the selected item beside the main column; sticky, Escape closes, focus goes back; `walk` steps through the list (« 3 sur 12 ») |
+| `Callout` | A notice in the page (refused save, offline, trial): soft tint + status shape, one action |
+| `DateField` | A date written with its weekday, typed in the reader's order or picked in a month calendar; native picker on touch |
+| `MapPin` | A place on a map, numbered like the list beside it; a button with hovered / selected states |
+| `MapDot` | An entrance's state in a map editor: on, free, elsewhere, to add, to remove |
+| `MapCluster` | Places too close to tell apart: a quiet disc with their count, a button that zooms in |
+| `MapControls` | Zoom and « Recentrer » over the map; `MapControlGroup` / `MapControlButton` for more |
+| `MapCaption`, `MapCard` | A line about the map (top left); a picked place's card (corner, or full width below 1280) |
+| `MapAttribution` | The data credit, always visible bottom right (pass `MAP_ATTRIBUTION` from the tokens) |
+| `MapStatus` | Loading or failed tiles, in the middle of the map's frame |
+| `Mark`, `Lockup` | The Unitae mark, alone or with the wordmark |
Helpers: `seriesColor(i)` (categorical colours in order, folded past eight), `chartMuted`, `chartContext`,
`chartOther`, `cn`.
diff --git a/ui/package.json b/ui/package.json
index 63c9b24..95dc728 100644
--- a/ui/package.json
+++ b/ui/package.json
@@ -1,6 +1,6 @@
{
"name": "@unitae/ui",
- "version": "0.8.0",
+ "version": "0.9.0",
"description": "Unitae UI components: stat tiles, chart kit (with table twins), status, avatars, selection bar, segmented control, form sections, save bar, panels, section headings, map pieces and the brand mark. Built on @unitae/tokens.",
"license": "MIT",
"type": "module",
@@ -37,7 +37,7 @@
"prepublishOnly": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc6 -p tsconfig.build.json && vitest run"
},
"peerDependencies": {
- "@unitae/tokens": "^0.1.0 || ^0.2.0",
+ "@unitae/tokens": "^0.1.0 || ^0.2.0 || ^0.3.0",
"react": "^19.0.0",
"react-dom": "^19.0.0",
"recharts": "^3.0.0"
diff --git a/ui/src/callout.tsx b/ui/src/callout.tsx
new file mode 100644
index 0000000..f60664a
--- /dev/null
+++ b/ui/src/callout.tsx
@@ -0,0 +1,59 @@
+import type { AriaRole, ReactNode } from 'react'
+import { StatusIcon } from './status.tsx'
+import { cn } from './utils.ts'
+
+export type CalloutTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger'
+
+const toneClass: Record = {
+ neutral: 'border-border bg-subtle',
+ info: 'border-transparent bg-brand-soft',
+ success: 'border-transparent bg-success-soft',
+ warning: 'border-transparent bg-warning-soft',
+ danger: 'border-transparent bg-danger-soft',
+}
+
+export interface CalloutProps {
+ tone: CalloutTone
+ /** One short line saying what happened, e.g. « Impossible d’enregistrer ». */
+ title?: ReactNode
+ /** What it means and what to do, in a sentence or two. */
+ children?: ReactNode
+ /** One action at the end of the line, e.g. « Réessayer ». */
+ action?: ReactNode
+ /** `alert` for an error the reader must notice now, `status` for a quiet notice; none for a lasting one. */
+ role?: AriaRole
+ className?: string
+}
+
+/**
+ * A notice inside the page: a refused save, an offline warning, a trial ending. The tone is a soft tint and a status
+ * shape, never colour alone, and the text keeps its own colours. No tinted icon chip, no left border.
+ */
+export function Callout({ tone, title, children, action, role, className }: CalloutProps) {
+ return (
+
+
+ {tone === 'info' ? : }
+
+
+ {title != null &&
{title}
}
+ {children != null &&
{children}
}
+
+ {action != null &&
{action}
}
+
+ )
+}
+
+function InfoIcon() {
+ return (
+
+ )
+}
diff --git a/ui/src/date-field.tsx b/ui/src/date-field.tsx
new file mode 100644
index 0000000..fa3a420
--- /dev/null
+++ b/ui/src/date-field.tsx
@@ -0,0 +1,410 @@
+import { type KeyboardEvent, useEffect, useId, useMemo, useRef, useState } from 'react'
+import { cn } from './utils.ts'
+
+export interface DateFieldLabels {
+ /** The calendar button and the calendar itself, e.g. « Choisir une date ». */
+ openCalendar: string
+ previousMonth: string
+ nextMonth: string
+}
+
+export interface DateFieldProps {
+ id?: string
+ /** Submitted with the form as `YYYY-MM-DD` (empty when no date), through a hidden input. */
+ name?: string
+ /** The day as `YYYY-MM-DD`, or null for none. Leave it out to let the field keep its own value. */
+ value?: string | null
+ defaultValue?: string | null
+ onChange?: (value: string | null) => void
+ /** The reader's language, e.g. `fr-FR`: how the day is written and in which order it is typed. */
+ locale: string
+ labels: DateFieldLabels
+ /** First and last days that can be chosen, as `YYYY-MM-DD`. */
+ min?: string
+ max?: string
+ required?: boolean
+ disabled?: boolean
+ placeholder?: string
+ 'aria-describedby'?: string
+ 'aria-invalid'?: boolean
+ className?: string
+}
+
+/** A calendar day read at noon UTC and formatted in UTC never slips to the day before or after. */
+const noon = (day: string) => new Date(`${day}T12:00:00Z`)
+const iso = (date: Date) => date.toISOString().slice(0, 10)
+const addDays = (day: string, days: number) => iso(new Date(noon(day).getTime() + days * 86_400_000))
+
+function addMonths(day: string, months: number): string {
+ const [year, month, date] = day.split('-').map(Number)
+ const target = new Date(Date.UTC(year, month - 1 + months, 1, 12))
+ const last = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0, 12)).getUTCDate()
+ target.setUTCDate(Math.min(date, last))
+ return iso(target)
+}
+
+function todayIso(): string {
+ const now = new Date()
+ return iso(new Date(Date.UTC(now.getFullYear(), now.getMonth(), now.getDate(), 12)))
+}
+
+/** 1 = Monday … 7 = Sunday, from the locale's week when the runtime knows it. */
+function firstDayOfWeek(locale: string): number {
+ try {
+ const intl = new Intl.Locale(locale) as Intl.Locale & {
+ getWeekInfo?: () => { firstDay: number }
+ weekInfo?: { firstDay: number }
+ }
+ const info = intl.getWeekInfo?.() ?? intl.weekInfo
+ if (info != null) return info.firstDay
+ return ['US', 'CA', 'BR', 'JP'].includes(intl.maximize().region ?? '') ? 7 : 1
+ } catch {
+ return 1
+ }
+}
+
+function formats(locale: string) {
+ const utc = { timeZone: 'UTC' } as const
+ return {
+ written: new Intl.DateTimeFormat(locale, {
+ ...utc,
+ weekday: 'short',
+ day: 'numeric',
+ month: 'long',
+ year: 'numeric',
+ }),
+ numeric: new Intl.DateTimeFormat(locale, { ...utc, day: '2-digit', month: '2-digit', year: 'numeric' }),
+ spoken: new Intl.DateTimeFormat(locale, {
+ ...utc,
+ weekday: 'long',
+ day: 'numeric',
+ month: 'long',
+ year: 'numeric',
+ }),
+ month: new Intl.DateTimeFormat(locale, { ...utc, month: 'long', year: 'numeric' }),
+ weekday: new Intl.DateTimeFormat(locale, { ...utc, weekday: 'narrow' }),
+ order: new Intl.DateTimeFormat(locale, { ...utc, day: '2-digit', month: '2-digit', year: 'numeric' })
+ .formatToParts(noon('2026-11-10'))
+ .map((part) => part.type)
+ .filter((type): type is 'day' | 'month' | 'year' => type === 'day' || type === 'month' || type === 'year'),
+ }
+}
+
+/** A typed date in the reader's order (« 3/12/26 », « 03.12.2026 »): the day, or null when it is not one. */
+function parseTyped(text: string, order: ('day' | 'month' | 'year')[]): string | null {
+ const parts = text.trim().split(/\D+/).filter(Boolean)
+ if (parts.length !== 3) return null
+ const value = Object.fromEntries(order.map((type, index) => [type, Number(parts[index])])) as Record<
+ 'day' | 'month' | 'year',
+ number
+ >
+ const year = value.year < 100 ? 2000 + value.year : value.year
+ const date = new Date(Date.UTC(year, value.month - 1, value.day, 12))
+ if (date.getUTCFullYear() !== year || date.getUTCMonth() !== value.month - 1 || date.getUTCDate() !== value.day) {
+ return null
+ }
+ return iso(date)
+}
+
+/**
+ * A date written out with its weekday (« mar. 10 novembre 2026 »), so the day of the week reads at once. The reader
+ * can type it in their own order while the field has focus, or pick it in a month calendar walked by keyboard; on a
+ * touch screen the device's own picker opens instead. The value is a calendar day (`YYYY-MM-DD`), free of any zone.
+ */
+export function DateField({
+ id,
+ name,
+ value,
+ defaultValue = null,
+ onChange,
+ locale,
+ labels,
+ min,
+ max,
+ required,
+ disabled,
+ placeholder,
+ className,
+ ...aria
+}: DateFieldProps) {
+ const format = useMemo(() => formats(locale), [locale])
+ const [inner, setInner] = useState(defaultValue)
+ const current = value !== undefined ? value : inner
+ const [draft, setDraft] = useState(null)
+ const [open, setOpen] = useState(false)
+ const rootRef = useRef(null)
+ const fieldRef = useRef(null)
+
+ const set = (next: string | null) => {
+ if (value === undefined) setInner(next)
+ onChange?.(next)
+ }
+ const inRange = (day: string) => (min == null || day >= min) && (max == null || day <= max)
+
+ function commit() {
+ if (draft == null) return
+ if (draft.trim() === '') set(null)
+ else {
+ const typed = parseTyped(draft, format.order)
+ if (typed != null && inRange(typed)) set(typed)
+ }
+ setDraft(null)
+ }
+
+ useEffect(() => {
+ if (!open) return
+ const close = (event: MouseEvent) => {
+ if (!rootRef.current?.contains(event.target as Node)) setOpen(false)
+ }
+ document.addEventListener('mousedown', close)
+ return () => document.removeEventListener('mousedown', close)
+ }, [open])
+
+ const shown = draft ?? (current != null ? format.written.format(noon(current)) : '')
+
+ return (
+
+ )
+}
+
+function MonthButton({ label, onClick, back }: { label: string; onClick: () => void; back?: boolean }) {
+ return (
+
+ )
+}
+
+function CalendarIcon() {
+ return (
+
+ )
+}
diff --git a/ui/src/index.ts b/ui/src/index.ts
index ea23724..6d3166d 100644
--- a/ui/src/index.ts
+++ b/ui/src/index.ts
@@ -7,6 +7,7 @@ export {
type SegmentedBarPart,
type SegmentedBarProps,
} from './bars.tsx'
+export { Callout, type CalloutProps, type CalloutTone } from './callout.tsx'
export {
ChartCard,
type ChartCardProps,
@@ -27,6 +28,7 @@ export {
type LineSeries,
} from './charts.tsx'
export { DateChip, type DateChipProps } from './date-chip.tsx'
+export { DateField, type DateFieldLabels, type DateFieldProps } from './date-field.tsx'
export { type Fact, FactList, type FactListProps } from './fact-list.tsx'
export { FormSection, type FormSectionProps } from './form-section.tsx'
export {
@@ -60,11 +62,12 @@ export {
type PeriodStepperProps,
} from './period-stepper.tsx'
export { ProgressBar, type ProgressBarProps, type ProgressTone } from './progress-bar.tsx'
+export { ProgressRing, type ProgressRingProps } from './progress-ring.tsx'
export { SaveBar, type SaveBarProps } from './save-bar.tsx'
export { SectionHeading, type SectionHeadingProps } from './section-heading.tsx'
export { SegmentedControl, type SegmentedControlProps, type SegmentedOption } from './segmented-control.tsx'
export { SelectionBar, type SelectionBarProps } from './selection-bar.tsx'
-export { SidePanel, type SidePanelProps } from './side-panel.tsx'
+export { SidePanel, type SidePanelProps, type SidePanelWalk } from './side-panel.tsx'
export {
MetricStrip,
type MetricStripProps,
diff --git a/ui/src/map.tsx b/ui/src/map.tsx
index 259fe01..fdb6b2d 100644
--- a/ui/src/map.tsx
+++ b/ui/src/map.tsx
@@ -61,7 +61,8 @@ export type MapDotState = 'in' | 'free' | 'other' | 'add' | 'remove'
const DOT_LOOK: Record = {
in: 'size-4.5 bg-primary text-primary-foreground ring-2 ring-surface shadow-sm',
// Free reads as « nothing yet »: the neutral dashed circle of the lists, never green.
- free: 'size-4.5 border-[1.5px] border-dashed border-faint bg-surface shadow-sm',
+ // On the dark ground the surface would vanish: a slightly lighter fill and a stronger ring keep the dot in view.
+ free: 'size-4.5 border-[1.5px] border-dashed border-faint bg-surface shadow-sm dark:border-muted-foreground dark:bg-hover',
other: 'size-2.5 bg-faint/70 ring-2 ring-surface',
add: 'size-4.5 bg-primary text-primary-foreground ring-2 ring-surface outline-[1.5px] outline-primary outline-offset-[3px] shadow-sm',
remove: 'size-4.5 border-2 border-danger bg-surface text-danger shadow-sm',
@@ -132,7 +133,11 @@ export function MapCluster({ count, label, onSelect, className }: MapClusterProp
type="button"
aria-label={label}
onClick={onSelect}
- className={cn(look, 'cursor-pointer focus-visible:outline-2 focus-visible:outline-ring')}
+ className={cn(
+ look,
+ // A touch target of 44 px at least, whatever the disc's size: the first thing tapped on a zoomed-out map.
+ 'relative cursor-pointer focus-visible:outline-2 focus-visible:outline-ring pointer-coarse:before:absolute pointer-coarse:before:-inset-2.5',
+ )}
>
{count}
diff --git a/ui/src/progress-ring.tsx b/ui/src/progress-ring.tsx
new file mode 100644
index 0000000..4da2bf6
--- /dev/null
+++ b/ui/src/progress-ring.tsx
@@ -0,0 +1,64 @@
+import { cn } from './utils.ts'
+
+export interface ProgressRingProps {
+ value: number
+ max: number
+ /**
+ * Names the ring and announces it as a progress bar. Leave it out when the figure beside it (« 5/7 ») already says
+ * the numbers: the ring is then decorative.
+ */
+ 'aria-label'?: string
+ /** `sm` (14 px) beside a figure in a list row, `md` (18 px) beside a larger one. */
+ size?: 'sm' | 'md'
+ className?: string
+}
+
+const SIZE = { sm: 14, md: 18 } as const
+const STROKE = 2
+
+/**
+ * A share of a whole as a small ring, for a column of shares in a list (« 5/7 », « 20 sur 24 »): it fits a one-line
+ * row where a bar would not. A thin arc over a solid track, so it never reads as a status shape (those are filled,
+ * dashed or halved); complete, the arc turns the success colour. Past the whole, it stays full.
+ */
+export function ProgressRing({ value, max, size = 'sm', className, ...rest }: ProgressRingProps) {
+ const px = SIZE[size]
+ const centre = px / 2
+ const radius = (px - STROKE) / 2
+ const circumference = 2 * Math.PI * radius
+ const share = max > 0 ? Math.min(Math.max(value / max, 0), 1) : 0
+ const complete = share >= 1
+ const drawn = share * circumference
+ const label = rest['aria-label']
+ const semantics =
+ label != null
+ ? { role: 'progressbar', 'aria-label': label, 'aria-valuenow': value, 'aria-valuemin': 0, 'aria-valuemax': max }
+ : {}
+
+ return (
+
+
+
+ )
+}
diff --git a/ui/src/side-panel.tsx b/ui/src/side-panel.tsx
index eb88c5c..4f04500 100644
--- a/ui/src/side-panel.tsx
+++ b/ui/src/side-panel.tsx
@@ -12,10 +12,23 @@ export interface SidePanelProps {
footer?: ReactNode
/** Where focus goes back on close, e.g. the row's edit button. Defaults to what had focus when the panel opened. */
returnFocus?: HTMLElement | null
+ /**
+ * Walks the list the panel was opened from: where this item sits (« 3 sur 12 ») and buttons to the previous and
+ * next ones, in the header beside the close button. Leave a handler out where there is nowhere to go.
+ */
+ walk?: SidePanelWalk
children: ReactNode
className?: string
}
+export interface SidePanelWalk {
+ position: ReactNode
+ previousLabel: string
+ nextLabel: string
+ onPrevious?: () => void
+ onNext?: () => void
+}
+
/**
* Edits the selected item beside the page's main column, so the list stays in view. Not a dialog: nothing is
* dimmed and the page stays usable. Put it in a flex row after the main column; it takes 340–400 px and sticks to
@@ -35,6 +48,7 @@ export function SidePanel({
closeLabel,
footer,
returnFocus,
+ walk,
children,
className,
}: SidePanelProps) {
@@ -118,6 +132,17 @@ export function SidePanel({
)}
+ {walk != null && (
+
+ {walk.position}
+
+
+
+
+
+
+
+ )}
}>
+ Ce numéro est déjà pris.
+ ,
+ )
+ const callout = screen.getByText('Impossible d’enregistrer').closest('[data-callout]')
+ expect(callout?.getAttribute('data-tone')).toBe('danger')
+ expect(callout?.querySelector('svg[aria-hidden="true"]')).not.toBeNull()
+ expect(screen.getByText('Ce numéro est déjà pris.')).toBeTruthy()
+ expect(screen.getByRole('button', { name: 'Réessayer' })).toBeTruthy()
+ })
+
+ it('announces itself only when asked to', () => {
+ const { rerender } = render(Hors ligne)
+ expect(screen.queryByRole('alert')).toBeNull()
+ rerender(
+
+ Échec
+ ,
+ )
+ expect(screen.getByRole('alert').textContent).toContain('Échec')
+ })
+})
+
+const DATE_LABELS = { openCalendar: 'Choisir une date', previousMonth: 'Mois précédent', nextMonth: 'Mois suivant' }
+
+function ControlledDateField({ initial = '2026-11-10', min }: { initial?: string | null; min?: string }) {
+ const [value, setValue] = useState(initial)
+ return (
+ <>
+
+
+
+ >
+ )
+}
+
+describe('DateField', () => {
+ it('writes the date out with its weekday, and submits it as YYYY-MM-DD', () => {
+ const { container } = render()
+ const field = screen.getByLabelText('Du') as HTMLInputElement
+ expect(field.value).toBe('mar. 10 novembre 2026')
+ expect((container.querySelector('input[type="hidden"][name="from"]') as HTMLInputElement).value).toBe('2026-11-10')
+ })
+
+ it('takes a typed date in the reader’s order, and shows it numerically while typing', () => {
+ render()
+ const field = screen.getByLabelText('Du') as HTMLInputElement
+ fireEvent.focus(field)
+ expect(field.value).toBe('10/11/2026')
+ fireEvent.change(field, { target: { value: '3/12/26' } })
+ fireEvent.blur(field)
+ expect(screen.getByTestId('value').textContent).toBe('2026-12-03')
+ expect(field.value).toBe('jeu. 3 décembre 2026')
+ })
+
+ it('keeps the date when what was typed is not one', () => {
+ render()
+ const field = screen.getByLabelText('Du') as HTMLInputElement
+ fireEvent.focus(field)
+ fireEvent.change(field, { target: { value: '31/02/2026' } })
+ fireEvent.blur(field)
+ expect(screen.getByTestId('value').textContent).toBe('2026-11-10')
+ })
+
+ it('opens a month calendar on the date, and a day picked there becomes the value', () => {
+ render()
+ fireEvent.click(screen.getByRole('button', { name: 'Choisir une date' }))
+ const grid = screen.getByRole('grid', { name: 'novembre 2026' })
+ expect(within(grid).getByRole('button', { name: /10 novembre 2026/, pressed: true })).toBeTruthy()
+ fireEvent.click(within(grid).getByRole('button', { name: /^vendredi 13 novembre 2026/ }))
+ expect(screen.getByTestId('value').textContent).toBe('2026-11-13')
+ expect(screen.queryByRole('grid')).toBeNull()
+ })
+
+ it('walks the calendar by keyboard and closes on Escape', () => {
+ render()
+ fireEvent.click(screen.getByRole('button', { name: 'Choisir une date' }))
+ const grid = screen.getByRole('grid')
+ fireEvent.keyDown(grid, { key: 'ArrowRight' })
+ fireEvent.keyDown(grid, { key: 'ArrowDown' })
+ expect((document.activeElement as HTMLElement).getAttribute('aria-label')).toMatch(/18 novembre 2026/)
+ fireEvent.keyDown(grid, { key: 'PageDown' })
+ expect(screen.getByRole('grid', { name: 'décembre 2026' })).toBeTruthy()
+ fireEvent.keyDown(grid, { key: 'Escape' })
+ expect(screen.queryByRole('grid')).toBeNull()
+ expect(screen.getByTestId('value').textContent).toBe('2026-11-10')
+ })
+
+ it('leaves days before `min` out of reach', () => {
+ render()
+ fireEvent.click(screen.getByRole('button', { name: 'Choisir une date' }))
+ expect((screen.getByRole('button', { name: /^mercredi 4 novembre 2026/ }) as HTMLButtonElement).disabled).toBe(true)
+ })
+
+ it('moves between months with its arrows', () => {
+ render()
+ fireEvent.click(screen.getByRole('button', { name: 'Choisir une date' }))
+ fireEvent.click(screen.getByRole('button', { name: 'Mois suivant' }))
+ expect(screen.getByRole('grid', { name: 'décembre 2026' })).toBeTruthy()
+ fireEvent.click(screen.getByRole('button', { name: 'Mois précédent' }))
+ fireEvent.click(screen.getByRole('button', { name: 'Mois précédent' }))
+ expect(screen.getByRole('grid', { name: 'octobre 2026' })).toBeTruthy()
+ })
+})
+
+describe('SidePanel walk', () => {
+ it('shows where the item sits and steps to the previous and next ones', () => {
+ const calls: string[] = []
+ render(
+ {}}
+ closeLabel="Fermer"
+ walk={{
+ position: '3 sur 12',
+ previousLabel: 'Précédent',
+ nextLabel: 'Suivant',
+ onPrevious: () => calls.push('previous'),
+ onNext: () => calls.push('next'),
+ }}
+ >
+