@uncinq/css-components 1.27.3 → 1.28.0

package/README.md

@@ -4,7 +4,7 @@
 
 <img width="1280" height="640" alt="share-css-components" src="https://github.com/user-attachments/assets/3d74df8a-e7bf-4ba5-8529-99cfef0bc176" />
 
-30 components and 1 utility, written as plain CSS, reading their values from [@uncinq/component-tokens](https://github.com/uncinq/component-tokens) and adding none of their own.
+31 components and 1 utility, written as plain CSS, reading their values from [@uncinq/component-tokens](https://github.com/uncinq/component-tokens) and adding none of their own.
 
 ## Where this sits
 
@@ -55,7 +55,7 @@ The failure is silent. No error is raised, the page simply stays at its mobile v
 | --- | --- |
 | Buttons | `.btn` with colour, size and style variants, plus `btn-close`, `btn-menu`, `btn-search`, `btn-filter`, `btn-share`, `btn-toc`, `btn-toggle-video` |
 | Overlays | `modal`, `drawer`, `dropdown`, and the shared panel skeleton |
-| Content | `alert`, `badge`, `banner`, `card`, `items`, `list`, `media`, `push`, `surtitle` |
+| Content | `alert`, `badge`, `banner`, `card`, `items`, `list`, `media`, `push`, `rating`, `surtitle` |
 | Navigation | `nav`, `nav-title`, `nav-accessibility`, `breadcrumb`, `pagination` |
 | Embeds | `embed`, `video`, `map` |
 | Forms | `form`, `form-check` and the layout helpers |
@@ -85,7 +85,7 @@ It is also versioned with the code in [`docs/`](docs/), one page per component,
 - [Cascade layers](docs/cascade-layers.md) — the two layers, and the `:where()` convention
 - [Buttons](docs/buttons/) — [`.btn`](docs/buttons/btn.md) and the seven specialised buttons
 - [Overlays](docs/overlays/) — [the panel skeleton](docs/overlays/panel.md), [`.modal`](docs/overlays/modal.md), [`.drawer`](docs/overlays/drawer.md), [`.dropdown`](docs/overlays/dropdown.md)
-- [Content](docs/content/) — [`.alert`](docs/content/alert.md), [`.badge`](docs/content/badge.md), [`.banner`](docs/content/banner.md), [`.card`](docs/content/card.md), [`.items`](docs/content/items.md), [`.list`](docs/content/list.md), [`.media`](docs/content/media.md), [`.surtitle`](docs/content/surtitle.md)
+- [Content](docs/content/) — [`.alert`](docs/content/alert.md), [`.badge`](docs/content/badge.md), [`.banner`](docs/content/banner.md), [`.card`](docs/content/card.md), [`.items`](docs/content/items.md), [`.list`](docs/content/list.md), [`.media`](docs/content/media.md), [`.rating`](docs/content/rating.md), [`.surtitle`](docs/content/surtitle.md)
 - [Navigation](docs/navigation/) — [`.nav`](docs/navigation/nav.md), [`.nav-title`](docs/navigation/nav-title.md), [skip links](docs/navigation/nav-accessibility.md), [breadcrumb](docs/navigation/breadcrumb.md), [pagination](docs/navigation/pagination.md)
 - [Embeds](docs/embeds/) — [`.embed`](docs/embeds/embed.md), [`.video`](docs/embeds/video.md), [`.map`](docs/embeds/map.md)
 - [Forms](docs/forms/) — [`.form`](docs/forms/form.md), [`.form-check`](docs/forms/form-check.md)

package/css/components/form.css

@@ -1,4 +1,17 @@
 /* components/form.css */
+/*
+ * .form — responsive grid of one or two columns, and its layout helpers.
+ *
+ * Structure:
+ *   form.form[.is-submitting|.is-success|.has-error]
+ *     p.required         (meaning of the asterisk, before the first field: RGAA 11.10)
+ *     div[.full]*        (fields)
+ *     .alert[hidden]     (answer of an async submission)
+ *     div.actions        (submit, legal)
+ *
+ * States, set by the script that submits the form asynchronously:
+ * .is-submitting, .is-success (only the .alert remains), .has-error
+ */
 @layer components {
   .form {
     display: grid;
@@ -14,10 +27,18 @@
     }
 
     .actions,
-    .full {
+    .alert,
+    .full,
+    .required {
       grid-column: 1 / -1;
     }
-    
+
+    /* Aligned with the labels, whatever the alignment of the container */
+    .required {
+      margin-block: 0;
+      text-align: start;
+    }
+
     .actions {
       align-items: start;
       display: flex;
@@ -28,6 +49,15 @@
       }
     }
 
+    &.is-submitting {
+      cursor: progress;
+    }
+
+    /* Once sent, only the answer remains (direct children only, so that the
+       content of the .alert stays) */
+    &.is-success > :not(.alert) {
+      display: none;
+    }
   }
 
   .form-check {

package/css/components/rating.css

@@ -0,0 +1,41 @@
+/* components/rating.css */
+/*
+ * .rating — star rating out of 5, fractional values included (4.8).
+ *
+ * Structure:
+ *   div.rating
+ *     span.rating-star       (×5, style="--rating-fill: 0–100%")
+ *       .icon                (the theme's star glyph, painted as a mask)
+ *     span.visually-hidden   (e.g. "Rating: 4.8 out of 5")
+ *
+ * The icon is a mask, so its background is what shows through the glyph.
+ * A hard-stop gradient paints each star in the active colour up to its
+ * --rating-fill and in the empty colour after it.
+ */
+@layer components {
+  .rating {
+    --icon-size: var(--rating-size);
+
+    align-items: center;
+    display: flex;
+    gap: var(--rating-gap);
+    justify-content: var(--rating-justify-content);
+  }
+
+  .rating-star {
+    display: flex;
+
+    .icon {
+      background: linear-gradient(
+        to right,
+        var(--rating-color-active) var(--rating-fill, 0%),
+        var(--rating-color-empty) var(--rating-fill, 0%)
+      );
+
+      /* RTL: stars fill from the right */
+      &:dir(rtl) {
+        scale: -1 1;
+      }
+    }
+  }
+}

package/css/index.css

@@ -27,6 +27,7 @@
 @import 'components/pagination.css';
 @import 'components/panel.css';
 @import 'components/push.css';
+@import 'components/rating.css';
 @import 'components/surtitle.css';
 @import 'components/video.css';
 

package/docs/content/_index.md

@@ -1,7 +1,7 @@
 ---
 isIndex: false
 title: Content
-description: Alerts, badges, banners, cards, the items grid, labelled lists, media objects, pushes and surtitles.
+description: Alerts, badges, banners, cards, the items grid, labelled lists, media objects, pushes, star ratings and surtitles.
 weight: 5
 icon: card-text
 ---

package/docs/content/rating.md

@@ -0,0 +1,68 @@
+---
+isIndex: false
+title: Rating
+description: A star rating out of 5 with fractional values, how each star is filled through its icon mask, and what the markup has to provide.
+weight: 10
+icon: star-half
+---
+
+A star rating out of 5, fractional values included: 4.8 shows four full stars and one filled to 80%.
+
+```html
+<div class="rating">
+  <span class="rating-star" style="--rating-fill: 100%"><i class="icon icon-star" aria-hidden="true"></i></span>
+  <span class="rating-star" style="--rating-fill: 100%"><i class="icon icon-star" aria-hidden="true"></i></span>
+  <span class="rating-star" style="--rating-fill: 100%"><i class="icon icon-star" aria-hidden="true"></i></span>
+  <span class="rating-star" style="--rating-fill: 100%"><i class="icon icon-star" aria-hidden="true"></i></span>
+  <span class="rating-star" style="--rating-fill: 80%"><i class="icon icon-star" aria-hidden="true"></i></span>
+  <span class="visually-hidden">Rating: 4.8 out of 5</span>
+</div>
+```
+
+| Child | Role |
+| --- | --- |
+| `.rating-star` | One star, carrying its own fill in `--rating-fill`, from `0%` to `100%` |
+| `.icon` | The star glyph, rendered by the theme |
+| `.visually-hidden` | The value, read out by screen readers |
+
+The fill is computed where the markup is written, not here: star *n* takes `(rating − n + 1) × 100%`, clamped between `0%` and `100%`. A star with no `--rating-fill` is empty.
+
+## The fill goes through the mask
+
+This package ships no star. The `.icon` is the theme's, and the rating expects it to be a **mask**: an element whose `background` shows through the glyph, as the Hugolify icons render.
+
+```css
+.rating-star .icon {
+  background: linear-gradient(
+    to right,
+    var(--rating-color-active) var(--rating-fill, 0%),
+    var(--rating-color-empty) var(--rating-fill, 0%)
+  );
+}
+```
+
+Both colour stops sit at the same position, so the gradient is a hard edge, not a blend: the glyph is in the active colour up to its fill and in the empty colour after it. With an outline icon set, such as Lucide, that is the outline which changes colour, not the inside of the star.
+
+An icon inlined as an `<svg>` ignores the background and is not filled.
+
+Under `:dir(rtl)` the glyph is mirrored, so stars fill from the right.
+
+## Size and alignment
+
+The rating sets `--icon-size` from `--rating-size`, so the stars follow the rating rather than the font size around them.
+
+It is a flex row aligned to the start. `--rating-justify-content` moves it, which is how a centred context, a quote for instance, centres its stars without a modifier:
+
+```css
+.quote .rating {
+  --rating-justify-content: center;
+}
+```
+
+`--rating-gap` is `0` by default: the star glyph carries its own inner margin, and a gap would only widen the row.
+
+## Accessibility
+
+The stars carry no meaning for assistive technology: each `.icon` is `aria-hidden`, and the value is given as text in a `.visually-hidden` span, in words rather than as a fraction.
+
+The empty colour defaults to `--color-text-muted` rather than a border colour, so an empty star stays visible on a muted background such as a card.

package/docs/content/surtitle.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Surtitle
 description: An eyebrow label above a heading, tightened automatically when it sits inside a card.
-weight: 10
+weight: 11
 icon: type-h2
 ---
 

package/docs/forms/form.md

@@ -55,15 +55,38 @@ Change the floor with `--form-col-min-width`. Raising it past 50% forces a singl
 | `.full` | Spans both columns, `grid-column: 1 / -1` |
 | `.actions` | Spans both columns and stacks its children vertically |
 | `.help` | Help text under a field |
+| `.required` | Spans both columns, aligned to the start, no block margin |
+| `.alert` | Spans both columns |
 
 `.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.
 
+`.required` is the line explaining the asterisk of the required fields. Put it before the first field: the RGAA wants the meaning of a non-textual indication such as `*` given before its first use, visually and in the source order. It stays aligned with the labels even in a centred container.
+
+## Async submission
+
+A script that submits the form without leaving the page shows its answer in an `.alert` placed among the fields, `hidden` until then, and sets these states on the form:
+
+| State | Effect |
+| --- | --- |
+| `.is-submitting` | `cursor: progress` while the request runs |
+| `.is-success` | Hides every direct child but the `.alert`, so only the answer remains |
+| `.has-error` | No rule: the fields stay, the `.alert` (e.g. `.alert-danger`) carries the error |
+
+```html
+<form class="form is-success">
+  <p class="required">* Required fields</p>
+  <div>…</div>
+  <p class="alert alert-success" role="status" tabindex="-1">Thank you!</p>
+  <div class="actions">…</div>
+</form>
+```
+
 ## 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.
+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 the submission states, nothing else, which is why a form built without `.form` still looks right, it is simply stacked.

package/docs/overview.md

@@ -1,12 +1,12 @@
 ---
 isIndex: false
 title: Overview
-description: The 30 components and 1 utility, how to install them, the import order inside the package, and what it deliberately leaves out.
+description: The 31 components and 1 utility, how to install them, the import order inside the package, and what it deliberately leaves out.
 weight: 1
 icon: book
 ---
 
-`@uncinq/css-components` is the top of the stack: 30 components and 1 utility, written as plain CSS, reading their values from [@uncinq/component-tokens](../../component-tokens/) and adding no values of their own.
+`@uncinq/css-components` is the top of the stack: 31 components and 1 utility, written as plain CSS, reading their values from [@uncinq/component-tokens](../../component-tokens/) and adding no values of their own.
 
 ```
 @uncinq/design-tokens      primitive + semantic values
@@ -25,7 +25,7 @@ One page per component, grouped into six sections.
 | --- | --- |
 | [Buttons](../buttons/) | [`.btn`](../buttons/btn/), [`.btn-close`](../buttons/btn-close/), [`.btn-menu`](../buttons/btn-menu/), [`.btn-search`](../buttons/btn-search/), [`.btn-filter`](../buttons/btn-filter/), [`.btn-share`](../buttons/btn-share/), [`.btn-toc`](../buttons/btn-toc/), [`.btn-toggle-video`](../buttons/btn-toggle-video/) |
 | [Overlays](../overlays/) | [panel](../overlays/panel/), [`.modal`](../overlays/modal/), [`.drawer`](../overlays/drawer/), [`.dropdown`](../overlays/dropdown/) |
-| [Content](../content/) | [`.alert`](../content/alert/), [`.badge`](../content/badge/), [`.banner`](../content/banner/), [`.card`](../content/card/), [`.items`](../content/items/), [`.list`](../content/list/), [`.media`](../content/media/), [`.push`](../content/push/), [`.surtitle`](../content/surtitle/) |
+| [Content](../content/) | [`.alert`](../content/alert/), [`.badge`](../content/badge/), [`.banner`](../content/banner/), [`.card`](../content/card/), [`.items`](../content/items/), [`.list`](../content/list/), [`.media`](../content/media/), [`.push`](../content/push/), [`.rating`](../content/rating/), [`.surtitle`](../content/surtitle/) |
 | [Navigation](../navigation/) | [`.nav`](../navigation/nav/), [`.nav-title`](../navigation/nav-title/), [`.nav-accessibility`](../navigation/nav-accessibility/), [`.breadcrumb-wrapper`](../navigation/breadcrumb/), [`.pagination`](../navigation/pagination/) |
 | [Embeds](../embeds/) | [`.embed`](../embeds/embed/), [`.video`](../embeds/video/), [`.map`](../embeds/map/) |
 | [Forms](../forms/) | [`.form`](../forms/form/), [`.form-check`](../forms/form-check/) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncinq/css-components",
-  "version": "1.27.3",
+  "version": "1.28.0",
   "description": "Framework-agnostic CSS component implementations.",
   "license": "MIT",
   "repository": {