@fusion.dev/helix-headless 0.49.1 → 0.51.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",
@@ -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"
             }
           ],
@@ -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"
@@ -19150,7 +19245,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether the control refuses changes while still submitting its value.\n\n**Enforced by refusing every request in one place**, which is the seam this\ncomponent already has: `requestValue` is what every path here comes through,\nand gating it once is what stops the next call site from being written\nwithout the check.\n\nNot `disabled`, which is the confusion worth naming: a disabled control\nsubmits nothing and leaves the tab order, and a read-only one submits its\nvalue and stays reachable, which is what a form showing a color somebody\nelse set needs.\n\n**One gate is not enough here, and the second is `move`.** This picker\nholds a model beside its value, which Date Picker and Time Picker do not:\n`moved` is the HSB the square is drawn from, and it is written before the\nvalue is requested. Gating only the request would leave the square under\nthe reader's pointer and the value where it was, which is a control that\nrefuses and looks like it accepted.",
+              "description": "Whether the control refuses changes while still submitting its value.\n\n**Enforced by refusing every request in one place**, which is the seam this\ncomponent already has: `requestValue` is what every path here comes through,\nand gating it once is what stops the next call site from being written\nwithout the check.\n\nNot `disabled`, which is the confusion worth naming: a disabled control\nsubmits nothing and leaves the tab order, and a read-only one submits its\nvalue and stays reachable, which is what a form showing a color somebody\nelse set needs.\n\n**One gate is not enough here, and the second is `move`.** This picker\nholds a model beside its value, which Date Picker and Time Picker do not:\n`moved` is the HSB the square is drawn from, and it is written before the\nvalue is requested. Gating only the request would leave the square under\nthe reader's pointer and the value where it was, which is a control that\nrefuses and looks like it accepted.\n\n**Two controls are refused whole rather than at either seam**, because\nboth do something before they ask. The syntax toggle rewrites the value, so\nletting it move would show `rgb` over a hex it is no longer allowed to\nrestate. The eyedropper clears the screen and runs a system sampler, so\nletting it open would take a color from the reader and drop it.",
               "attribute": "readonly",
               "reflects": true
             },
@@ -20198,7 +20293,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether the control refuses changes while still submitting its value.\n\n**Enforced by refusing every request in one place**, which is the seam this\ncomponent already has: `requestValue` is what every path here comes through,\nand gating it once is what stops the next call site from being written\nwithout the check.\n\nNot `disabled`, which is the confusion worth naming: a disabled control\nsubmits nothing and leaves the tab order, and a read-only one submits its\nvalue and stays reachable, which is what a form showing a color somebody\nelse set needs.\n\n**One gate is not enough here, and the second is `move`.** This picker\nholds a model beside its value, which Date Picker and Time Picker do not:\n`moved` is the HSB the square is drawn from, and it is written before the\nvalue is requested. Gating only the request would leave the square under\nthe reader's pointer and the value where it was, which is a control that\nrefuses and looks like it accepted.",
+              "description": "Whether the control refuses changes while still submitting its value.\n\n**Enforced by refusing every request in one place**, which is the seam this\ncomponent already has: `requestValue` is what every path here comes through,\nand gating it once is what stops the next call site from being written\nwithout the check.\n\nNot `disabled`, which is the confusion worth naming: a disabled control\nsubmits nothing and leaves the tab order, and a read-only one submits its\nvalue and stays reachable, which is what a form showing a color somebody\nelse set needs.\n\n**One gate is not enough here, and the second is `move`.** This picker\nholds a model beside its value, which Date Picker and Time Picker do not:\n`moved` is the HSB the square is drawn from, and it is written before the\nvalue is requested. Gating only the request would leave the square under\nthe reader's pointer and the value where it was, which is a control that\nrefuses and looks like it accepted.\n\n**Two controls are refused whole rather than at either seam**, because\nboth do something before they ask. The syntax toggle rewrites the value, so\nletting it move would show `rgb` over a hex it is no longer allowed to\nrestate. The eyedropper clears the screen and runs a system sampler, so\nletting it open would take a color from the reader and drop it.",
               "fieldName": "readOnly"
             },
             {
@@ -20285,7 +20380,7 @@
           "helix": {
             "category": "forms",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/color-picker",
             "aliases": [
               "Color",
@@ -73586,7 +73681,7 @@
           "helix": {
             "category": "forms",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/rating",
             "aliases": [
               "Stars",
@@ -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 its summary promises. So the collapse is reached either way and is\nrefused, or not, 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**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"
             }
@@ -95151,7 +95246,7 @@
           "helix": {
             "category": "forms",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/time-picker",
             "aliases": [
               "Time",

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

@@ -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.
      *

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

@@ -9,6 +9,15 @@ import { caretLeft, caretRight, play, stop } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+const COUNT_OR_AUTO = {
+    fromAttribute: (value) => {
+        if (value === null) {
+            return undefined;
+        }
+        return value === 'auto' ? 'auto' : Number(value);
+    },
+    toAttribute: (value) => value === undefined ? null : String(value),
+};
 let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
     constructor() {
         super(...arguments);
@@ -20,6 +29,16 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         this.label = 'Carousel';
         this.loop = false;
         this.rotating = false;
+        this.readFit = () => {
+            const fitted = this.measure();
+            if (fitted === undefined || fitted === this.fitted) {
+                return;
+            }
+            this.fitted = fitted;
+            if (this.index > this.positions - 1) {
+                this.goTo(this.positions - 1);
+            }
+        };
         this.handleIndicatorKeydown = (event) => {
             const step = inlineStep(this, event.key);
             if (step === 0) {
@@ -95,12 +114,55 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         this.indexState = next;
         this.requestUpdate('index', previous);
     }
-    get across() {
+    get clamped() {
         const asked = this.perView ?? 1;
-        return Number.isFinite(asked) ? Math.max(1, Math.floor(asked)) : 1;
+        return typeof asked === 'number' && Number.isFinite(asked) ? Math.max(1, Math.floor(asked)) : 1;
+    }
+    get fits() {
+        return this.perView === 'auto' && this.orientation !== 'vertical';
+    }
+    get across() {
+        return this.fits ? this.fitted : this.clamped;
     }
     get positions() {
-        return Math.max(1, this.slides.length - this.across + 1);
+        return Math.max(1, this.slides.length - (this.across ?? 1) + 1);
+    }
+    measure() {
+        const track = this.partNamed('track');
+        const pane = this.panes[0]?.getBoundingClientRect().width;
+        if (!track || pane === undefined) {
+            return undefined;
+        }
+        const asked = Number.parseFloat(getComputedStyle(track).columnGap);
+        const gap = Number.isNaN(asked) ? 0 : asked;
+        const room = track.clientWidth - 2 * this.bleed(track);
+        if (pane <= 0 || room <= 0) {
+            return undefined;
+        }
+        return Math.max(1, Math.round((room + gap) / (pane + gap)));
+    }
+    handed() {
+        return this.fits ? nothing : `--carousel-per-view: ${this.clamped}`;
+    }
+    watchPane() {
+        if (!this.fits || typeof ResizeObserver === 'undefined') {
+            this.sizes?.disconnect();
+            this.sizes = undefined;
+            this.watched = undefined;
+            return;
+        }
+        this.sizes ??= new ResizeObserver(this.readFit);
+        const pane = this.panes[0];
+        if (pane === this.watched) {
+            return;
+        }
+        if (this.watched) {
+            this.sizes.unobserve(this.watched);
+        }
+        this.watched = pane;
+        if (pane) {
+            this.sizes.observe(pane);
+        }
     }
     get panes() {
         return [...(this.renderRoot?.querySelectorAll?.('[part="slide"]') ?? [])];
@@ -196,6 +258,7 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         this.addEventListener('pointerenter', this.pause);
         this.watcher = new MutationObserver(() => this.requestUpdate());
         this.watcher.observe(this, { childList: true });
+        this.watchPane();
     }
     disconnectedCallback() {
         super.disconnectedCallback();
@@ -207,6 +270,9 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         this.removeEventListener('pointerenter', this.pause);
         this.watcher?.disconnect();
         this.watcher = undefined;
+        this.sizes?.disconnect();
+        this.sizes = undefined;
+        this.watched = undefined;
         clearInterval(this.timer);
         this.timer = undefined;
     }
@@ -218,11 +284,15 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         if (changed.has('index')) {
             this.showing = undefined;
         }
+        if (changed.has('perView')) {
+            this.fitted = undefined;
+        }
         hostAria(this.internals, { label: this.label, role: 'group' });
         this.internals.ariaRoleDescription = 'carousel';
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
+        this.watchPane();
         this.finishHydration();
     }
     updated(changed) {
@@ -237,6 +307,7 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         if (count > 0 && this.index > count - 1) {
             this.goTo(count - 1);
         }
+        this.watchPane();
         this.assign();
     }
     assign() {
@@ -308,7 +379,7 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
       <div
         data-scroller
         part="track"
-        style=${`--carousel-per-view: ${this.across}`}
+        style=${this.handed()}
         @scroll=${this.handleTrackScroll}
         @scrollend=${this.handleScroll}
         @pointerdown=${this.handleTake}
@@ -328,7 +399,7 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
             ></slot>
           </div>`)}
       </div>
-      ${this.slides.length > 1
+      ${this.slides.length > 1 && this.across !== undefined
             ? html `<div part="indicators" role="group" aria-label=${`${this.label} slides`}>
               ${''}
               ${Array.from({ length: this.positions }).map((_place, at) => {
@@ -376,8 +447,11 @@ __decorate([
     state()
 ], HelixHeadlessCarousel.prototype, "rotating", void 0);
 __decorate([
-    property({ attribute: 'per-view', reflect: true, type: Number })
+    property({ attribute: 'per-view', converter: COUNT_OR_AUTO, reflect: true })
 ], HelixHeadlessCarousel.prototype, "perView", void 0);
+__decorate([
+    state()
+], HelixHeadlessCarousel.prototype, "fitted", void 0);
 __decorate([
     state()
 ], HelixHeadlessCarousel.prototype, "showing", void 0);