@uncinq/css-components 1.16.2 → 1.16.4

package/docs/embeds/embed.md

@@ -0,0 +1,53 @@
+---
+isIndex: false
+title: Embed
+description: A responsive container for third-party embeds, holding an aspect ratio so the page does not reflow.
+weight: 2
+icon: aspect-ratio
+---
+
+A responsive container for third-party embeds, holding an aspect ratio so the page does not reflow once the iframe loads.
+
+```html
+<div class="embed">
+  <iframe src="https://..." title="Video title" allowfullscreen></iframe>
+</div>
+```
+
+Accepts `iframe`, `video`, `embed` or `object` as its child, each stretched to fill the box.
+
+## The ratio
+
+`--embed-ratio` defaults to the video ratio token. Override it per instance for a square or portrait embed:
+
+```html
+<div class="embed" style="--embed-ratio: 1">...</div>
+```
+
+or per context, which is usually better:
+
+```css
+.podcast-player { --embed-ratio: 4 / 1; }
+```
+
+## Frame and shadow
+
+`--embed-border`, `--embed-border-radius` and `--embed-box-shadow` are the three decoration tokens. `overflow: hidden` is what lets the radius clip the iframe at the corners, since an iframe cannot be given one of its own.
+
+Note that `--embed-border` is a **shorthand** token taking width, style and colour together, unlike most components in this package which split the three. Set it as one value:
+
+```css
+.embed { --embed-border: 1px solid var(--color-border); }
+```
+
+## Always give the iframe a title
+
+```html
+<iframe src="..." title="2024 annual report, presented by the CFO"></iframe>
+```
+
+It is the only accessible name an embedded frame has. Without it a screen reader announces "frame" and the reader has to enter it to find out what it holds.
+
+## Embed or video?
+
+Use `.embed` for a **third-party player**, where the content is an iframe you do not control. Use [`.video`](../video/) for a native `<video>` element, which needs a positioning context for its pause control rather than a ratio wrapper.

package/docs/embeds/map.md

@@ -0,0 +1,57 @@
+---
+isIndex: false
+title: Map
+description: A Leaflet map container, and where Leaflet's own stylesheet belongs in the layer order.
+weight: 4
+icon: map
+---
+
+A map container, driven by Leaflet through a `js-map` hook.
+
+```html
+<div class="map js-map"
+     data-markers="[...]"
+     data-zoom="12"
+     data-tile="3"
+     data-marker-hidden="false"></div>
+```
+
+| Attribute | Role |
+| --- | --- |
+| `data-markers` | The markers to plot |
+| `data-zoom` | Initial zoom level |
+| `data-tile` | Tile layer selection |
+| `data-marker-hidden` | Whether markers start hidden |
+
+This package provides the container only: ratio, background, radius and margins. **Leaflet itself, its stylesheet and the script reading those attributes are yours to supply.**
+
+## It breaks out on mobile
+
+```css
+@media not (--sm) {
+  --map-ratio: var(--map-ratio-mobile);
+
+  .container & { margin-inline: calc(-1 * var(--gutter)); }
+  .row { display: block; }
+}
+```
+
+Three changes below 768px. The ratio switches to `--map-ratio-mobile`, usually taller, because a wide map on a narrow screen shows almost nothing useful. Inside a `.container` the map pulls out to the screen edges by one gutter. And a `.row` inside it stops laying out in columns.
+
+The bleed is deliberately scoped to `.container &`, so a map in a card or a sidebar stays inside its parent instead of overflowing something with no room to give.
+
+## Where Leaflet's CSS goes
+
+This is the clearest case in the package for why the layer order matters. Leaflet ships its own stylesheet, and a map is often loaded lazily.
+
+```css
+@layer reset, tokens, libs, base, vendors, layouts, components, pages, utilities;
+```
+
+Import Leaflet's stylesheet into `@layer libs`, and any adjustments you write into `@layer vendors`. A layer's position is fixed the first time its name appears, so a stylesheet injected at runtime lands in the slot its layer already occupies rather than at the end of the cascade. Without that, a lazily loaded Leaflet outranks your own rules purely on source order, and the map's marker styling starts winning arguments it should lose.
+
+See [Cascade layers](../../cascade-layers/).
+
+## Accessibility
+
+A map with no text alternative is unusable without sight. Whatever the map shows, addresses, opening hours, a route, should also exist as text near it. The container has no role and announces nothing on its own.

package/docs/embeds/overview.md

@@ -0,0 +1,25 @@
+---
+isIndex: false
+title: Overview
+description: Three containers that reserve their aspect ratio before the content arrives, and stop at the container.
+weight: 1
+icon: book
+---
+
+Three containers, all built on the same idea: hold the space before the content arrives.
+
+| Page | Class | For |
+| --- | --- | --- |
+| [Embed](../embed/) | `.embed` | Third-party iframes, players, social cards |
+| [Video](../video/) | `.video` | A native `<video>`, with an optional pause control |
+| [Map](../map/) | `.map` | A Leaflet map container |
+
+## They all reserve an aspect ratio
+
+An iframe, a video or a map that sizes itself once its content loads pushes the rest of the page down at an unpredictable moment. Each of these components declares `aspect-ratio` from a token, so the box exists at its final size from the first paint.
+
+That is also why all three set `overflow: hidden`: the content is stretched to fill a box whose proportions it did not choose.
+
+## They stop at the container
+
+None of the three ships the thing it wraps. `.embed` gives you no player, `.video` gives you no controls beyond the [toggle button](../../buttons/btn-toggle-video/), and `.map` gives you neither Leaflet nor its stylesheet. Loading those, and keeping them out of your own layers, is the consuming project's job. See [Cascade layers](../../cascade-layers/) for where third-party CSS belongs.

package/docs/embeds/video.md

@@ -0,0 +1,53 @@
+---
+isIndex: false
+title: Video
+description: A wrapper for a native video, positioning the optional pause control an autoplaying video needs.
+weight: 3
+icon: camera-video
+---
+
+A wrapper for a **native** `<video>`, as opposed to an embedded player.
+
+```html
+<div class="video">
+  <video autoplay muted loop playsinline></video>
+  <button class="btn btn-toggle-video is-playing" aria-label="Pause">
+    <span class="icon-pause"></span>
+    <span class="icon-play"></span>
+  </button>
+</div>
+```
+
+## What it does
+
+Three things:
+
+```css
+.video {
+  position: relative;
+
+  video { aspect-ratio: var(--video-ratio, var(--ratio-video)); width: 100%; }
+
+  .btn-toggle-video { position: absolute; inset-block-end: 0; inset-inline-end: 0; z-index: 10; }
+}
+```
+
+It establishes the positioning context, sizes the video to its container at a known ratio, and pins the control to the bottom inline-end corner. The ratio falls back to `--ratio-video` from the design tokens, so `--video-ratio` only needs setting for a portrait or square clip.
+
+## The control is not decoration
+
+A video that autoplays without native controls must be pausable to meet WCAG, which is exactly what [`.btn-toggle-video`](../../buttons/btn-toggle-video/) provides. If your video carries `controls`, you do not need it.
+
+The button is the only child the wrapper positions. Anything else you put inside sits in the normal flow.
+
+## Inside a media block
+
+```css
+.media .video { height: 100%; }
+```
+
+A [`.media`](../../content/media/) stretches the wrapper to fill it, so a video and an image are interchangeable within a [card](../../content/card/) without changing the card's structure. The media block's own `--media-ratio` then governs the box, and the video is cropped to it by `object-fit: cover`.
+
+## Autoplay checklist
+
+`muted` is required for autoplay to be allowed at all, and `playsinline` keeps iOS from taking the video fullscreen. `loop` is what makes a background video a background video. All three are attributes on the element, not something this component can supply.

package/docs/forms/_index.md

@@ -0,0 +1,7 @@
+---
+isIndex: false
+title: Forms
+description: The .form grid, the .form-check row, and where the actual control styling lives.
+weight: 8
+icon: ui-checks
+---

package/docs/forms/form-check.md

@@ -0,0 +1,77 @@
+---
+isIndex: false
+title: Check row
+description: A checkbox or radio laid out beside its label, and why the class is only one declaration.
+weight: 3
+icon: check-square
+---
+
+A checkbox or radio laid out inline with its label.
+
+```html
+<div class="form-check">
+  <input id="terms" type="checkbox">
+  <label for="terms">I accept the terms</label>
+</div>
+```
+
+## The whole component
+
+```css
+.form-check { display: flex; }
+```
+
+That is the entire rule, and it is deliberate. The control's appearance, its size, and the gap between it and the adjacent label all come from [css-base](../../../css-base/base/form-checkbox/), which styles `[type='checkbox'] + label` directly on the native elements.
+
+So the only thing missing from a bare input and label is that they sit on separate lines by default. This class fixes that, and stays out of everything else.
+
+The practical consequence: if the spacing between a checkbox and its label is wrong, the fix is in css-base or in the tokens, not here. Adding a `gap` to `.form-check` would apply on top of the one css-base already sets, and the two would drift apart.
+
+## The label must come after the control
+
+`[type='checkbox'] + label` is an adjacent sibling selector. Wrapping the input inside the label, or putting the label first, means the control gets no spacing and no styling from css-base.
+
+```html
+<!-- works -->
+<div class="form-check">
+  <input id="terms" type="checkbox">
+  <label for="terms">I accept the terms</label>
+</div>
+
+<!-- does not -->
+<div class="form-check">
+  <label for="terms">I accept the terms</label>
+  <input id="terms" type="checkbox">
+</div>
+```
+
+## Inside a form grid
+
+A check row is a direct child of [`.form`](../form/) like any other field, so it takes a grid track. Give it `.full` when the label is long enough to wrap in half the width:
+
+```html
+<div class="form-check full">
+  <input id="newsletter" type="checkbox">
+  <label for="newsletter">Send me the monthly newsletter</label>
+</div>
+```
+
+## Groups of radios
+
+There is no class for the group. Use a `<fieldset>` with a `<legend>`, and one `.form-check` per option:
+
+```html
+<fieldset class="full">
+  <legend>Preferred contact</legend>
+  <div class="form-check">
+    <input id="by-email" type="radio" name="contact" value="email">
+    <label for="by-email">Email</label>
+  </div>
+  <div class="form-check">
+    <input id="by-phone" type="radio" name="contact" value="phone">
+    <label for="by-phone">Phone</label>
+  </div>
+</fieldset>
+```
+
+The legend is what names the group in the accessibility tree. A set of radios with individual labels and no legend is announced one option at a time, with nothing saying what is being chosen.

package/docs/forms/form.md

@@ -0,0 +1,67 @@
+---
+isIndex: false
+title: Form
+description: A responsive grid that is one column or two, never three, plus its layout helpers.
+weight: 2
+icon: columns-gap
+---
+
+A responsive two-column grid that collapses to one column when there is not enough room.
+
+```html
+<form class="form">
+  <div>
+    <label for="first">First name</label>
+    <input id="first" type="text">
+  </div>
+  <div>
+    <label for="last">Last name</label>
+    <input id="last" type="text">
+  </div>
+  <div class="full">
+    <label for="message">Message</label>
+    <textarea id="message"></textarea>
+    <p class="help" id="message-help">Markdown is supported.</p>
+  </div>
+  <div class="actions">
+    <button class="btn" type="submit">Send</button>
+  </div>
+</form>
+```
+
+Each field is a plain `div`. There is no `.form-group` or `.field` class: the grid places its direct children, whatever they are.
+
+## One column or two, never three
+
+```css
+grid-template-columns: repeat(
+  auto-fill,
+  minmax(max(var(--form-col-min-width, 25ch), calc(50% - var(--gap) / 2)), 1fr)
+);
+```
+
+The `max()` is doing two jobs at once. It sets a **floor** of `25ch`, below which a field is too narrow to use, and it sets each track to at least half the width minus half the gap, which **caps** the result at two columns however wide the container gets.
+
+A three-column form is almost never what you want, because it breaks the vertical reading order of a sequence of fields: the eye has to move right twice before dropping a line, and nothing in the layout says which order the fields belong in.
+
+Change the floor with `--form-col-min-width`. Raising it past 50% forces a single column, which is a reasonable way to write a narrow form without a variant class.
+
+## Layout helpers
+
+| Class | Effect |
+| --- | --- |
+| `.full` | Spans both columns, `grid-column: 1 / -1` |
+| `.actions` | Spans both columns and stacks its children vertically |
+| `.help` | Help text under a field |
+
+`.actions` is a column flex container aligned to the start, with `--gap` between its children and their block margins flattened. So a submit button, a consent line and a legal note stack in the order written without fighting each other's margins.
+
+`.help` reads `--help-*` for colour, size, weight, margin and alignment. Pair it with `aria-describedby`, or it is seen and never announced.
+
+## Field spacing
+
+Both axes use `--gap`, the same token the grid uses for its column calculation. That is why the two-column cap subtracts `var(--gap) / 2`: the track width and the gutter come from one value, so changing it cannot desynchronise them.
+
+## Controls are not styled here
+
+Inputs, selects, textareas and their focus and invalid states come from [css-base](../../../css-base/base/form/), applied to the native elements. This file adds layout and nothing else, which is why a form built without `.form` still looks right, it is simply stacked.

package/docs/forms/overview.md

@@ -0,0 +1,31 @@
+---
+isIndex: false
+title: Overview
+description: The two form layout components, why the controls themselves are styled elsewhere, and the accessible names none of it supplies.
+weight: 1
+icon: book
+---
+
+Form **controls** are styled by [@uncinq/css-base](../../../css-base/base/form/), on the native elements themselves. There is no `.input` or `.select` class to apply.
+
+This package adds only what css-base cannot: the layout around those controls.
+
+| Page | Class | Covers |
+| --- | --- | --- |
+| [Form](../form/) | `.form` | The two-column grid and its layout helpers |
+| [Check row](../form-check/) | `.form-check` | A checkbox or radio laid out beside its label |
+
+Both live in `components/form.css`.
+
+## Accessibility
+
+Nothing here supplies an accessible name. Every control needs a `<label for>` pointing at its `id`, or a `.visually-hidden` label when the design has no room for a visible one.
+
+Tie `.help` text to its field with `aria-describedby`, otherwise it is visible but never announced:
+
+```html
+<input id="message" aria-describedby="message-help">
+<p class="help" id="message-help">Markdown is supported.</p>
+```
+
+For error states, use `aria-invalid="true"` on the control and point `aria-describedby` at the error message.

package/docs/navigation/_index.md

@@ -0,0 +1,7 @@
+---
+isIndex: false
+title: Navigation
+description: Navigation lists, navigation titles, skip links, breadcrumbs and pagination.
+weight: 6
+icon: signpost
+---

package/docs/navigation/breadcrumb.md

@@ -0,0 +1,59 @@
+---
+isIndex: false
+title: Breadcrumb
+description: The breadcrumb trail, with the class on the wrapper and the separator drawn from a token.
+weight: 5
+icon: chevron-double-right
+---
+
+The breadcrumb trail. **The class goes on the wrapper, not on the list.**
+
+```html
+<nav class="breadcrumb-wrapper" aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li><a href="/docs">Docs</a></li>
+    <li aria-current="page">Navigation</li>
+  </ol>
+</nav>
+```
+
+`.breadcrumb-wrapper` styles the `ol` and the `li` inside it by element, so there is no class to put on either. The name says wrapper for that reason.
+
+## The separator
+
+Drawn on `li::before` from a token, with the first item's suppressed:
+
+```css
+li::before { content: var(--breadcrumb-separator); color: var(--breadcrumb-color-separator); }
+li:first-child::before { display: none; }
+```
+
+`--breadcrumb-separator` defaults to `"/"` and takes any `content` value, so a chevron or an arrow is a token change. It needs the quotes, since it is dropped into `content` as is.
+
+Because the separator is generated content rather than text, it is not selected when a reader copies the trail, and screen readers skip it.
+
+## Marking the current page
+
+Use `aria-current="page"`, which is both the accessible marker and the styling hook:
+
+```css
+li[aria-current="page"] { color: var(--breadcrumb-color-text-active); }
+```
+
+There is no `.active` class here, deliberately. Relying on the attribute means the visual state and the announced state cannot disagree, and it rules out the other common approach, styling `:last-child`, which breaks the moment a trail ends on something other than the current page.
+
+## Overflow on narrow screens
+
+```css
+overflow-x: auto;
+li { flex-shrink: 0; white-space: nowrap; }
+```
+
+A long trail scrolls sideways rather than wrapping into several lines or truncating. Items keep their full width, so the deepest entries stay readable and the reader scrolls to reach the shallow ones.
+
+The wrapper also carries a block border and its own background, which is what lets a breadcrumb sit as a full-width band under the header.
+
+## Accessibility
+
+`aria-label` on the `<nav>` is what distinguishes this landmark from the other navigation regions on the page. Use an `<ol>`, not a `<ul>`: the order of a breadcrumb is its meaning.

package/docs/navigation/nav-accessibility.md

@@ -0,0 +1,67 @@
+---
+isIndex: false
+title: Skip links
+description: Skip navigation for keyboard and assistive technology users, hidden off-screen rather than hidden.
+weight: 4
+icon: universal-access
+---
+
+Skip links, for keyboard and assistive technology users.
+
+```html
+<ul class="nav nav-accessibility">
+  <li><a href="#main">Skip to content</a></li>
+  <li><a href="#navigation">Skip to navigation</a></li>
+  <li><a href="#footer">Skip to footer</a></li>
+</ul>
+```
+
+Three things matter here, and getting any of them wrong defeats the purpose.
+
+## It must be the first focusable element in `<body>`
+
+A skip link that comes after the navigation it skips is useless. It goes before the header, before any cookie banner, before anything else that can take focus.
+
+## It is hidden off-screen, not hidden
+
+```css
+.nav-accessibility {
+  position: absolute;
+  transform: translateY(-100%);
+
+  &:focus-within { transform: translateY(0); }
+}
+```
+
+`display: none` or `visibility: hidden` would remove it from the tab order entirely, which is the one thing a skip link cannot afford. It is pushed out of view with a transform and slides back on `:focus-within`, so the whole group appears as soon as any link inside it is reached.
+
+The slide is behind `prefers-reduced-motion`; with motion disabled the group simply appears.
+
+## It requires the `.nav` base class
+
+`.nav-accessibility` sets `flex-direction: row` and a small font size, but the flex layout, the list reset and the link padding all come from [`.nav`](../nav/). On its own it is an unstyled list positioned off-screen.
+
+## The focus treatment is deliberate
+
+```css
+a {
+  background: var(--color-background);
+  &:focus {
+    background: var(--color-text);
+    color: var(--color-background);
+    outline: none;
+  }
+}
+```
+
+The resting background is what keeps the links readable once the group slides over the page content. On focus the colours invert, which is why the usual focus ring is dropped: the inversion is the focus indicator, and it meets the contrast requirement on its own.
+
+Note this uses `:focus`, not `:focus-visible`, so the indicator appears however focus arrived.
+
+## The targets have to be focusable
+
+`z-index: 300` puts the group above sticky headers, but a working skip link also needs somewhere to land. An `id` on a non-interactive element needs `tabindex="-1"`, otherwise the jump scrolls the page without moving focus, and the next Tab press continues from the top of the document:
+
+```html
+<main id="main" tabindex="-1">
+```

package/docs/navigation/nav-title.md

@@ -0,0 +1,43 @@
+---
+isIndex: false
+title: Nav title
+description: A label above a group of navigation links.
+weight: 3
+icon: type
+---
+
+A title within a navigation block, for labelling a group of links.
+
+```html
+<nav aria-labelledby="docs-nav">
+  <p class="nav-title" id="docs-nav">Documentation</p>
+  <ul class="nav">
+    <li><a href="/docs/install">Installation</a></li>
+    <li><a href="/docs/usage">Usage</a></li>
+  </ul>
+</nav>
+```
+
+It is a leaf component with no children and no variants:
+
+```css
+.nav-title {
+  font-size: var(--nav-title-font-size);
+  font-weight: var(--nav-title-font-weight);
+  margin-block: var(--nav-title-margin-block, 0);
+  padding-block: var(--nav-title-padding-block);
+  padding-inline: var(--nav-title-padding-inline);
+}
+```
+
+## It is a sibling of the list, not an item in it
+
+Putting it inside the `<ul>` as an `<li>` would make it a list item that screen readers count and announce as one, and [`.nav`](../nav/) would style it as a navigation entry. Keep it outside.
+
+## Why it carries inline padding
+
+`--nav-title-padding-inline` exists so the label lines up with the link text below it, which is itself inset by `--nav-link-padding-inline`. Keep the two in step when you change either, or the title sits proud of the list it labels.
+
+## Use it as the accessible name
+
+A group of links deserves a label in the accessibility tree as well as on screen. Point the surrounding `<nav>` at it with `aria-labelledby` rather than repeating the text in an `aria-label`, so the two cannot drift apart.

package/docs/navigation/nav.md

@@ -0,0 +1,65 @@
+---
+isIndex: false
+title: Nav
+description: The base navigation list, vertical by default, whose direction is set by context rather than by a modifier class.
+weight: 2
+icon: compass
+---
+
+The base navigation list, vertical by default.
+
+```html
+<ul class="nav">
+  <li><a href="/">Home</a></li>
+  <li><a href="/about">About</a></li>
+</ul>
+```
+
+Works on `ul` or `ol`.
+
+## Direction is set by context, not by a modifier
+
+There is no `.nav-horizontal`. The direction comes from a token:
+
+```css
+flex-direction: var(--nav-direction, column);
+```
+
+so a header lays its own navigation out horizontally by setting `--nav-direction: row` on it, or `flex-direction` directly. That keeps the component free of layout variants that would only ever be used in one place, and it means the same list is a column in a drawer and a row in a header without a class change.
+
+## Nested lists inherit the layout
+
+```css
+&,
+:is(ul, ol) { display: flex; flex-direction: var(--nav-direction, column); ... }
+```
+
+The rule matches the nav **and** every list inside it, so a submenu needs no second `.nav` class. Note that a nested list inherits `--nav-direction` too, so a horizontal header menu gets horizontal submenus unless the submenu resets it.
+
+## Links
+
+`a:where(:not(.btn))` and `li > span` are styled together, so a non-link entry, the current page rendered as text, lines up with the links around it. `.btn` is excluded through `:where()`, which adds no specificity, so a call to action inside a navigation keeps its own styling.
+
+The current entry is marked with a class on the link:
+
+```html
+<li><a href="/about" class="active" aria-current="page">About</a></li>
+```
+
+```css
+&.active { --nav-color-text: var(--nav-color-text-active); }
+```
+
+The class drives the colour; `aria-current` is what a screen reader announces. Write both.
+
+## Highlighted items
+
+`.nav-item-highlighted` tightens the line height and pulls the item out to the nav's own inline padding, for an entry rendered as a block rather than as a line of text.
+
+## Dropdowns inside a nav
+
+`.dropdown-toggle` is restyled to take `--nav-color-text`, so a [dropdown](../../overlays/dropdown/) in a header menu matches the links beside it. Nothing else about the dropdown changes.
+
+## Inside a panel
+
+A `.modal` or `.drawer` publishes `--nav-color-text` from its own text colour, so a navigation inside a panel follows the panel's palette. Going inline with [`.panel-inline-*`](../../overlays/panel/#inline-variants) hands that token back to the page, which is why a drawer menu that becomes a sidebar column changes colour at the breakpoint.

package/docs/navigation/overview.md

@@ -0,0 +1,29 @@
+---
+isIndex: false
+title: Overview
+description: The five navigation components, the two that take their class on the wrapper, and the landmarks none of them supplies.
+weight: 1
+icon: book
+---
+
+Five components for moving around a site.
+
+| Page | Class | Purpose |
+| --- | --- | --- |
+| [Nav](../nav/) | `.nav` | The base navigation list |
+| [Nav title](../nav-title/) | `.nav-title` | A label above a group of links |
+| [Skip links](../nav-accessibility/) | `.nav-accessibility` | Skip navigation for keyboard and assistive technology |
+| [Breadcrumb](../breadcrumb/) | `.breadcrumb-wrapper` | The breadcrumb trail |
+| [Pagination](../pagination/) | `.pagination` | Page navigation |
+
+## Two of them take the class on the wrapper
+
+`.breadcrumb-wrapper` goes on the `<nav>`, not on the `<ol>` inside it. `.nav-accessibility` goes on the list itself, but only alongside `.nav`. Neither is guessable from the name, so check the page before writing the markup.
+
+## None of them supplies the landmark
+
+`<nav>`, `aria-label` and `aria-current` are yours to write. A page with three navigation regions and no labels on them is harder to use with a screen reader than a page with one, which is the usual reason to add them.
+
+## `.item` means two different things
+
+In [pagination](../pagination/), `.item` is a page number. It is unrelated to the `.item` card unit mentioned throughout the [Content](../../content/) section, which is not defined in this package at all.