@uncinq/css-components 1.27.4 → 1.29.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/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/css/utilities/scrollsnap.css

@@ -68,6 +68,12 @@
     overflow-x: auto;
     overflow-y: hidden;
     padding-inline: var(--container-bleed, var(--gutter));
+    /* The row is the containing block of anything absolute inside it.
+       overflow only clips what it contains: without this, an absolute
+       descendant of an unpositioned item (the .visually-hidden label of a
+       .rating, say) anchors to an ancestor outside the row, escapes the clip
+       and widens the whole page by the length of the row. */
+    position: relative;
     scroll-snap-type: x mandatory;
 
     > * {
@@ -89,6 +95,7 @@
       overflow-x: revert-layer;
       overflow-y: revert-layer;
       padding-inline: revert-layer;
+      position: revert-layer;
       scroll-snap-type: revert-layer;
 
       > * {
@@ -107,6 +114,7 @@
       overflow-x: revert-layer;
       overflow-y: revert-layer;
       padding-inline: revert-layer;
+      position: revert-layer;
       scroll-snap-type: revert-layer;
 
       > * {
@@ -125,6 +133,7 @@
       overflow-x: revert-layer;
       overflow-y: revert-layer;
       padding-inline: revert-layer;
+      position: revert-layer;
       scroll-snap-type: revert-layer;
 
       > * {
@@ -143,6 +152,7 @@
       overflow-x: revert-layer;
       overflow-y: revert-layer;
       padding-inline: revert-layer;
+      position: revert-layer;
       scroll-snap-type: revert-layer;
 
       > * {

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/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.4",
+  "version": "1.29.0",
   "description": "Framework-agnostic CSS component implementations.",
   "license": "MIT",
   "repository": {