@fusion.dev/helix-headless 0.33.4 → 0.33.5

package/custom-elements.json

@@ -9526,6 +9526,20 @@
           "kind": "class",
           "description": "The track is a scroller with scroll snapping, so a drag, a trackpad swipe,\nand the browser's own momentum all work without being reimplemented. The\ncontrols scroll it; they do not drive a transform.\n\nSlides are the consumer's own elements, and nothing is written onto them. The\ncomponent renders a pane per slide carrying `role=\"group\"`,\n`aria-roledescription=\"slide\"` and a name reading its position in the set,\nand assigns the slide into it: a screen-reader user hears where they are, and\na slide that is itself a link is still a link. See `assign`.\n\n**Rotation stops on focus and on hover, and once stopped it stays stopped.**\nThe APG is explicit: rotation must not resume unless the reader asks for it,\nso hovering away does not start it again. The control names the action it\nperforms, and it is first in the tab order.",
           "name": "HelixHeadlessCarousel",
+          "cssProperties": [
+            {
+              "description": "Space between slides. A sheet sets it and the component measures the run with it.",
+              "name": "--carousel-gap"
+            },
+            {
+              "description": "The size one pane is laid out at. A sheet sets it and the component measures the run with it.",
+              "name": "--carousel-pane"
+            },
+            {
+              "description": "How far short of a whole pixel the run ends, on the last slide alone, for a sheet to take up as `margin-inline-end`. See `runEnd`.",
+              "name": "--carousel-run-end"
+            }
+          ],
           "cssParts": [
             {
               "description": "The row of controls.",
@@ -9966,6 +9980,17 @@
               },
               "description": "Puts each slide into the pane rendered for it.\n\n**The panes carry the ARIA and the consumer's element carries none**, which\nis the whole reason this is a manual assignment rather than a plain slot.\nThe APG wants each slide to be a `group` with `aria-roledescription=\"slide\"`\nand a name saying where it sits in the run, and writing those onto the\nelements a consumer wrote fails twice, only one of them about frameworks.\n\n**A React consumer's slides are nodes React is in the middle of hydrating.**\nAttributes landing before React reaches them are a DOM it did not render,\nwhich it reports as a mismatch and will not patch up: the ARIA survives and\nthe announcement is correct, so the console is the only tell. Deferring the\nwrite does not help, a frame being a race rather than an ordering: measured\nin Chromium on the landing page, a tab opened in the foreground still\nreported the mismatch and a tab opened hidden did not, only because\n`requestAnimationFrame` had not run there yet. `Chat`'s comment on\n`shadowRootOptions` reaches the same conclusion.\n\n**And `role=\"group\"` on a consumer's `<a href>` is not additive.** It\nreplaces the implicit link role, so six insight cards on the landing page\nannounced as groups and left the links list entirely. No amount of\ndeferring helps, because the write is the bug. A pane around the slide is\nwhat the pattern actually asks for: a group holding a link, rather than a\nlink relabeled as a group."
             },
+            {
+              "kind": "method",
+              "name": "runEnd",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string | typeof nothing"
+                }
+              },
+              "description": "How far short of a whole pixel the run of slides ends, for the last one.\n\n**The run has to end on a whole pixel, because a right-to-left track cannot\nreach a fraction.** Three across 692 makes the run 450.66 longer than the\ntrack. Chromium measures a right-to-left scroller from its far end and\nfloors that length, so the track stops at -450 where a left-to-right one\nrounds to 451, and two thirds of a pixel of the slide before stays at the\nleading edge. Ending on a whole pixel, the far end is one number both ways\nand the last place rests on it in both, so a swipe to the end stops there\ntoo.\n\n**Here rather than in a stylesheet, because the count is the component's.**\nThe arithmetic wants how many slides there are, and CSS can only ask\n`sibling-count()`, which is Chromium-only, evaluates to 0 through\n`::part()`, and needs a `:last-child` that `::part()` cannot carry either.\nSo the styled tier could correct its run and a consumer writing their own\nseveral-across sheet could not: measured in Chromium at three across, the\nheadless tier rested at 451 against -450 while the styled tier rested at\none number both ways. Published from here, one declaration reading this\ngets both tiers and any consumer to the same place.\n\n**WebKit takes the margin and does not need it**, which is the reason a\ncorrection written in CSS looked like enough. It has no `sibling-count()`\nat all, so nothing reached that engine, and its track rested on one number\nboth ways anyway. Measured with the margin in place, the same widths:\nevery resting place is the number it was without it.\n\n**On the last slide alone, which is what makes that one declaration\nenough.** A sheet writes `margin-inline-end: var(--carousel-run-end, 0px)`\nacross every pane and the fallback answers on all but the last, so nothing\nhas to select a slide by its position in the run.\n\n**A sheet says how wide a pane is and how far apart they sit, and this\nreads both back.** Set neither and the correction is invalid at\ncomputed-value time, which is the fallback rather than a broken margin. The\npercentage resolves where the value is used, on the last pane, so it is the\ntrack's content box and not the track's own containing block: the width the\nrun is actually measured against.\n\nHorizontal only. A vertical track scrolls the other axis, `scrollTop`\ncounts up from zero whatever the writing mode, and there is no far end to\nfloor."
+            },
             {
               "kind": "field",
               "name": "tier",
@@ -10402,6 +10427,10 @@
               {
                 "description": "The same carousel on the headless tier, with every rule written by hand.",
                 "slug": "preview"
+              },
+              {
+                "description": "Three slides across, with the pane, the gap and the run's end written by hand.",
+                "slug": "several-across"
               }
             ],
             "source": "helix/headless/src/carousel"

package/dist/carousel/root/carousel-root.d.ts

@@ -41,6 +41,10 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @csspart rotation-mark - The glyph on the play and pause control.
  * @csspart slide - The pane one slide is shown in, and the box the track snaps to.
  * @csspart track - The scroller the slides sit in.
+ *
+ * @cssproperty --carousel-gap - Space between slides. A sheet sets it and the component measures the run with it.
+ * @cssproperty --carousel-pane - The size one pane is laid out at. A sheet sets it and the component measures the run with it.
+ * @cssproperty --carousel-run-end - How far short of a whole pixel the run ends, on the last slide alone, for a sheet to take up as `margin-inline-end`. See `runEnd`.
  */
 export declare class HelixHeadlessCarousel extends HelixElement {
     /**
@@ -394,6 +398,51 @@ export declare class HelixHeadlessCarousel extends HelixElement {
      * link relabeled as a group.
      */
     private assign;
+    /**
+     * How far short of a whole pixel the run of slides ends, for the last one.
+     *
+     * **The run has to end on a whole pixel, because a right-to-left track cannot
+     * reach a fraction.** Three across 692 makes the run 450.66 longer than the
+     * track. Chromium measures a right-to-left scroller from its far end and
+     * floors that length, so the track stops at -450 where a left-to-right one
+     * rounds to 451, and two thirds of a pixel of the slide before stays at the
+     * leading edge. Ending on a whole pixel, the far end is one number both ways
+     * and the last place rests on it in both, so a swipe to the end stops there
+     * too.
+     *
+     * **Here rather than in a stylesheet, because the count is the component's.**
+     * The arithmetic wants how many slides there are, and CSS can only ask
+     * `sibling-count()`, which is Chromium-only, evaluates to 0 through
+     * `::part()`, and needs a `:last-child` that `::part()` cannot carry either.
+     * So the styled tier could correct its run and a consumer writing their own
+     * several-across sheet could not: measured in Chromium at three across, the
+     * headless tier rested at 451 against -450 while the styled tier rested at
+     * one number both ways. Published from here, one declaration reading this
+     * gets both tiers and any consumer to the same place.
+     *
+     * **WebKit takes the margin and does not need it**, which is the reason a
+     * correction written in CSS looked like enough. It has no `sibling-count()`
+     * at all, so nothing reached that engine, and its track rested on one number
+     * both ways anyway. Measured with the margin in place, the same widths:
+     * every resting place is the number it was without it.
+     *
+     * **On the last slide alone, which is what makes that one declaration
+     * enough.** A sheet writes `margin-inline-end: var(--carousel-run-end, 0px)`
+     * across every pane and the fallback answers on all but the last, so nothing
+     * has to select a slide by its position in the run.
+     *
+     * **A sheet says how wide a pane is and how far apart they sit, and this
+     * reads both back.** Set neither and the correction is invalid at
+     * computed-value time, which is the fallback rather than a broken margin. The
+     * percentage resolves where the value is used, on the last pane, so it is the
+     * track's content box and not the track's own containing block: the width the
+     * run is actually measured against.
+     *
+     * Horizontal only. A vertical track scrolls the other axis, `scrollTop`
+     * counts up from zero whatever the writing mode, and there is no far end to
+     * floor.
+     */
+    private runEnd;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/carousel/root/carousel-root.js

@@ -241,8 +241,17 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
             panes[index]?.assign?.(slide);
         });
     }
+    runEnd() {
+        if (this.orientation === 'vertical') {
+            return nothing;
+        }
+        const run = `${this.slides.length} * (var(--carousel-pane) + var(--carousel-gap))` +
+            ' - var(--carousel-gap) - 100%';
+        return `--carousel-run-end: calc(round(${run}, 1px) - (${run}))`;
+    }
     render() {
         const rotating = this.rotating;
+        const last = this.slides.length - 1;
         return html `<div part="controls">
         ${this.autoplay
             ? html `<button
@@ -297,6 +306,7 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
             role="group"
             aria-roledescription="slide"
             aria-label=${`${index + 1} of ${this.slides.length}`}
+            style=${index === last ? this.runEnd() : nothing}
           >
             <slot
               name=${this.assignsByName ? `slide-${index + 1}` : nothing}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.33.4",
+  "version": "0.33.5",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -46,14 +46,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.33.4",
-    "@fusion.dev/helix-icons": "0.33.4",
+    "@fusion.dev/helix-core": "0.33.5",
+    "@fusion.dev/helix-icons": "0.33.5",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.33.4",
-    "@fusion.dev/helix-testing": "0.33.4",
+    "@fusion.dev/helix-cem": "0.33.5",
+    "@fusion.dev/helix-testing": "0.33.5",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",

package/types/jsx.d.ts

@@ -18781,6 +18781,14 @@ export type CustomElements = {
    *
    * - `goTo(index: number) => void`: Moves to a slide, wrapping only where `loop` says to.
    *
+   * ## CSS Custom Properties
+   *
+   * CSS variables available for styling the component.
+   *
+   * - `--carousel-gap`: Space between slides. A sheet sets it and the component measures the run with it. (default: `undefined`)
+   * - `--carousel-pane`: The size one pane is laid out at. A sheet sets it and the component measures the run with it. (default: `undefined`)
+   * - `--carousel-run-end`: How far short of a whole pixel the run ends, on the last slide alone, for a sheet to take up as `margin-inline-end`. See `runEnd`. (default: `undefined`)
+   *
    * ## CSS Parts
    *
    * Custom selectors for styling elements within the component.
@@ -36172,6 +36180,14 @@ export type CustomElementsSolidJs = {
    *
    * - `goTo(index: number) => void`: Moves to a slide, wrapping only where `loop` says to.
    *
+   * ## CSS Custom Properties
+   *
+   * CSS variables available for styling the component.
+   *
+   * - `--carousel-gap`: Space between slides. A sheet sets it and the component measures the run with it. (default: `undefined`)
+   * - `--carousel-pane`: The size one pane is laid out at. A sheet sets it and the component measures the run with it. (default: `undefined`)
+   * - `--carousel-run-end`: How far short of a whole pixel the run ends, on the last slide alone, for a sheet to take up as `margin-inline-end`. See `runEnd`. (default: `undefined`)
+   *
    * ## CSS Parts
    *
    * Custom selectors for styling elements within the component.
@@ -51967,6 +51983,12 @@ export type CustomCssProperties = {
   "--bar-chart-secondary"?: (string) | undefined;
   /** The gradient a bar would take, named per bar so the styled tier can point `fill` at it. Drawn whatever the treatment and used only where `wash="gradient"` asks for it. */
   "--chart-bar-wash"?: (string) | undefined;
+  /** Space between slides. A sheet sets it and the component measures the run with it. */
+  "--carousel-gap"?: (string) | undefined;
+  /** The size one pane is laid out at. A sheet sets it and the component measures the run with it. */
+  "--carousel-pane"?: (string) | undefined;
+  /** How far short of a whole pixel the run ends, on the last slide alone, for a sheet to take up as `margin-inline-end`. See `runEnd`. */
+  "--carousel-run-end"?: (string) | undefined;
   /** The chosen color, to paint over the transparency check. */
   "--color-input-swatch"?: (string) | undefined;
   /** The chosen brightness, 0 to 100, as a percentage. */

package/types/vue.d.ts

@@ -8715,6 +8715,12 @@ export type CustomCssProperties = {
   "--bar-chart-secondary"?: (string) | undefined;
   /** The gradient a bar would take, named per bar so the styled tier can point `fill` at it. Drawn whatever the treatment and used only where `wash="gradient"` asks for it. */
   "--chart-bar-wash"?: (string) | undefined;
+  /** Space between slides. A sheet sets it and the component measures the run with it. */
+  "--carousel-gap"?: (string) | undefined;
+  /** The size one pane is laid out at. A sheet sets it and the component measures the run with it. */
+  "--carousel-pane"?: (string) | undefined;
+  /** How far short of a whole pixel the run ends, on the last slide alone, for a sheet to take up as `margin-inline-end`. See `runEnd`. */
+  "--carousel-run-end"?: (string) | undefined;
   /** The chosen color, to paint over the transparency check. */
   "--color-input-swatch"?: (string) | undefined;
   /** The chosen brightness, 0 to 100, as a percentage. */