@uncinq/css-components 1.16.2 → 1.16.3

package/docs/content.md

@@ -1,145 +0,0 @@
----
-isIndex: false
-title: Content
-description: Alerts, badges, banners, cards, the items grid, labelled lists, media objects and surtitles.
-weight: 4
-icon: card-text
----
-
-## `.alert`
-
-An inline notification block.
-
-```html
-<div class="alert alert-info">
-  <p class="alert-heading">Heads up</p>
-  <p>Your changes were saved.</p>
-</div>
-```
-
-Variants: `.alert-primary`, `.alert-secondary`, `.alert-brand`, `.alert-neutral`, `.alert-dark`, `.alert-light`, `.alert-success`, `.alert-danger`, `.alert-warning`, `.alert-info`.
-
-Each sets the background, border and text colour from the matching `-muted` and `-strong` semantic tokens, so the pairing stays legible if the underlying colour changes.
-
-Two behaviours are worth knowing. `--color-link` is reassigned to the alert's own text colour, so links inside an alert do not fall back to the page link colour against a tinted background. And an alert whose first child is an `.icon`, with no `.alert-heading`, switches to a horizontal layout automatically.
-
-`.container` inside an alert inherits the same flex layout, which is what lets a full-bleed alert keep its content aligned with the rest of the page.
-
-## `.banner`
-
-A thin variation on the alert, centred rather than start-aligned. It sets `--alert-align: center` and flattens paragraph margins, and nothing else.
-
-```html
-<div class="alert banner">
-  <p>Site-wide announcement.</p>
-</div>
-```
-
-It is a modifier on `.alert`, so use both classes.
-
-## `.badge`
-
-A small inline label.
-
-```html
-<span class="badge badge-success">Published</span>
-<a class="badge" href="/tag/css">css</a>
-```
-
-Variants mirror the alert set: `.badge-primary`, `.badge-secondary`, `.badge-brand`, `.badge-neutral`, `.badge-dark`, `.badge-light`, `.badge-success`, `.badge-danger`, `.badge-warning`, `.badge-info`.
-
-Hover styles apply only to `a.badge`, guarded by `@media (hover: hover) and (pointer: fine)`, so a static badge never looks interactive.
-
-## `.card`
-
-A self-contained content card.
-
-```html
-<article class="card">
-  <div class="content">
-    <p class="surtitle">Category</p>
-    <p class="title">Card title</p>
-    <p class="description">Short description.</p>
-  </div>
-  <div class="media">
-    <picture>...</picture>
-  </div>
-</article>
-```
-
-The media block sits first visually, through `--card-media-order: -1`, regardless of its position in the markup. Put it after the content so that screen readers and search engines reach the text first.
-
-Wrapping the content in `a.content` makes the whole card clickable, using a `::before` overlay that covers the card. Focus is then handled on the card itself with `:has(a.content:focus-visible)`, so the focus ring outlines the card rather than an invisible box. Nested interactive elements inside such a card will be unreachable, which is the known trade-off of this pattern.
-
-Sizing with `--card-max-width` and `--card-width` is unset by default. Prefer `ch` units, so the width tracks the text measure.
-
-{{< alert-block state="info" >}}
-The source comment in `card.css` describes `.card` as a backwards-compatible alias for `.item` and recommends using `.item` directly. That is misleading for anyone consuming this package on its own: **`.item` is not defined here**. It lives in the Hugolify design system theme. Within `@uncinq/css-components`, `.card` is a complete implementation and the class to use.
-{{< /alert-block >}}
-
-## `.items`
-
-A responsive grid, and the usual container for cards.
-
-```html
-<div class="items">
-  <article class="card">...</article>
-  <article class="card">...</article>
-</div>
-```
-
-The column count is intrinsic rather than breakpoint-driven:
-
-```css
-grid-template-columns: repeat(
-  var(--items-cols, auto-fill),
-  minmax(min(var(--items-min-width, var(--max-width-item)), 100%), 1fr)
-);
-```
-
-Items wrap when they no longer fit at `--items-min-width`, with no media query involved. Set `--items-cols` to a number to force a fixed count instead.
-
-It also declares `container-type: inline-size` and `container-name: items`, so children can use container queries against the grid rather than the viewport.
-
-Pair it with [`.scrollsnap`](../utilities/) to turn the grid into a horizontal carousel below a given breakpoint.
-
-## `.list`
-
-A compact labelled list with dash markers.
-
-```html
-<div class="list">
-  <p>Optional label</p>
-  <ul>
-    <li>First</li>
-    <li>Second</li>
-  </ul>
-</div>
-```
-
-The wrapper is a `div`, with the label as a sibling of the list rather than inside it. Either `ul` or `ol` works.
-
-## `.media`
-
-The structural base for media blocks, controlling aspect ratio, background and border.
-
-| Class | Use |
-| --- | --- |
-| `.media` | Base, for a picture or video |
-| `.media-logo` | Logo, typically contained rather than cropped |
-| `.media-icon` | Icon, sized from `--icon-size` |
-
-`.media-logo` and `.media-icon` build on `.media`. Inside a `.card`, the card reassigns `--media-color-background` and `--media-ratio` from its own `--card-media-*` tokens, so a media block adapts to its context without a variant class.
-
-A `.video` inside a `.media` is stretched to fill it. See [Embeds](../embeds/).
-
-## `.surtitle`
-
-An eyebrow label above a heading.
-
-```html
-<p class="surtitle">Category</p>
-<h2>Main title</h2>
-```
-
-Inside a `.card` it gets a negative `--surtitle-margin-block-end`, pulling it closer to the title so the pair reads as one unit.

package/docs/embeds.md

@@ -1,66 +0,0 @@
----
-isIndex: false
-title: Embeds
-description: Aspect-ratio wrappers for third-party embeds, native video and maps.
-weight: 6
-icon: play-btn
----
-
-## `.embed`
-
-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. The ratio comes from `--embed-ratio`, which 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>
-```
-
-Always give the `iframe` a `title`. It is the only accessible name an embedded frame has.
-
-## `.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>
-```
-
-The wrapper positions the optional toggle control over the video. Inside a `.media`, the wrapper is stretched to fill it, so a video and an image are interchangeable within a card.
-
-The control is there for a reason rather than for decoration. A video that autoplays without native controls must be pausable to meet WCAG, which is exactly what `.btn-toggle-video` provides. If your video carries `controls`, you do not need it. See [Buttons](../buttons/#btn-toggle-video) for the `.is-playing` contract.
-
-## `.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: sizing, background and border. Leaflet itself, its stylesheet and the script reading those attributes are yours to supply.
-
-Leaflet's own CSS is a good example of why the layer order matters. Import it into `@layer libs` and any adjustments you write into `@layer vendors`, so that a lazily loaded Leaflet cannot outrank your own rules on source order. See [Cascade layers](../cascade-layers/).

package/docs/forms.md

@@ -1,80 +0,0 @@
----
-isIndex: false
-title: Forms
-description: The .form grid, its layout helpers, and where the actual control styling lives.
-weight: 7
-icon: ui-checks
----
-
-Form **controls** are styled by [@uncinq/css-base](../../css-base/base/#forms), 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.
-
-## `.form`
-
-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">Markdown is supported.</p>
-  </div>
-  <div class="actions">
-    <button class="btn" type="submit">Send</button>
-  </div>
-</form>
-```
-
-The column rule is worth reading once:
-
-```css
-grid-template-columns: repeat(
-  auto-fill,
-  minmax(max(var(--form-col-min-width, 25ch), calc(50% - var(--gap) / 2)), 1fr)
-);
-```
-
-The `max()` sets a floor of `25ch` **and** caps the result at half the width. The effect is a form that is one column or two, never three, 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.
-
-Change the floor with `--form-col-min-width`.
-
-## 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 |
-| `.form-check` | 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>
-```
-
-`.form-check` is deliberately minimal, just `display: flex`. The checkbox and radio appearance, including the gap with the adjacent label, comes from css-base, which styles `[type='checkbox'] + label` directly.
-
-## 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.md

@@ -1,93 +0,0 @@
----
-isIndex: false
-title: Navigation
-description: Navigation lists, skip links, breadcrumbs and pagination.
-weight: 5
-icon: signpost
----
-
-## `.nav`
-
-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 class**: a header lays its nav out horizontally by setting `flex-direction: row` on it. That keeps the component free of layout variants that would only ever be used in one place.
-
-## `.nav-title`
-
-A title within a navigation block, for labelling a group of links.
-
-## `.nav-accessibility`
-
-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 is hidden off-screen, not hidden.** It slides into view when a child receives focus. Using `display: none` would remove it from the tab order entirely.
-
-**It requires the `.nav` base class** alongside it.
-
-The targets must exist and be focusable. An `id` on a non-interactive element needs `tabindex="-1"` for the jump to move focus rather than just scroll.
-
-## `.breadcrumb-wrapper`
-
-The breadcrumb trail. Note that the class goes on the **wrapper**, not on the list itself.
-
-```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>
-```
-
-The separator is drawn from `--breadcrumb-separator`, which defaults to `"/"`. Mark the current page with `aria-current="page"` rather than relying on it being last.
-
-## `.pagination`
-
-A page navigation list.
-
-```html
-<nav role="navigation" aria-label="Pagination">
-  <ul class="pagination">
-    <li class="disabled"><a class="first">First</a></li>
-    <li><a class="previous">Previous</a></li>
-    <li class="item active"><a href="?page=1">1</a></li>
-    <li class="item item-adjacent"><a href="?page=2">2</a></li>
-    <li><a class="next">Next</a></li>
-    <li><a class="last">Last</a></li>
-  </ul>
-</nav>
-```
-
-| Class | Role |
-| --- | --- |
-| `.first`, `.previous`, `.next`, `.last` | Navigation controls, on the `a` |
-| `.item` | A page number, on the `li` |
-| `.item-adjacent` | A page number next to the current one |
-| `.active` | The current page |
-| `.disabled` | An unavailable control, on the `li` |
-
-`.item-adjacent` exists so that a responsive paginator can hide distant page numbers while keeping the immediate neighbours visible, which is the usual mobile treatment.
-
-**The glyphs for `.first`, `.last`, `.previous` and `.next` are not provided.** This package positions and spaces them; the theme supplies the arrow through `a::before` or `a::after` content. A paginator with no theme styling will show the text labels only, which is a reasonable fallback but rarely what you want visually.
-
-Note that `.item` here means a pagination entry, and is unrelated to the `.item` card unit mentioned in [Content](../content/).

package/docs/overlays.md

@@ -1,133 +0,0 @@
----
-isIndex: false
-title: Overlays
-description: The shared panel skeleton behind .modal and .drawer, the two opening strategies, and the .dropdown contract.
-weight: 3
-icon: window-stack
----
-
-## The shared panel skeleton
-
-`.modal` and `.drawer` are the same panel. Same structure (header, content, footer), same open and closed contract, same backdrop. They differ only in where they sit: modal centres them, drawer sticks them to an edge.
-
-`components/panel.css` owns every rule. The two variants are **pure configuration**: `modal.css` and `drawer.css` declare nothing but `--panel-*` tokens.
-
-There is **no `.panel` class to apply.** The file targets `:where(.modal, .drawer)` directly, so the skeleton arrives with either variant class. `panel` names the shared concept and the token namespace, not a class.
-
-```html
-<dialog class="modal" id="contact" aria-labelledby="contactLabel">
-  <div class="header">
-    <p class="title" id="contactLabel">Contact</p>
-    <button class="btn-close js-dialog-close" aria-label="Close"></button>
-  </div>
-  <div class="content">...</div>
-  <div class="footer">...</div>
-</dialog>
-```
-
-Each variant aliases `--panel-*` from its own namespace, so `--modal-*` and `--drawer-*` remain the public API. Override those, not `--panel-*`.
-
-## Two ways to open a panel
-
-**The tag picks the strategy, not the class.** Either variant works both ways.
-
-### `<dialog>` with `showModal()`
-
-The browser handles Escape, the focus trap and making the rest of the page inert. You get `[open]`, the native `::backdrop` and the top layer for free.
-
-This is the right choice when the panel is **always** a dialog.
-
-### `popover="auto"` with `showPopover()`
-
-Same top layer, same native `::backdrop`, but the element carries no implicit role.
-
-Use this when the panel becomes a static region of the page above a breakpoint, which is what the `.panel-inline-*` variants do. The reason is an accessibility one: a `<dialog>` is exposed as `role="dialog"` even when it is only styled as a sidebar, whereas a script can set that role solely while the panel is actually open.
-
-## `.modal`
-
-A centred panel. Size a single instance by overriding `--modal-max-width` on the element itself.
-
-```html
-<dialog class="modal" style="--modal-max-width: 40rem">...</dialog>
-```
-
-## `.drawer`
-
-A panel sliding in from an edge.
-
-| Class | Edge |
-| --- | --- |
-| `.drawer-start` | Inline start, left in a left-to-right document |
-| `.drawer-end` | Inline end |
-| `.drawer-top` | Top |
-| `.drawer-bottom` | Bottom |
-
-## `.panel-inline-*`
-
-Turns a panel into an ordinary region of the page from a breakpoint upwards, while it stays an overlay below.
-
-| Class | Becomes inline at |
-| --- | --- |
-| `.panel-inline-sm` | `--sm`, 768px |
-| `.panel-inline-md` | `--md`, 1024px |
-| `.panel-inline-lg` | `--lg`, 1440px |
-| `.panel-inline-xl` | `--xl`, 1600px |
-
-This is the case that calls for `popover="auto"` rather than `<dialog>`. A filters sidebar that is a drawer on mobile and a column on desktop should not announce itself as a dialog while it is a column.
-
-These variants beat `.modal` and `.drawer` on **source order**, not specificity, which is why `panel.css` is imported last. See [Cascade layers](../cascade-layers/).
-
-## `.panel-trigger-*`
-
-The companion to `.panel-inline-*`, applied to the **trigger button** rather than to the panel. It hides the trigger at the breakpoint where the panel stops being an overlay.
-
-| Class | Trigger hidden from |
-| --- | --- |
-| `.panel-trigger-sm` | `--sm`, 768px |
-| `.panel-trigger-md` | `--md`, 1024px |
-| `.panel-trigger-lg` | `--lg`, 1440px |
-| `.panel-trigger-xl` | `--xl`, 1600px |
-
-Pair the suffixes: a panel carrying `.panel-inline-md` needs its button carrying `.panel-trigger-md`, otherwise a button that opens nothing remains on screen at desktop width.
-
-The reason this is a second class rather than something CSS derives on its own is worth knowing, because it looks like a redundancy. Nothing structurally connects a trigger to its panel: the only link is `data-target` matching an `id`, and no selector can compare two attribute values. A positional rule would work only until somebody moved the markup, and a filter button typically lives in the page heading rather than beside the panel it opens. In practice both classes come from the same configuration value, so the pair cannot disagree.
-
-## The JavaScript contract
-
-This package ships no JavaScript. `.modal` and `.drawer` expect a script that provides:
-
-| Hook | Role |
-| --- | --- |
-| `.js-dialog-toggle[data-target="#id"]` | Opens the panel it points at |
-| `.js-dialog-close` | Any element inside the panel that closes it |
-
-Closing must also work on Escape and on a click outside. With `<dialog>` and `showModal()` the browser already does both. With `popover="auto"` the platform handles light dismiss and Escape too, so in practice the script mainly manages the role and the open call.
-
-## `.dropdown`
-
-A contextual menu, with a tighter JavaScript contract because it animates.
-
-```html
-<div class="dropdown">
-  <button class="js-dropdown-toggle" aria-expanded="false">Label</button>
-  <ul class="dropdown-menu" role="menu">
-    <li><a class="dropdown-item" href="#">Item</a></li>
-    <li><hr class="dropdown-divider"></li>
-    <li><a class="dropdown-item" href="#">Item</a></li>
-  </ul>
-</div>
-```
-
-The trigger is `.js-dropdown-toggle`, and its **next element sibling must be** `.dropdown-menu`.
-
-The script toggles three classes on the menu, in this sequence:
-
-| Class | Meaning |
-| --- | --- |
-| `.showing` | Opening transition has started |
-| `.show` | Fully open |
-| `.hiding` | Closing transition has started |
-
-It must also keep `aria-expanded` on the toggle in sync. The three-class sequence exists so the menu can animate out before being removed from the flow; a single `.show` class would make the closing transition impossible.
-
-`.dropdown-menu-end` aligns the menu to the inline end of its trigger rather than the start.