@fusion.dev/helix-headless 0.50.0 → 0.52.0

package/custom-elements.json

@@ -9612,12 +9612,16 @@
               "name": "--carousel-pane"
             },
             {
-              "description": "How many slides go across, written onto the track by the component so a sheet divides the track by the same number the positions are counted from. Read it rather than selecting on `per-view`, which cannot be enumerated without a ceiling. See `perView`.",
+              "description": "How many slides go across, written onto the track by the component so a sheet divides the track by the same number the positions are counted from. Read it rather than selecting on `per-view`, which cannot be enumerated without a ceiling. Under `per-view=\"auto\"` the component writes nothing and the sheet declares it instead, so the same name answers in both modes. See `perView`.",
               "name": "--carousel-per-view"
             },
             {
               "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"
+            },
+            {
+              "description": "The narrowest a slide may be laid out, which is what `per-view=\"auto\"` fits the track with. A length, since the sheet divides by it. Unset is the whole track, which is one across.",
+              "name": "--carousel-slide-min"
             }
           ],
           "cssParts": [
@@ -9808,20 +9812,40 @@
               "kind": "field",
               "name": "perView",
               "type": {
-                "text": "number | undefined"
+                "text": "number | 'auto' | undefined"
               },
-              "description": "How many slides are shown across the track at once. Absent shows one.\n\n**Here rather than on the styled tier, because it decides how many places\nthe track can stop.** From the stylesheet it looks like a width, one rule\nper value setting a custom property that the slides divide the track by.\nBut a carousel showing four of six slides has three positions, not six, and\neverything that counts positions is in this file. Declared up there, `goTo`\nclamps to the last *slide*, so three of the six indicators point at an\noffset the track has already reached: pressing next walks the dots to the\nend while the slides stop moving a third of the way through.\n\n**The number is published to the styles rather than enumerated by them**,\nas `--carousel-per-view` on the track, which is what keeps a width and a\ncount from disagreeing. A sheet can only name a value it wrote a rule for,\nso the styled tier enumerated `per-view=\"2\"` through `5` and called five a\njudgment; above it the pane fell back to one across while this file went on\ncounting positions. Measured in Chromium over eight slides, six across gave\nthree dots, a pane taking the whole track and five slides reachable only by\ndragging. Written from here there is no ceiling to exceed, and a consumer's\nown sheet reads the same declaration the styled one does. `runEnd` publishes\nits correction the same way and for the same reason.\n\n**On the track and not on the host.** A custom property on the host is a\nreflected attribute by another name: it would arrive on upgrade, and a\nconsumer's server markup never had it. Inside the component's own shadow\nroot it serializes with the rest of the template on the server, and the\ntrack's own declaration beats anything a consumer inherits in, so the\nattribute is the one answer to how wide a pane is.\n\nA value the track cannot honor is taken to the nearest one it can, by\n`across`, and both tiers read that rather than this.\n\nNo default, because it reflects. A reflected property with a value writes\nits attribute on upgrade, and the host then carries something a consumer's\nserver markup never had, which React reports as a mismatch. The one-across\ncase is the absent attribute, and the styles read it that way.",
+              "description": "How many slides are shown across the track at once. Absent shows one.\n\n**Here rather than on the styled tier, because it decides how many places\nthe track can stop.** From the stylesheet it looks like a width, one rule\nper value setting a custom property that the slides divide the track by.\nBut a carousel showing four of six slides has three positions, not six, and\neverything that counts positions is in this file. Declared up there, `goTo`\nclamps to the last *slide*, so three of the six indicators point at an\noffset the track has already reached: pressing next walks the dots to the\nend while the slides stop moving a third of the way through.\n\n**The number is published to the styles rather than enumerated by them**,\nas `--carousel-per-view` on the track, which is what keeps a width and a\ncount from disagreeing. A sheet can only name a value it wrote a rule for,\nso the styled tier enumerated `per-view=\"2\"` through `5` and called five a\njudgment; above it the pane fell back to one across while this file went on\ncounting positions. Measured in Chromium over eight slides, six across gave\nthree dots, a pane taking the whole track and five slides reachable only by\ndragging. Written from here there is no ceiling to exceed, and a consumer's\nown sheet reads the same declaration the styled one does. `runEnd` publishes\nits correction the same way and for the same reason.\n\n**On the track and not on the host.** A custom property on the host is a\nreflected attribute by another name: it would arrive on upgrade, and a\nconsumer's server markup never had it. Inside the component's own shadow\nroot it serializes with the rest of the template on the server, and the\ntrack's own declaration beats anything a consumer inherits in, so the\nattribute is the one answer to how wide a pane is.\n\nA value the track cannot honor is taken to the nearest one it can, by\n`across`, and both tiers read that rather than this.\n\n**`auto` fits as many as the track can hold**, at `--carousel-slide-min`\napiece, and nothing is written onto the track: the count is the sheet's,\nand the sheet's alone, because it is the one number here CSS can work out\nfor itself. Everything it takes is a length the sheet already has, so the\npanes are laid out at their final width by the first rule that runs, on a\nserver's markup as on the client's, and no script is waited on. That is the\nwhole reason a declared count was ever the only option: a carousel that\nasks how wide its container is can only ask on the client, so the panes go\ndown at one width and move to another when the answer arrives. Written\ninline the count would outrank the sheet that computes it, which is why an\n`auto` track is handed nothing. A count stays for the design that calls for\nexactly three.\n\nThe styled sheet says how it divides, and the headless `auto` example\ncarries the same three lines for a consumer writing their own.\n\n**A value rather than the resting behavior**, which is what the\nresponsiveness policy asks of every axis that a box decides: a splitter\nturns on `orientation=\"auto\"` and a plain one does not turn at all. Fitting\nchanges what the carousel *does*, since how many are across is how many\nplaces the track can stop, so a carousel that had not asked for it would\nfind its position count moving with the window.\n\nNo default, because it reflects. A reflected property with a value writes\nits attribute on upgrade, and the host then carries something a consumer's\nserver markup never had, which React reports as a mismatch. The one-across\ncase is the absent attribute, and the styles read it that way.",
               "attribute": "per-view",
               "reflects": true
             },
             {
               "kind": "field",
-              "name": "across",
+              "name": "clamped",
               "type": {
                 "text": "number"
               },
               "privacy": "private",
-              "description": "`perView` as both tiers use it: a whole number of slides, one at least.\n\n**The clamp is here because the arithmetic is here**, and the two readers\nof this number have to be given the same one. A fraction is floored, since\na position is a whole slide along: one and a half across leaves a last\nposition the track runs out before reaching, which is the fault `goTo`\nalready carries a comment about. Zero and a negative divide the track into\nnothing and into a pane facing the wrong way, and a non-numeric attribute\nparses to `NaN`, which `Math.max` propagates: it counted `NaN` positions,\ndrew no indicators at all and left `index` at `NaN`. All of them read as\none across, which is what a carousel with nothing sayable asked for.\n\nNot clamped to the number of slides. Six across four slides is four panes\nat a sixth of the track each and the one place to stand, which is what was\nasked for as nearly as it can be had, and the slide count is a fact the\nserver does not have: clamping to it would draw one width there and another\non upgrade.",
+              "description": "A declared `perView` as both tiers use it: a whole number, one at least.\n\n**The clamp is here because the arithmetic is here**, and the two readers\nof this number have to be given the same one. A fraction is floored, since\na position is a whole slide along: one and a half across leaves a last\nposition the track runs out before reaching, which is the fault `goTo`\nalready carries a comment about. Zero and a negative divide the track into\nnothing and into a pane facing the wrong way, and a non-numeric attribute\nparses to `NaN`, which `Math.max` propagates: it counted `NaN` positions,\ndrew no indicators at all and left `index` at `NaN`. All of them read as\none across, which is what a carousel with nothing sayable asked for.\n\n**A vertical `auto` is one of them.** Fitting divides the room the page\ngave the track, and a vertical track's room is a height the consumer chose\nwith `--carousel-block-size`: there is nothing there to fit against that\nthey did not already decide, so the count is theirs to state. It also\ncannot be had cheaply, the block axis wanting `container-type: size`, which\nlays a track out as empty wherever its height is not definite.\n\nNot clamped to the number of slides. Six across four slides is four panes\nat a sixth of the track each and the one place to stand, which is what was\nasked for as nearly as it can be had, and the slide count is a fact the\nserver does not have: clamping to it would draw one width there and another\non upgrade.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "fits",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "description": "Whether the track is fitting slides to its own box rather than to a count.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "across",
+              "type": {
+                "text": "number | undefined"
+              },
+              "privacy": "private",
+              "description": "How many slides go across, and `undefined` while a fitted track is unlaid.\n\n**Undefined is the honest answer and the indicators read it as one**, which\nis the whole of how a fitted carousel keeps from drawing a run of dots at\none length and correcting it at another. The count a fitted track goes\nacross is whatever its box resolved to, so nothing knows it until there is\na box: not the server, which has no layout, and not the render that draws\nthe panes, layout being what follows a render rather than what precedes it.\nThe dots wait for it, which costs them nothing, because a server serves no\nindicators for any carousel, `slides` being empty there.\n\nMeasured 16 Sep 2026 in Chromium 151.0.7922.34 and WebKit 26.5, recording\nevery run of dots a carousel has from the upgrade on: a fitted one goes\nnone, then five, and never another number; a declared one goes straight to\nsix. What a reader can see is the run missing, never the run wrong.",
               "readonly": true
             },
             {
@@ -9830,9 +9854,76 @@
               "type": {
                 "text": "number"
               },
-              "description": "How many distinct views the track holds, which is what the indicators count.\n\nA window of `perView` slides sliding one at a time over `n` of them stops\n`n - perView + 1` times, so six slides four across is three: 0 to 3, 1 to 4,\n2 to 5. One at minimum, since a carousel showing everything it has still\nhas the one place to be.",
+              "description": "How many distinct views the track holds, which is what the indicators count.\n\nA window of `perView` slides sliding one at a time over `n` of them stops\n`n - perView + 1` times, so six slides four across is three: 0 to 3, 1 to 4,\n2 to 5. One at minimum, since a carousel showing everything it has still\nhas the one place to be.\n\nOne across until a fitted track has been laid out, which is the same answer\na carousel that has never been told anything gives, and the dots are\nwithheld rather than counted from it. See `across`.",
               "readonly": true
             },
+            {
+              "kind": "method",
+              "name": "measure",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number | undefined"
+                }
+              },
+              "description": "How many slides the box turned out to hold, from the pane it laid out.\n\n**The measurement asks what happened rather than what was asked for**, and\nthat is why it is the pane's width and not the count in the declaration.\nThe sheet divides the track by `--carousel-per-view`, which under `auto` is\narithmetic rather than a number, and a consumer's own sheet may divide it\nsome other way entirely or grow the panes to fill a track holding\neverything it has. Reading the box back gets the same answer as the\ndeclaration wherever the two agree and the true one wherever they do not,\nso a width and a count cannot disagree in either direction.\n\nThe sheet's own arithmetic run backward, on the lengths that were actually\nused: a gap added to the room, divided by a pane and a gap. Rounded,\nbecause the pane a sheet lays out is a sixty-fourth off its exact share by\ndesign and the quotient lands a ten-thousandth off a whole number.\n\nUndefined where there is nothing to measure, which is a harness rather than\na browser: happy-dom lays nothing out and reports zero for every box, and a\ncount taken from zeros would be a number with no layout behind it."
+            },
+            {
+              "kind": "field",
+              "name": "readFit",
+              "privacy": "private",
+              "readonly": true,
+              "description": "Takes the reading, and puts the index back inside what it leaves.\n\n**A fitted carousel's last position moves with the window**, which a\ndeclared one's never does: eight slides at one across has eight places to\nstand and four across has five, so a track widened while the reader sits on\nthe last of them is a track resting somewhere it can no longer be. Through\n`goTo`, so the correction goes out as the same cancelable announcement\nevery other index change does and a consumer holding `index` hears it\nrather than being overwritten.\n\nOnly on a change, so the observer's own re-render cannot feed itself."
+            },
+            {
+              "kind": "method",
+              "name": "handed",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string | typeof nothing"
+                }
+              },
+              "description": "The count handed to the styles, and nothing at all where they work it out.\n\nA declared count is this file's: it decides how many places the track can\nstop, so the number the panes are divided by has to be the number the\npositions were counted from, and writing it on the track inside the\ncomponent's own shadow root is what keeps a sheet from having to enumerate\nthe values it will answer for.\n\nA fitted one is the sheet's, and handing it anything would take it back: an\ninline declaration outranks every rule short of `!important`, so a track\ntold `1` here could never be told three by the rule that fits it. The\nabsence is not a gap either, because the rule that computes the count\ndeclares it on this same element, which beats anything a consumer inherits\nin exactly as the inline one did."
+            },
+            {
+              "kind": "field",
+              "name": "fitted",
+              "type": {
+                "text": "number | undefined"
+              },
+              "privacy": "private",
+              "description": "What the box resolved to, and `undefined` until it has been laid out."
+            },
+            {
+              "kind": "field",
+              "name": "sizes",
+              "type": {
+                "text": "ResizeObserver | undefined"
+              },
+              "privacy": "private",
+              "description": "Watches the pane a fitted track laid out, while `auto` is what was asked."
+            },
+            {
+              "kind": "field",
+              "name": "watched",
+              "type": {
+                "text": "HTMLElement | undefined"
+              },
+              "privacy": "private",
+              "description": "The pane being watched, so a re-rendered run moves the watch with it."
+            },
+            {
+              "kind": "method",
+              "name": "watchPane",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Starts or stops watching, according to what the count was asked to be.\n\n**The pane and not the track, because both questions move it.** A narrower\ntrack divides into a narrower pane, and so does a slide arriving or leaving\nwhere the panes grow to fill a track holding everything it has. A watch on\nthe track answers the first and sleeps through the second.\n\n**An observation is delivered after layout and inside the same rendering\nstep**, and the update it asks for is a microtask on the end of it, so the\ndots are added to a frame that has not been painted. Taking the reading\nfrom `updated` instead would be the same arithmetic one Lit warning\nearlier, and the warning is about the right thing: a render that has to\nread layout is a render that has to run twice.\n\nCalled from `connectedCallback`, `firstUpdated` and `updated`, so a\nconsumer switching to `auto` after mount is watched, one switching away\nstops being, and a carousel moved in the DOM is watched again. Observing is\nwhat asks for the first reading, so the watch is rebuilt rather than kept\nacross a mode change."
+            },
             {
               "kind": "field",
               "name": "panes",
@@ -9897,7 +9988,7 @@
                   }
                 }
               ],
-              "description": "The leading padding the track keeps for a slide to draw its own edge in.\n\nA styled track carries one so a slide's shadow and focus ring have\nsomewhere to go: a scroll container clips at its padding box, and a slide\nflush against that edge loses whatever it paints outside itself. The\nheadless tier has no stylesheet and so no padding, and this reads zero\nthere, which is why both tiers can share the arithmetic below.\n\nPhysical sides rather than logical, to match the physical `offsetLeft` and\n`offsetTop` it is subtracted from. The bleed is one length on all four\nsides, so the two agree whatever the writing mode; if that stops being\ntrue, this is the method that has to know."
+              "description": "The leading padding the track keeps for a slide to draw its own edge in.\n\nA styled track carries one so a slide's shadow and focus ring have\nsomewhere to go: a scroll container clips at its padding box, and a slide\nflush against that edge loses whatever it paints outside itself. The\nheadless tier has no stylesheet and so no padding, and this reads zero\nthere, which is why both tiers can share the arithmetic below.\n\nPhysical sides rather than logical, to match the physical `offsetLeft` and\n`offsetTop` it is subtracted from.\n\n**The side read is the side the track scrolls on, and not one side standing\nfor four.** They are one length on a track laid out at the defaults and\nstop being one the moment a consumer raises `--carousel-bleed`, which the\nhook exists to invite: a slide on `--helix-shadow-lg` reaches 44px and is\ntold to ask for it. So a horizontal track's room is its inline padding and\na vertical one's is its block padding, and each sheet puts the bleed where\nthe scroller clips. Reading one side for both would have a vertical track\nmeasuring a length nothing on its axis was laid out with."
             },
             {
               "kind": "method",
@@ -10489,9 +10580,9 @@
             {
               "name": "per-view",
               "type": {
-                "text": "number | undefined"
+                "text": "number | 'auto' | undefined"
               },
-              "description": "How many slides are shown across the track at once. Absent shows one.\n\n**Here rather than on the styled tier, because it decides how many places\nthe track can stop.** From the stylesheet it looks like a width, one rule\nper value setting a custom property that the slides divide the track by.\nBut a carousel showing four of six slides has three positions, not six, and\neverything that counts positions is in this file. Declared up there, `goTo`\nclamps to the last *slide*, so three of the six indicators point at an\noffset the track has already reached: pressing next walks the dots to the\nend while the slides stop moving a third of the way through.\n\n**The number is published to the styles rather than enumerated by them**,\nas `--carousel-per-view` on the track, which is what keeps a width and a\ncount from disagreeing. A sheet can only name a value it wrote a rule for,\nso the styled tier enumerated `per-view=\"2\"` through `5` and called five a\njudgment; above it the pane fell back to one across while this file went on\ncounting positions. Measured in Chromium over eight slides, six across gave\nthree dots, a pane taking the whole track and five slides reachable only by\ndragging. Written from here there is no ceiling to exceed, and a consumer's\nown sheet reads the same declaration the styled one does. `runEnd` publishes\nits correction the same way and for the same reason.\n\n**On the track and not on the host.** A custom property on the host is a\nreflected attribute by another name: it would arrive on upgrade, and a\nconsumer's server markup never had it. Inside the component's own shadow\nroot it serializes with the rest of the template on the server, and the\ntrack's own declaration beats anything a consumer inherits in, so the\nattribute is the one answer to how wide a pane is.\n\nA value the track cannot honor is taken to the nearest one it can, by\n`across`, and both tiers read that rather than this.\n\nNo default, because it reflects. A reflected property with a value writes\nits attribute on upgrade, and the host then carries something a consumer's\nserver markup never had, which React reports as a mismatch. The one-across\ncase is the absent attribute, and the styles read it that way.",
+              "description": "How many slides are shown across the track at once. Absent shows one.\n\n**Here rather than on the styled tier, because it decides how many places\nthe track can stop.** From the stylesheet it looks like a width, one rule\nper value setting a custom property that the slides divide the track by.\nBut a carousel showing four of six slides has three positions, not six, and\neverything that counts positions is in this file. Declared up there, `goTo`\nclamps to the last *slide*, so three of the six indicators point at an\noffset the track has already reached: pressing next walks the dots to the\nend while the slides stop moving a third of the way through.\n\n**The number is published to the styles rather than enumerated by them**,\nas `--carousel-per-view` on the track, which is what keeps a width and a\ncount from disagreeing. A sheet can only name a value it wrote a rule for,\nso the styled tier enumerated `per-view=\"2\"` through `5` and called five a\njudgment; above it the pane fell back to one across while this file went on\ncounting positions. Measured in Chromium over eight slides, six across gave\nthree dots, a pane taking the whole track and five slides reachable only by\ndragging. Written from here there is no ceiling to exceed, and a consumer's\nown sheet reads the same declaration the styled one does. `runEnd` publishes\nits correction the same way and for the same reason.\n\n**On the track and not on the host.** A custom property on the host is a\nreflected attribute by another name: it would arrive on upgrade, and a\nconsumer's server markup never had it. Inside the component's own shadow\nroot it serializes with the rest of the template on the server, and the\ntrack's own declaration beats anything a consumer inherits in, so the\nattribute is the one answer to how wide a pane is.\n\nA value the track cannot honor is taken to the nearest one it can, by\n`across`, and both tiers read that rather than this.\n\n**`auto` fits as many as the track can hold**, at `--carousel-slide-min`\napiece, and nothing is written onto the track: the count is the sheet's,\nand the sheet's alone, because it is the one number here CSS can work out\nfor itself. Everything it takes is a length the sheet already has, so the\npanes are laid out at their final width by the first rule that runs, on a\nserver's markup as on the client's, and no script is waited on. That is the\nwhole reason a declared count was ever the only option: a carousel that\nasks how wide its container is can only ask on the client, so the panes go\ndown at one width and move to another when the answer arrives. Written\ninline the count would outrank the sheet that computes it, which is why an\n`auto` track is handed nothing. A count stays for the design that calls for\nexactly three.\n\nThe styled sheet says how it divides, and the headless `auto` example\ncarries the same three lines for a consumer writing their own.\n\n**A value rather than the resting behavior**, which is what the\nresponsiveness policy asks of every axis that a box decides: a splitter\nturns on `orientation=\"auto\"` and a plain one does not turn at all. Fitting\nchanges what the carousel *does*, since how many are across is how many\nplaces the track can stop, so a carousel that had not asked for it would\nfind its position count moving with the window.\n\nNo default, because it reflects. A reflected property with a value writes\nits attribute on upgrade, and the host then carries something a consumer's\nserver markup never had, which React reports as a mismatch. The one-across\ncase is the absent attribute, and the styles read it that way.",
               "fieldName": "perView"
             }
           ],
@@ -10503,7 +10594,7 @@
           "helix": {
             "category": "layout",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/carousel",
             "aliases": [
               "Slider",
@@ -10518,6 +10609,10 @@
                 "description": "The same carousel on the headless tier, with every rule written by hand.",
                 "slug": "preview"
               },
+              {
+                "description": "As many slides as the track holds, from a minimum width and no count.",
+                "slug": "auto"
+              },
               {
                 "description": "Three slides across, with the pane, the gap and the run's end written by hand.",
                 "slug": "several-across"
@@ -80833,7 +80928,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "**One axis, and nesting is how you get two.** A splitter inside a splitter\ngives back the cross, and gives the three-pane and four-pane arrangements a\nsingle divider never had.\n\n**Where two of them cross there is a corner, and it moves both.** A splitter\nslotted into a pane of another, at right angles to it, grows a handle at the\ncrossing: `move` under the pointer, both arrow axes on the keyboard, and a\ndrag that carries the two positions at once. It appears at `firstUpdated`\nrather than in the served markup, being an affordance rather than content,\nand a splitter with no corner yet is a splitter with two working dividers.\n\n**The divider is a real `role=\"separator\"` with `aria-valuenow`**, moved by\nthe arrow keys as well as by pointer, with `Home` and `End` taking it to its\nbounds. A drag in progress is a state rather than `:hover`, so both dividers\na corner moves are lit for as long as it moves them.\n\n**It goes where it is put, all the way to either end.** `min` and `max` are\nnothing and everything unless a consumer says otherwise, because a divider\nthat stops short of the edge gives a reader no way to put a pane away.\n\n**A pane can be shut, and that is not the same as a divider at the edge.**\nThe geometry is identical and the knowledge is not: only a shut pane knows\nwhere to open back to. So `collapsed` is a second state rather than a reading\nof the position, and the position it opens to is the one collapsing never\noverwrote. `collapsed-size` keeps a sliver showing where a pane has a tab\nstrip worth leaving, and collapse overrides `min` and `max`, which is what\nthose are for.",
+          "description": "**One axis, and nesting is how you get two.** A splitter inside a splitter\ngives back the cross, and gives the three-pane and four-pane arrangements a\nsingle divider never had.\n\n**Where two of them cross there is a corner, and it moves both.** A splitter\nslotted into a pane of another, at right angles to it, grows a handle at the\ncrossing: `move` under the pointer, both arrow axes on the keyboard, and a\ndrag that carries the two positions at once. It appears at `firstUpdated`\nrather than in the served markup, being an affordance rather than content,\nand a splitter with no corner yet is a splitter with two working dividers.\n\n**The divider is a real `role=\"separator\"` with `aria-valuenow`**, moved by\nthe arrow keys as well as by pointer, with `Home` and `End` taking it to its\nbounds. A drag in progress is a state rather than `:hover`, so both dividers\na corner moves are lit for as long as it moves them.\n\n**It goes where it is put, all the way to either end.** `min` and `max` are\nnothing and everything unless a consumer says otherwise, because a divider\nthat stops short of the edge gives a reader no way to put a pane away.\n\n**A pane can be shut, and that is not the same as a divider at the edge.**\nThe geometry is identical and the knowledge is not: only a shut pane knows\nwhere to open back to. So `collapsed` is a second state rather than a reading\nof the position, and the position it opens to is where the gesture that shut\nit began, whichever gesture that was: a drag takes its reading on the press,\nand every other door takes it in `settle`, nothing having been applied there\nyet. `collapsed-size` keeps a sliver showing where a pane has a tab strip\nworth leaving, and collapse overrides `min` and `max`, which is what those\nare for.",
           "name": "HelixHeadlessSplitter",
           "cssProperties": [
             {
@@ -81054,7 +81149,7 @@
               },
               "privacy": "private",
               "default": "undefined",
-              "description": "Where the divider was before the gesture that may be about to shut it.\n\nA drag writes a position on every pointer move, so by the time it reaches\nthe edge the number it started from is gone. Taken once, on the press, and\nwritten back if the gesture ends shut, so the pane opens to where it was\nrather than to the edge it was dragged against."
+              "description": "Where the divider was before the gesture that may be about to shut it.\n\nA drag writes a position on every pointer move, so by the time it reaches\nthe edge the number it started from is gone. Taken once, on the press, and\nwritten back if the gesture ends shut, so the pane opens to where it was\nrather than to the edge it was dragged against.\n\n**A pointer gesture only, because it is the only one that loses it**, and\n`settle` answers for the rest from `began`: a key and a double click apply\nnothing before they settle, so where the divider is at the top of that\nmethod is where it was. Read once and cleared there, exactly as `began` is,\nand for the second reason as well as the first. Left standing it measured\nthe next gesture against the last one's press, so a collapse pressed from\n20 reopened at the 60 a drag had started from an hour earlier."
             },
             {
               "kind": "field",
@@ -81304,7 +81399,7 @@
                   }
                 }
               ],
-              "description": "Says the arrangement has settled, so a consumer can keep it.\n\nThrough the audited path, so a consumer who owns `position` is told what was\nasked for and decides, and one who does not has already had it applied.\n\n**The second announcement is conditional on the first, because it is derived\nfrom it.** `shutAt` reads the position the gesture ended on, so a refused\n`helix-before-resize` leaves a collapse computed from a number that was\nrefused. Announced anyway, the refusal produced the outcome it was refusing:\nmeasured on a divider at 40 with a listener calling `preventDefault`, Home\nleft `position` reporting 0 and `collapsed` reporting `start`, because the\ncollapse applied and `position` reads the sliver once a pane is shut. The\nreturn of the first request is what says so, and it was being dropped: a\ncancelable event dispatched as a bare statement with nothing reading the\nanswer, which is the shape the navigation cohort named on `Outline` and left.\n\nRefusing the collapse alone still leaves the resize, which is the other way\nround and is coherent: the divider goes where the drag put it and the pane\nis not declared shut. What a consumer cannot have is a pane that collapses\nout from under a position they said no to.\n\n**A gesture that moved nothing announces nothing, and this is the one place\nthat can say so.** A change carrying the position the divider already had\nrewrites a consumer's stored value from a gesture that moved nothing:\nharmless where the value round-trips exactly, and not where it does not,\nwhich is any consumer storing pixels and dividing by a box. The separator's\n`pointerup` held that as an early return of its own and was the only door\nwith one. There are five: the separator's pointer and arrows, the corner's\npointer and arrows, and a double click through `reset`, and `moveTo` is a\nsixth a consumer can open. Measured in Chromium 17 Sep 2026 on the built\nbundle, every door but the guarded one announced a move of zero: a corner\npress with nothing between announced on both splitters, `Home` on a divider\nalready at its minimum announced, and a double click on one already at its\ndefault announced.\n\n**Measured against where the gesture began, and not against `position`.**\n`move` applies as it goes, so by the time a drag settles the position is\nalready the number about to be announced, and comparing those two would\nsilence every drag there is. `began` is the press; a discrete path takes\nnone and compares against the position, which for it is the same thing.\n\n**Per divider rather than per gesture, which is the corner's question.** The\ncorner drives two at once, so \"moved nothing\" cannot mean \"neither moved\":\na drag along one axis moves one of them, and the other would be announcing\na number nobody asked to change. Each settles on its own and guards on its\nown, so the one that moved still announces while the one that did not stays\nquiet. That is also why the guard cannot live in `handleCornerUp`, which\nonly ever sees the pair.\n\n**The collapse counts as movement, because a refusal can leave the two\ndisagreeing.** A consumer who refuses `helix-before-collapse` has a pane at\nthe edge that is not declared shut, and a guard reading the position alone\nwould then never offer the collapse again: `Home` is already at the\nminimum, so every later press is a move of zero."
+              "description": "Says the arrangement has settled, so a consumer can keep it.\n\nThrough the audited path, so a consumer who owns `position` is told what was\nasked for and decides, and one who does not has already had it applied.\n\n**A refused resize ends the resize and not the gesture.** `shutAt` reads the\nposition the gesture ended on, so the collapse is computed from a number the\nconsumer may have declined, and the reading this replaces was that the two\nare therefore one decision: refuse the first and the second cannot stand.\nThat is a reasonable thing to believe about a splitter nobody else owns, and\nit takes \"no\" to mean the gesture is over. What it misses is that a consumer\nwho owns the position refuses in order to *take* the decision, not to end\nit. The sandbox two folders away refuses every `helix-before-resize` from\nthe splitter inside it, re-announces the same move in its own vocabulary and\nwrites the answer back through `position`, which is what makes it the single\ndecision point; returning on its refusal left `panel-collapsed-size` inert\nthere, the shipped `with-a-panel` example measuring a 0px panel against the\n36 it asks for. So the collapse is reached either way and is refused, or\nnot, on its own.\n\n**Which is honest because the collapse carries its own position.** A shut\npane sits at `collapsed-size`, which is where `position` reads it from once\n`collapsed` is set, and never at the number the resize named: refuse a drag\nto 100 on a splitter with `collapsed-size=\"10\"`, allow the collapse, and the\ndivider is at 90. Nothing writes the refused number either, `requestChange`\napplying nothing when it is refused and the collapse below writing the open\nposition back over whatever a drag had already drawn, so a consumer who says\nno to the position and yes to the collapse gets the pane shut and keeps the\nnumber they had to reopen to. The two coincide only where `collapsed-size`\nis zero, and the states differ even there: a shut pane knows where to open\nback to and a divider parked at the edge does not.\n\nRefusing the collapse alone still leaves the resize, which is the other way\nround and is coherent: the divider goes where the drag put it and the pane\nis not declared shut.\n\n**The open position is taken here for every door but the pointer's, which\nis the same split `began` makes and for the same reason.** A drag has\noverwritten the position on the way to the edge, so it reads it on the\npress; a key, a double click and `moveTo` apply nothing until the request\nbelow, so where the divider is at the top of this method is where it was.\nCaptured on the press alone, the class docstring's promise that a shut pane\nknows where to open back to held for a drag and for nothing else: measured\n17 Sep 2026, `Home` on a splitter resting at 60 shut the start pane and\nreopened it at 0, the resize above having written the edge and the collapse\nhaving nothing to put back. Stale, it was worse than absent, `opened` never\nbeing cleared: a press at 60, then a key collapse from 20, reopened at 60.\n\n**A gesture that moved nothing announces nothing, and this is the one place\nthat can say so.** A change carrying the position the divider already had\nrewrites a consumer's stored value from a gesture that moved nothing:\nharmless where the value round-trips exactly, and not where it does not,\nwhich is any consumer storing pixels and dividing by a box. The separator's\n`pointerup` held that as an early return of its own and was the only door\nwith one. There are five: the separator's pointer and arrows, the corner's\npointer and arrows, and a double click through `reset`, and `moveTo` is a\nsixth a consumer can open. Measured in Chromium 17 Sep 2026 on the built\nbundle, every door but the guarded one announced a move of zero: a corner\npress with nothing between announced on both splitters, `Home` on a divider\nalready at its minimum announced, and a double click on one already at its\ndefault announced.\n\n**Measured against where the gesture began, and not against `position`.**\n`move` applies as it goes, so by the time a drag settles the position is\nalready the number about to be announced, and comparing those two would\nsilence every drag there is. `began` is the press; a discrete path takes\nnone and compares against the position, which for it is the same thing.\n\n**Per divider rather than per gesture, which is the corner's question.** The\ncorner drives two at once, so \"moved nothing\" cannot mean \"neither moved\":\na drag along one axis moves one of them, and the other would be announcing\na number nobody asked to change. Each settles on its own and guards on its\nown, so the one that moved still announces while the one that did not stays\nquiet. That is also why the guard cannot live in `handleCornerUp`, which\nonly ever sees the pair.\n\n**The collapse counts as movement, because a refusal can leave the two\ndisagreeing.** A consumer who refuses `helix-before-collapse` has a pane at\nthe edge that is not declared shut, and a guard reading the position alone\nwould then never offer the collapse again: `Home` is already at the\nminimum, so every later press is a move of zero."
             },
             {
               "kind": "field",
@@ -81808,7 +81903,7 @@
               "type": {
                 "text": "HelixBeforeCollapseEvent"
               },
-              "description": "Fired before a pane shuts or reopens, and only where the position it is derived from stood. Cancelable: refusing it leaves the pane as it was and the divider where the gesture put it.",
+              "description": "Fired before a pane shuts or reopens, whether or not the resize that reached it was allowed, and carrying its own position: a shut pane sits at `collapsed-size` rather than at the number the resize named. Cancelable: refusing it leaves the pane as it was and the divider where the gesture put it.",
               "name": "helix-before-collapse",
               "reactProp": "onhelix-before-collapse"
             },
@@ -81816,7 +81911,7 @@
               "type": {
                 "text": "HelixBeforeResizeEvent"
               },
-              "description": "Fired before the divider settles, and only where the gesture moved it: a press that moved nothing, a drag that came back, an arrow with nowhere left to go and a corner that moved the other divider are all silent on this one. Cancelable: refusing it takes the whole of where the gesture ended, so no collapse follows from it either. A drag has already drawn itself by then and holds where it was dropped until the consumer assigns their own.",
+              "description": "Fired before the divider settles, and only where the gesture moved it: a press that moved nothing, a drag that came back, an arrow with nowhere left to go and a corner that moved the other divider are all silent on this one. Cancelable: refusing it takes the position and leaves the rest of the gesture, so a collapse the gesture reached is still announced and still yours to refuse. A drag has already drawn itself by then and holds where it was dropped until the consumer assigns their own.",
               "name": "helix-before-resize",
               "reactProp": "onhelix-before-resize"
             }
@@ -81926,7 +82021,7 @@
           "helix": {
             "category": "layout",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/splitter",
             "aliases": [
               "SplitPane",

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

@@ -20,7 +20,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * performs, and it is first in the tab order.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category layout
  * @aliases Slider, Gallery, Slideshow
  * @documentation https://fusion.dev/helix/components/carousel
@@ -44,8 +44,9 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @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-per-view - How many slides go across, written onto the track by the component so a sheet divides the track by the same number the positions are counted from. Read it rather than selecting on `per-view`, which cannot be enumerated without a ceiling. See `perView`.
+ * @cssproperty --carousel-per-view - How many slides go across, written onto the track by the component so a sheet divides the track by the same number the positions are counted from. Read it rather than selecting on `per-view`, which cannot be enumerated without a ceiling. Under `per-view="auto"` the component writes nothing and the sheet declares it instead, so the same name answers in both modes. See `perView`.
  * @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`.
+ * @cssproperty --carousel-slide-min - The narrowest a slide may be laid out, which is what `per-view="auto"` fits the track with. A length, since the sheet divides by it. Unset is the whole track, which is one across.
  */
 export declare class HelixHeadlessCarousel extends HelixElement {
     /**
@@ -183,14 +184,37 @@ export declare class HelixHeadlessCarousel extends HelixElement {
      * A value the track cannot honor is taken to the nearest one it can, by
      * `across`, and both tiers read that rather than this.
      *
+     * **`auto` fits as many as the track can hold**, at `--carousel-slide-min`
+     * apiece, and nothing is written onto the track: the count is the sheet's,
+     * and the sheet's alone, because it is the one number here CSS can work out
+     * for itself. Everything it takes is a length the sheet already has, so the
+     * panes are laid out at their final width by the first rule that runs, on a
+     * server's markup as on the client's, and no script is waited on. That is the
+     * whole reason a declared count was ever the only option: a carousel that
+     * asks how wide its container is can only ask on the client, so the panes go
+     * down at one width and move to another when the answer arrives. Written
+     * inline the count would outrank the sheet that computes it, which is why an
+     * `auto` track is handed nothing. A count stays for the design that calls for
+     * exactly three.
+     *
+     * The styled sheet says how it divides, and the headless `auto` example
+     * carries the same three lines for a consumer writing their own.
+     *
+     * **A value rather than the resting behavior**, which is what the
+     * responsiveness policy asks of every axis that a box decides: a splitter
+     * turns on `orientation="auto"` and a plain one does not turn at all. Fitting
+     * changes what the carousel *does*, since how many are across is how many
+     * places the track can stop, so a carousel that had not asked for it would
+     * find its position count moving with the window.
+     *
      * No default, because it reflects. A reflected property with a value writes
      * its attribute on upgrade, and the host then carries something a consumer's
      * server markup never had, which React reports as a mismatch. The one-across
      * case is the absent attribute, and the styles read it that way.
      */
-    perView?: number;
+    perView?: number | 'auto';
     /**
-     * `perView` as both tiers use it: a whole number of slides, one at least.
+     * A declared `perView` as both tiers use it: a whole number, one at least.
      *
      * **The clamp is here because the arithmetic is here**, and the two readers
      * of this number have to be given the same one. A fraction is floored, since
@@ -202,12 +226,39 @@ export declare class HelixHeadlessCarousel extends HelixElement {
      * drew no indicators at all and left `index` at `NaN`. All of them read as
      * one across, which is what a carousel with nothing sayable asked for.
      *
+     * **A vertical `auto` is one of them.** Fitting divides the room the page
+     * gave the track, and a vertical track's room is a height the consumer chose
+     * with `--carousel-block-size`: there is nothing there to fit against that
+     * they did not already decide, so the count is theirs to state. It also
+     * cannot be had cheaply, the block axis wanting `container-type: size`, which
+     * lays a track out as empty wherever its height is not definite.
+     *
      * Not clamped to the number of slides. Six across four slides is four panes
      * at a sixth of the track each and the one place to stand, which is what was
      * asked for as nearly as it can be had, and the slide count is a fact the
      * server does not have: clamping to it would draw one width there and another
      * on upgrade.
      */
+    private get clamped();
+    /** Whether the track is fitting slides to its own box rather than to a count. */
+    private get fits();
+    /**
+     * How many slides go across, and `undefined` while a fitted track is unlaid.
+     *
+     * **Undefined is the honest answer and the indicators read it as one**, which
+     * is the whole of how a fitted carousel keeps from drawing a run of dots at
+     * one length and correcting it at another. The count a fitted track goes
+     * across is whatever its box resolved to, so nothing knows it until there is
+     * a box: not the server, which has no layout, and not the render that draws
+     * the panes, layout being what follows a render rather than what precedes it.
+     * The dots wait for it, which costs them nothing, because a server serves no
+     * indicators for any carousel, `slides` being empty there.
+     *
+     * Measured 16 Sep 2026 in Chromium 151.0.7922.34 and WebKit 26.5, recording
+     * every run of dots a carousel has from the upgrade on: a fitted one goes
+     * none, then five, and never another number; a declared one goes straight to
+     * six. What a reader can see is the run missing, never the run wrong.
+     */
     private get across();
     /**
      * How many distinct views the track holds, which is what the indicators count.
@@ -216,8 +267,93 @@ export declare class HelixHeadlessCarousel extends HelixElement {
      * `n - perView + 1` times, so six slides four across is three: 0 to 3, 1 to 4,
      * 2 to 5. One at minimum, since a carousel showing everything it has still
      * has the one place to be.
+     *
+     * One across until a fitted track has been laid out, which is the same answer
+     * a carousel that has never been told anything gives, and the dots are
+     * withheld rather than counted from it. See `across`.
      */
     get positions(): number;
+    /**
+     * How many slides the box turned out to hold, from the pane it laid out.
+     *
+     * **The measurement asks what happened rather than what was asked for**, and
+     * that is why it is the pane's width and not the count in the declaration.
+     * The sheet divides the track by `--carousel-per-view`, which under `auto` is
+     * arithmetic rather than a number, and a consumer's own sheet may divide it
+     * some other way entirely or grow the panes to fill a track holding
+     * everything it has. Reading the box back gets the same answer as the
+     * declaration wherever the two agree and the true one wherever they do not,
+     * so a width and a count cannot disagree in either direction.
+     *
+     * The sheet's own arithmetic run backward, on the lengths that were actually
+     * used: a gap added to the room, divided by a pane and a gap. Rounded,
+     * because the pane a sheet lays out is a sixty-fourth off its exact share by
+     * design and the quotient lands a ten-thousandth off a whole number.
+     *
+     * Undefined where there is nothing to measure, which is a harness rather than
+     * a browser: happy-dom lays nothing out and reports zero for every box, and a
+     * count taken from zeros would be a number with no layout behind it.
+     */
+    private measure;
+    /**
+     * Takes the reading, and puts the index back inside what it leaves.
+     *
+     * **A fitted carousel's last position moves with the window**, which a
+     * declared one's never does: eight slides at one across has eight places to
+     * stand and four across has five, so a track widened while the reader sits on
+     * the last of them is a track resting somewhere it can no longer be. Through
+     * `goTo`, so the correction goes out as the same cancelable announcement
+     * every other index change does and a consumer holding `index` hears it
+     * rather than being overwritten.
+     *
+     * Only on a change, so the observer's own re-render cannot feed itself.
+     */
+    private readonly readFit;
+    /**
+     * The count handed to the styles, and nothing at all where they work it out.
+     *
+     * A declared count is this file's: it decides how many places the track can
+     * stop, so the number the panes are divided by has to be the number the
+     * positions were counted from, and writing it on the track inside the
+     * component's own shadow root is what keeps a sheet from having to enumerate
+     * the values it will answer for.
+     *
+     * A fitted one is the sheet's, and handing it anything would take it back: an
+     * inline declaration outranks every rule short of `!important`, so a track
+     * told `1` here could never be told three by the rule that fits it. The
+     * absence is not a gap either, because the rule that computes the count
+     * declares it on this same element, which beats anything a consumer inherits
+     * in exactly as the inline one did.
+     */
+    private handed;
+    /** What the box resolved to, and `undefined` until it has been laid out. */
+    private fitted;
+    /** Watches the pane a fitted track laid out, while `auto` is what was asked. */
+    private sizes;
+    /** The pane being watched, so a re-rendered run moves the watch with it. */
+    private watched;
+    /**
+     * Starts or stops watching, according to what the count was asked to be.
+     *
+     * **The pane and not the track, because both questions move it.** A narrower
+     * track divides into a narrower pane, and so does a slide arriving or leaving
+     * where the panes grow to fill a track holding everything it has. A watch on
+     * the track answers the first and sleeps through the second.
+     *
+     * **An observation is delivered after layout and inside the same rendering
+     * step**, and the update it asks for is a microtask on the end of it, so the
+     * dots are added to a frame that has not been painted. Taking the reading
+     * from `updated` instead would be the same arithmetic one Lit warning
+     * earlier, and the warning is about the right thing: a render that has to
+     * read layout is a render that has to run twice.
+     *
+     * Called from `connectedCallback`, `firstUpdated` and `updated`, so a
+     * consumer switching to `auto` after mount is watched, one switching away
+     * stops being, and a carousel moved in the DOM is watched again. Observing is
+     * what asks for the first reading, so the watch is rebuilt rather than kept
+     * across a mode change.
+     */
+    private watchPane;
     /**
      * The panes rendered for the slides, in order. Empty until the first render.
      *
@@ -254,9 +390,16 @@ export declare class HelixHeadlessCarousel extends HelixElement {
      * there, which is why both tiers can share the arithmetic below.
      *
      * Physical sides rather than logical, to match the physical `offsetLeft` and
-     * `offsetTop` it is subtracted from. The bleed is one length on all four
-     * sides, so the two agree whatever the writing mode; if that stops being
-     * true, this is the method that has to know.
+     * `offsetTop` it is subtracted from.
+     *
+     * **The side read is the side the track scrolls on, and not one side standing
+     * for four.** They are one length on a track laid out at the defaults and
+     * stop being one the moment a consumer raises `--carousel-bleed`, which the
+     * hook exists to invite: a slide on `--helix-shadow-lg` reaches 44px and is
+     * told to ask for it. So a horizontal track's room is its inline padding and
+     * a vertical one's is its block padding, and each sheet puts the bleed where
+     * the scroller clips. Reading one side for both would have a vertical track
+     * measuring a length nothing on its axis was laid out with.
      */
     private bleed;
     /**