@fusion.dev/helix 0.59.4 → 0.60.1

package/custom-elements.json

@@ -13284,7 +13284,7 @@
               "type": {
                 "text": "'start' | 'end' | 'top' | 'bottom' | 'overlay' | undefined"
               },
-              "description": "Which side of the slides the arrows sit on.\n\nThe same four sides as `indicatorPlacement` and the same default, so a\ncarousel that moves only one of them keeps the other where it was. `start`\nor `end` stacks the arrows into a column, which is what a vertical track\nusually wants.\n\n`overlay` puts them on the slides, at the track's own edges, which is what a\nfull-bleed carousel wants: the slide is the page and the controls are on it\nrather than in a bar beneath it. It carries its own treatment with it, a\nsurface and a shadow under each arrow, because a glyph drawn straight onto a\nphotograph is legible against about half of one.\n\n**It is a value here rather than an axis of its own.** \"The controls are\nover the content\" is the whole of what a `hero` appearance would say, and\nthe surface, the edge-to-edge arrows and the bar that catches no presses all\nfollow from it. These two placements are the whole of where a carousel's\nchrome can go.",
+              "description": "Which side of the slides the arrows sit on.\n\nThe same five places as `indicatorPlacement` and the same default, so a\ncarousel that moves only one of them keeps the other where it was. `start`\nor `end` stacks the arrows into a column, which is what a vertical track\nusually wants.\n\n`overlay` puts them on the slides, at the track's own edges, which is what a\nfull-bleed carousel wants: the slide is the page and the controls are on it\nrather than in a bar beneath it. It carries its own treatment with it, a\nsurface and a shadow under each arrow, because a glyph drawn straight onto a\nphotograph is legible against about half of one.\n\n**It is a value here rather than an axis of its own.** \"The controls are\nover the content\" is the whole of what a `hero` appearance would say, and\nthe surface, the edge-to-edge arrows and the bar that catches no presses all\nfollow from it. The four edges and the slides are the whole of where a\ncarousel's chrome can go, and `indicatorPlacement` names the same five: the\ndots were short of this one until #389, which is how a hero ended up with\nits arrows on the picture and its dots in a band below.",
               "attribute": "controls-placement",
               "reflects": true
             },
@@ -13302,9 +13302,9 @@
               "kind": "field",
               "name": "indicatorPlacement",
               "type": {
-                "text": "'start' | 'end' | 'top' | 'bottom' | undefined"
+                "text": "'start' | 'end' | 'top' | 'bottom' | 'overlay' | undefined"
               },
-              "description": "Which side of the slides the dots sit on.\n\nUnset is `bottom`, under them. `top` puts them above, `start` and `end`\nbeside, where a run of dots becomes a column.\n\n**The sides of the content, not positions along a bar.** `start` and `end`\nare the logical ones and they are logical because that axis flips: a\ncarousel with its dots at the start should put them on the right in Arabic\nwithout being told. `top` and `bottom` are the block edges, which flip in\nno writing mode this library draws for, so the plain word is the honest one\nand `block-start` would be jargon standing in for it.\n\n**`Drawer` and `Toast` say it in exactly these four words**, and one\nvocabulary across the three is worth more than each family's own: a\nconsumer who has placed a drawer knows where a carousel's dots go.\n\nIndependent of `controlsPlacement`. Both default to the bottom, where they\nshare the row and split it, dots to the start and arrows to the end,\narrived at by two defaults rather than by a rule about the pair, so moving\none leaves the other alone.",
+              "description": "Which side of the slides the dots sit on.\n\nUnset is `bottom`, under them. `top` puts them above, `start` and `end`\nbeside, where a run of dots becomes a column.\n\n**The sides of the content, not positions along a bar.** `start` and `end`\nare the logical ones and they are logical because that axis flips: a\ncarousel with its dots at the start should put them on the right in Arabic\nwithout being told. `top` and `bottom` are the block edges, which flip in\nno writing mode this library draws for, so the plain word is the honest one\nand `block-start` would be jargon standing in for it.\n\n**`Drawer` and `Toast` say it in exactly these four words**, and one\nvocabulary across the three is worth more than each family's own: a\nconsumer who has placed a drawer knows where a carousel's dots go.\n\n**`overlay` is the fifth place, and it is the slides themselves**, which is\nwhere a run of dots belongs on a full-bleed carousel: the picture is the\npage and the chrome is on it rather than in a band beneath it. The arrows\nhave always had this and the dots did not, so a hero carousel put its\ncontrols over the picture and left its dots stranded in a bar under it,\nwhich is the one arrangement nobody designs on purpose.\n\n**The run takes a surface, where the arrows take one each.** Over a\nphotograph a gray dot and a primary one are both legible against about half\nof it, which is the reason the arrows already carry a ground and a shadow.\nOne ground under the whole run rather than one per dot, because the dots are\na single object with gaps too small to be edges, where the arrows are two\ntargets at opposite ends of the picture with the slide showing between them.\nInside it the dots keep the colors they have everywhere else, so what a\nreader learned from a carousel in a card still reads on one over a picture.\n\n**`indicatorAlign` still says where along the edge**, unchanged, because\nthis placement puts the run on the block-end edge like the other four.\n`controlsPlacement`'s own `overlay` reinterprets its alignment, that bar\nbeing stretched across the middle of the picture rather than sitting on an\nedge, and the two differ for that reason rather than by oversight.\n\nIndependent of `controlsPlacement`. Both default to the bottom, where they\nshare the row and split it, dots to the start and arrows to the end,\narrived at by two defaults rather than by a rule about the pair, so moving\none leaves the other alone.",
               "attribute": "indicator-placement",
               "reflects": true
             },
@@ -14326,7 +14326,7 @@
               "type": {
                 "text": "'start' | 'end' | 'top' | 'bottom' | 'overlay' | undefined"
               },
-              "description": "Which side of the slides the arrows sit on.\n\nThe same four sides as `indicatorPlacement` and the same default, so a\ncarousel that moves only one of them keeps the other where it was. `start`\nor `end` stacks the arrows into a column, which is what a vertical track\nusually wants.\n\n`overlay` puts them on the slides, at the track's own edges, which is what a\nfull-bleed carousel wants: the slide is the page and the controls are on it\nrather than in a bar beneath it. It carries its own treatment with it, a\nsurface and a shadow under each arrow, because a glyph drawn straight onto a\nphotograph is legible against about half of one.\n\n**It is a value here rather than an axis of its own.** \"The controls are\nover the content\" is the whole of what a `hero` appearance would say, and\nthe surface, the edge-to-edge arrows and the bar that catches no presses all\nfollow from it. These two placements are the whole of where a carousel's\nchrome can go.",
+              "description": "Which side of the slides the arrows sit on.\n\nThe same five places as `indicatorPlacement` and the same default, so a\ncarousel that moves only one of them keeps the other where it was. `start`\nor `end` stacks the arrows into a column, which is what a vertical track\nusually wants.\n\n`overlay` puts them on the slides, at the track's own edges, which is what a\nfull-bleed carousel wants: the slide is the page and the controls are on it\nrather than in a bar beneath it. It carries its own treatment with it, a\nsurface and a shadow under each arrow, because a glyph drawn straight onto a\nphotograph is legible against about half of one.\n\n**It is a value here rather than an axis of its own.** \"The controls are\nover the content\" is the whole of what a `hero` appearance would say, and\nthe surface, the edge-to-edge arrows and the bar that catches no presses all\nfollow from it. The four edges and the slides are the whole of where a\ncarousel's chrome can go, and `indicatorPlacement` names the same five: the\ndots were short of this one until #389, which is how a hero ended up with\nits arrows on the picture and its dots in a band below.",
               "fieldName": "controlsPlacement"
             },
             {
@@ -14340,9 +14340,9 @@
             {
               "name": "indicator-placement",
               "type": {
-                "text": "'start' | 'end' | 'top' | 'bottom' | undefined"
+                "text": "'start' | 'end' | 'top' | 'bottom' | 'overlay' | undefined"
               },
-              "description": "Which side of the slides the dots sit on.\n\nUnset is `bottom`, under them. `top` puts them above, `start` and `end`\nbeside, where a run of dots becomes a column.\n\n**The sides of the content, not positions along a bar.** `start` and `end`\nare the logical ones and they are logical because that axis flips: a\ncarousel with its dots at the start should put them on the right in Arabic\nwithout being told. `top` and `bottom` are the block edges, which flip in\nno writing mode this library draws for, so the plain word is the honest one\nand `block-start` would be jargon standing in for it.\n\n**`Drawer` and `Toast` say it in exactly these four words**, and one\nvocabulary across the three is worth more than each family's own: a\nconsumer who has placed a drawer knows where a carousel's dots go.\n\nIndependent of `controlsPlacement`. Both default to the bottom, where they\nshare the row and split it, dots to the start and arrows to the end,\narrived at by two defaults rather than by a rule about the pair, so moving\none leaves the other alone.",
+              "description": "Which side of the slides the dots sit on.\n\nUnset is `bottom`, under them. `top` puts them above, `start` and `end`\nbeside, where a run of dots becomes a column.\n\n**The sides of the content, not positions along a bar.** `start` and `end`\nare the logical ones and they are logical because that axis flips: a\ncarousel with its dots at the start should put them on the right in Arabic\nwithout being told. `top` and `bottom` are the block edges, which flip in\nno writing mode this library draws for, so the plain word is the honest one\nand `block-start` would be jargon standing in for it.\n\n**`Drawer` and `Toast` say it in exactly these four words**, and one\nvocabulary across the three is worth more than each family's own: a\nconsumer who has placed a drawer knows where a carousel's dots go.\n\n**`overlay` is the fifth place, and it is the slides themselves**, which is\nwhere a run of dots belongs on a full-bleed carousel: the picture is the\npage and the chrome is on it rather than in a band beneath it. The arrows\nhave always had this and the dots did not, so a hero carousel put its\ncontrols over the picture and left its dots stranded in a bar under it,\nwhich is the one arrangement nobody designs on purpose.\n\n**The run takes a surface, where the arrows take one each.** Over a\nphotograph a gray dot and a primary one are both legible against about half\nof it, which is the reason the arrows already carry a ground and a shadow.\nOne ground under the whole run rather than one per dot, because the dots are\na single object with gaps too small to be edges, where the arrows are two\ntargets at opposite ends of the picture with the slide showing between them.\nInside it the dots keep the colors they have everywhere else, so what a\nreader learned from a carousel in a card still reads on one over a picture.\n\n**`indicatorAlign` still says where along the edge**, unchanged, because\nthis placement puts the run on the block-end edge like the other four.\n`controlsPlacement`'s own `overlay` reinterprets its alignment, that bar\nbeing stretched across the middle of the picture rather than sitting on an\nedge, and the two differ for that reason rather than by oversight.\n\nIndependent of `controlsPlacement`. Both default to the bottom, where they\nshare the row and split it, dots to the start and arrows to the end,\narrived at by two defaults rather than by a rule about the pair, so moving\none leaves the other alone.",
               "fieldName": "indicatorPlacement"
             },
             {
@@ -14495,7 +14495,7 @@
                 "slug": "events"
               },
               {
-                "description": "Full-bleed slides with the controls over the picture.",
+                "description": "Full-bleed slides with the chrome over the picture.",
                 "slug": "hero"
               },
               {
@@ -80373,11 +80373,8 @@
         {
           "kind": "variable",
           "name": "ORB_STATES",
-          "type": {
-            "text": "[\n  'waiting',\n  'connecting',\n  'thinking',\n  'fetching',\n  'listening',\n  'working',\n  'done',\n]"
-          },
-          "default": "[ 'waiting', 'connecting', 'thinking', 'fetching', 'listening', 'working', 'done', ]",
-          "description": "The states an orb can be in, in the order a task tends to pass through them.\n\nExported so the component can validate an attribute against the same list the\ngenerator reads, rather than keeping a second copy that drifts."
+          "default": "Object.keys(ORDER)",
+          "description": "The same states as a list, in that order.\n\nExported so the component can validate an attribute against one list rather\nthan a second copy that drifts. String keys come back in insertion order,\nwhich the object above is written in."
         },
         {
           "kind": "variable",

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

@@ -89,6 +89,10 @@ padding-inline: var(--helix-space-none);
 --_carousel-controls-along: center;
 }
 
+:host([indicator-placement="overlay"]) [part="indicators"] {
+--_carousel-indicators-along: center;
+}
+
 :host([indicator-align="start"]) [part="indicators"] {
 --_carousel-indicators-along: start;
 }
@@ -308,6 +312,29 @@ box-shadow: var(--helix-shadow-md);
 pointer-events: auto;
 }
 
+:host([indicator-placement="overlay"]) [part="indicators"] {
+align-self: end;
+grid-area: 2 / 2;
+z-index: var(--helix-layer-raised);
+}
+
+:host([indicator-placement="overlay"]) [part="indicators"] {
+background-color: var(--helix-color-surface-overlay);
+border-radius: var(--helix-radii-full);
+box-shadow: var(--helix-shadow-md);
+margin-block-end: calc(var(--_carousel-bleed) + var(--helix-space-md));
+padding-block: var(--helix-space-2xs);
+padding-inline: var(--helix-space-xs);
+}
+
+:host([indicator-placement="overlay"]) [part~="indicator"] {
+background-color: var(--helix-color-foreground-muted);
+}
+
+:host([indicator-placement="overlay"]) [part~="indicator"][data-current] {
+background-color: var(--helix-color-primary);
+}
+
 :host([controls-placement="overlay"]) [part="next"] {
 margin-inline-start: auto;
 }

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

@@ -39,7 +39,7 @@ export declare class HelixCarousel extends HelixHeadlessCarousel {
     /**
      * Which side of the slides the arrows sit on.
      *
-     * The same four sides as `indicatorPlacement` and the same default, so a
+     * The same five places as `indicatorPlacement` and the same default, so a
      * carousel that moves only one of them keeps the other where it was. `start`
      * or `end` stacks the arrows into a column, which is what a vertical track
      * usually wants.
@@ -53,8 +53,10 @@ export declare class HelixCarousel extends HelixHeadlessCarousel {
      * **It is a value here rather than an axis of its own.** "The controls are
      * over the content" is the whole of what a `hero` appearance would say, and
      * the surface, the edge-to-edge arrows and the bar that catches no presses all
-     * follow from it. These two placements are the whole of where a carousel's
-     * chrome can go.
+     * follow from it. The four edges and the slides are the whole of where a
+     * carousel's chrome can go, and `indicatorPlacement` names the same five: the
+     * dots were short of this one until #389, which is how a hero ended up with
+     * its arrows on the picture and its dots in a band below.
      */
     controlsPlacement?: 'start' | 'end' | 'top' | 'bottom' | 'overlay';
     /**
@@ -101,12 +103,34 @@ export declare class HelixCarousel extends HelixHeadlessCarousel {
      * vocabulary across the three is worth more than each family's own: a
      * consumer who has placed a drawer knows where a carousel's dots go.
      *
+     * **`overlay` is the fifth place, and it is the slides themselves**, which is
+     * where a run of dots belongs on a full-bleed carousel: the picture is the
+     * page and the chrome is on it rather than in a band beneath it. The arrows
+     * have always had this and the dots did not, so a hero carousel put its
+     * controls over the picture and left its dots stranded in a bar under it,
+     * which is the one arrangement nobody designs on purpose.
+     *
+     * **The run takes a surface, where the arrows take one each.** Over a
+     * photograph a gray dot and a primary one are both legible against about half
+     * of it, which is the reason the arrows already carry a ground and a shadow.
+     * One ground under the whole run rather than one per dot, because the dots are
+     * a single object with gaps too small to be edges, where the arrows are two
+     * targets at opposite ends of the picture with the slide showing between them.
+     * Inside it the dots keep the colors they have everywhere else, so what a
+     * reader learned from a carousel in a card still reads on one over a picture.
+     *
+     * **`indicatorAlign` still says where along the edge**, unchanged, because
+     * this placement puts the run on the block-end edge like the other four.
+     * `controlsPlacement`'s own `overlay` reinterprets its alignment, that bar
+     * being stretched across the middle of the picture rather than sitting on an
+     * edge, and the two differ for that reason rather than by oversight.
+     *
      * Independent of `controlsPlacement`. Both default to the bottom, where they
      * share the row and split it, dots to the start and arrows to the end,
      * arrived at by two defaults rather than by a rule about the pair, so moving
      * one leaves the other alone.
      */
-    indicatorPlacement?: 'start' | 'end' | 'top' | 'bottom';
+    indicatorPlacement?: 'start' | 'end' | 'top' | 'bottom' | 'overlay';
     static styles: CSSResultGroup;
 }
 declare global {

package/dist/orb/shapes.d.ts

@@ -1,12 +1,23 @@
 /**
- * The states an orb can be in, in the order a task tends to pass through them.
+ * What the agent is doing.
  *
- * Exported so the component can validate an attribute against the same list the
- * generator reads, rather than keeping a second copy that drifts.
+ * **Written out rather than derived from the array below**, which is the other
+ * way round from where this started. The manifest records a property's type as
+ * the text somebody wrote, so `(typeof ORB_STATES)[number]` reached it as a name
+ * with no values in it and the reference page listed none: a reader was told the
+ * attribute takes an `OrbState` and left to find out what one is. A union on one
+ * line is what every reader of this repository's sources can resolve, the `axes`
+ * rule included, and no type system is needed to do it.
  */
-export declare const ORB_STATES: readonly ['waiting', 'connecting', 'thinking', 'fetching', 'listening', 'working', 'done'];
-/** What the agent is doing. */
-export type OrbState = (typeof ORB_STATES)[number];
+export type OrbState = 'waiting' | 'connecting' | 'thinking' | 'fetching' | 'listening' | 'working' | 'done';
+/**
+ * The same states as a list, in that order.
+ *
+ * Exported so the component can validate an attribute against one list rather
+ * than a second copy that drifts. String keys come back in insertion order,
+ * which the object above is written in.
+ */
+export declare const ORB_STATES: readonly OrbState[];
 /**
  * The numbers one state is made of.
  *

package/dist/orb/shapes.js

@@ -1,12 +1,13 @@
-export const ORB_STATES = [
-    'waiting',
-    'connecting',
-    'thinking',
-    'fetching',
-    'listening',
-    'working',
-    'done',
-];
+const ORDER = {
+    connecting: 1,
+    done: 6,
+    fetching: 3,
+    listening: 4,
+    thinking: 2,
+    waiting: 0,
+    working: 5,
+};
+export const ORB_STATES = Object.keys(ORDER);
 export const ORB_PARAMS = {
     connecting: {
         belt: 0.32,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix",
   "description": "Styled component tier. Extends the headless tier with token-driven presentation.",
-  "version": "0.59.4",
+  "version": "0.60.1",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -47,14 +47,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.59.4",
-    "@fusion.dev/helix-headless": "0.59.4",
-    "@fusion.dev/helix-styles": "0.59.4"
+    "@fusion.dev/helix-core": "0.60.1",
+    "@fusion.dev/helix-headless": "0.60.1",
+    "@fusion.dev/helix-styles": "0.60.1"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.59.4",
-    "@fusion.dev/helix-testing": "0.59.4",
+    "@fusion.dev/helix-cem": "0.60.1",
+    "@fusion.dev/helix-testing": "0.60.1",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",

package/types/jsx.d.ts

@@ -2655,7 +2655,7 @@ where an arrow over a photograph belongs. */
   controlsAlign?: (HelixCarousel["controlsAlign"]) | undefined;
   /** Which side of the slides the arrows sit on.
 
-The same four sides as `indicatorPlacement` and the same default, so a
+The same five places as `indicatorPlacement` and the same default, so a
 carousel that moves only one of them keeps the other where it was. `start`
 or `end` stacks the arrows into a column, which is what a vertical track
 usually wants.
@@ -2669,12 +2669,14 @@ photograph is legible against about half of one.
 **It is a value here rather than an axis of its own.** "The controls are
 over the content" is the whole of what a `hero` appearance would say, and
 the surface, the edge-to-edge arrows and the bar that catches no presses all
-follow from it. These two placements are the whole of where a carousel's
-chrome can go. */
+follow from it. The four edges and the slides are the whole of where a
+carousel's chrome can go, and `indicatorPlacement` names the same five: the
+dots were short of this one until #389, which is how a hero ended up with
+its arrows on the picture and its dots in a band below. */
   "controls-placement"?: (HelixCarousel["controlsPlacement"]) | undefined;
   /** Which side of the slides the arrows sit on.
 
-The same four sides as `indicatorPlacement` and the same default, so a
+The same five places as `indicatorPlacement` and the same default, so a
 carousel that moves only one of them keeps the other where it was. `start`
 or `end` stacks the arrows into a column, which is what a vertical track
 usually wants.
@@ -2688,8 +2690,10 @@ photograph is legible against about half of one.
 **It is a value here rather than an axis of its own.** "The controls are
 over the content" is the whole of what a `hero` appearance would say, and
 the surface, the edge-to-edge arrows and the bar that catches no presses all
-follow from it. These two placements are the whole of where a carousel's
-chrome can go. */
+follow from it. The four edges and the slides are the whole of where a
+carousel's chrome can go, and `indicatorPlacement` names the same five: the
+dots were short of this one until #389, which is how a hero ended up with
+its arrows on the picture and its dots in a band below. */
   controlsPlacement?: (HelixCarousel["controlsPlacement"]) | undefined;
   /** Where along that side the dots sit.
 
@@ -2757,6 +2761,28 @@ and `block-start` would be jargon standing in for it.
 vocabulary across the three is worth more than each family's own: a
 consumer who has placed a drawer knows where a carousel's dots go.
 
+**`overlay` is the fifth place, and it is the slides themselves**, which is
+where a run of dots belongs on a full-bleed carousel: the picture is the
+page and the chrome is on it rather than in a band beneath it. The arrows
+have always had this and the dots did not, so a hero carousel put its
+controls over the picture and left its dots stranded in a bar under it,
+which is the one arrangement nobody designs on purpose.
+
+**The run takes a surface, where the arrows take one each.** Over a
+photograph a gray dot and a primary one are both legible against about half
+of it, which is the reason the arrows already carry a ground and a shadow.
+One ground under the whole run rather than one per dot, because the dots are
+a single object with gaps too small to be edges, where the arrows are two
+targets at opposite ends of the picture with the slide showing between them.
+Inside it the dots keep the colors they have everywhere else, so what a
+reader learned from a carousel in a card still reads on one over a picture.
+
+**`indicatorAlign` still says where along the edge**, unchanged, because
+this placement puts the run on the block-end edge like the other four.
+`controlsPlacement`'s own `overlay` reinterprets its alignment, that bar
+being stretched across the middle of the picture rather than sitting on an
+edge, and the two differ for that reason rather than by oversight.
+
 Independent of `controlsPlacement`. Both default to the bottom, where they
 share the row and split it, dots to the start and arrows to the end,
 arrived at by two defaults rather than by a rule about the pair, so moving
@@ -2778,6 +2804,28 @@ and `block-start` would be jargon standing in for it.
 vocabulary across the three is worth more than each family's own: a
 consumer who has placed a drawer knows where a carousel's dots go.
 
+**`overlay` is the fifth place, and it is the slides themselves**, which is
+where a run of dots belongs on a full-bleed carousel: the picture is the
+page and the chrome is on it rather than in a band beneath it. The arrows
+have always had this and the dots did not, so a hero carousel put its
+controls over the picture and left its dots stranded in a bar under it,
+which is the one arrangement nobody designs on purpose.
+
+**The run takes a surface, where the arrows take one each.** Over a
+photograph a gray dot and a primary one are both legible against about half
+of it, which is the reason the arrows already carry a ground and a shadow.
+One ground under the whole run rather than one per dot, because the dots are
+a single object with gaps too small to be edges, where the arrows are two
+targets at opposite ends of the picture with the slide showing between them.
+Inside it the dots keep the colors they have everywhere else, so what a
+reader learned from a carousel in a card still reads on one over a picture.
+
+**`indicatorAlign` still says where along the edge**, unchanged, because
+this placement puts the run on the block-end edge like the other four.
+`controlsPlacement`'s own `overlay` reinterprets its alignment, that bar
+being stretched across the middle of the picture rather than sitting on an
+edge, and the two differ for that reason rather than by oversight.
+
 Independent of `controlsPlacement`. Both default to the bottom, where they
 share the row and split it, dots to the start and arrows to the end,
 arrived at by two defaults rather than by a rule about the pair, so moving
@@ -2987,7 +3035,7 @@ where an arrow over a photograph belongs. */
   "prop:controlsAlign"?: (HelixCarousel["controlsAlign"]) | undefined;
   /** Which side of the slides the arrows sit on.
 
-The same four sides as `indicatorPlacement` and the same default, so a
+The same five places as `indicatorPlacement` and the same default, so a
 carousel that moves only one of them keeps the other where it was. `start`
 or `end` stacks the arrows into a column, which is what a vertical track
 usually wants.
@@ -3001,12 +3049,14 @@ photograph is legible against about half of one.
 **It is a value here rather than an axis of its own.** "The controls are
 over the content" is the whole of what a `hero` appearance would say, and
 the surface, the edge-to-edge arrows and the bar that catches no presses all
-follow from it. These two placements are the whole of where a carousel's
-chrome can go. */
+follow from it. The four edges and the slides are the whole of where a
+carousel's chrome can go, and `indicatorPlacement` names the same five: the
+dots were short of this one until #389, which is how a hero ended up with
+its arrows on the picture and its dots in a band below. */
   "attr:controls-placement"?: (HelixCarousel["controlsPlacement"]) | undefined;
   /** Which side of the slides the arrows sit on.
 
-The same four sides as `indicatorPlacement` and the same default, so a
+The same five places as `indicatorPlacement` and the same default, so a
 carousel that moves only one of them keeps the other where it was. `start`
 or `end` stacks the arrows into a column, which is what a vertical track
 usually wants.
@@ -3020,8 +3070,10 @@ photograph is legible against about half of one.
 **It is a value here rather than an axis of its own.** "The controls are
 over the content" is the whole of what a `hero` appearance would say, and
 the surface, the edge-to-edge arrows and the bar that catches no presses all
-follow from it. These two placements are the whole of where a carousel's
-chrome can go. */
+follow from it. The four edges and the slides are the whole of where a
+carousel's chrome can go, and `indicatorPlacement` names the same five: the
+dots were short of this one until #389, which is how a hero ended up with
+its arrows on the picture and its dots in a band below. */
   "prop:controlsPlacement"?: (HelixCarousel["controlsPlacement"]) | undefined;
   /** Where along that side the dots sit.
 
@@ -3089,6 +3141,28 @@ and `block-start` would be jargon standing in for it.
 vocabulary across the three is worth more than each family's own: a
 consumer who has placed a drawer knows where a carousel's dots go.
 
+**`overlay` is the fifth place, and it is the slides themselves**, which is
+where a run of dots belongs on a full-bleed carousel: the picture is the
+page and the chrome is on it rather than in a band beneath it. The arrows
+have always had this and the dots did not, so a hero carousel put its
+controls over the picture and left its dots stranded in a bar under it,
+which is the one arrangement nobody designs on purpose.
+
+**The run takes a surface, where the arrows take one each.** Over a
+photograph a gray dot and a primary one are both legible against about half
+of it, which is the reason the arrows already carry a ground and a shadow.
+One ground under the whole run rather than one per dot, because the dots are
+a single object with gaps too small to be edges, where the arrows are two
+targets at opposite ends of the picture with the slide showing between them.
+Inside it the dots keep the colors they have everywhere else, so what a
+reader learned from a carousel in a card still reads on one over a picture.
+
+**`indicatorAlign` still says where along the edge**, unchanged, because
+this placement puts the run on the block-end edge like the other four.
+`controlsPlacement`'s own `overlay` reinterprets its alignment, that bar
+being stretched across the middle of the picture rather than sitting on an
+edge, and the two differ for that reason rather than by oversight.
+
 Independent of `controlsPlacement`. Both default to the bottom, where they
 share the row and split it, dots to the start and arrows to the end,
 arrived at by two defaults rather than by a rule about the pair, so moving
@@ -3110,6 +3184,28 @@ and `block-start` would be jargon standing in for it.
 vocabulary across the three is worth more than each family's own: a
 consumer who has placed a drawer knows where a carousel's dots go.
 
+**`overlay` is the fifth place, and it is the slides themselves**, which is
+where a run of dots belongs on a full-bleed carousel: the picture is the
+page and the chrome is on it rather than in a band beneath it. The arrows
+have always had this and the dots did not, so a hero carousel put its
+controls over the picture and left its dots stranded in a bar under it,
+which is the one arrangement nobody designs on purpose.
+
+**The run takes a surface, where the arrows take one each.** Over a
+photograph a gray dot and a primary one are both legible against about half
+of it, which is the reason the arrows already carry a ground and a shadow.
+One ground under the whole run rather than one per dot, because the dots are
+a single object with gaps too small to be edges, where the arrows are two
+targets at opposite ends of the picture with the slide showing between them.
+Inside it the dots keep the colors they have everywhere else, so what a
+reader learned from a carousel in a card still reads on one over a picture.
+
+**`indicatorAlign` still says where along the edge**, unchanged, because
+this placement puts the run on the block-end edge like the other four.
+`controlsPlacement`'s own `overlay` reinterprets its alignment, that bar
+being stretched across the middle of the picture rather than sitting on an
+edge, and the two differ for that reason rather than by oversight.
+
 Independent of `controlsPlacement`. Both default to the bottom, where they
 share the row and split it, dots to the start and arrows to the end,
 arrived at by two defaults rather than by a rule about the pair, so moving
@@ -23564,7 +23660,7 @@ export type CustomElements = {
    * where an arrow over a photograph belongs.
    * - `controls-placement`/`controlsPlacement`: Which side of the slides the arrows sit on.
    *
-   * The same four sides as `indicatorPlacement` and the same default, so a
+   * The same five places as `indicatorPlacement` and the same default, so a
    * carousel that moves only one of them keeps the other where it was. `start`
    * or `end` stacks the arrows into a column, which is what a vertical track
    * usually wants.
@@ -23578,8 +23674,10 @@ export type CustomElements = {
    * **It is a value here rather than an axis of its own.** "The controls are
    * over the content" is the whole of what a `hero` appearance would say, and
    * the surface, the edge-to-edge arrows and the bar that catches no presses all
-   * follow from it. These two placements are the whole of where a carousel's
-   * chrome can go.
+   * follow from it. The four edges and the slides are the whole of where a
+   * carousel's chrome can go, and `indicatorPlacement` names the same five: the
+   * dots were short of this one until #389, which is how a hero ended up with
+   * its arrows on the picture and its dots in a band below.
    * - `indicator-align`/`indicatorAlign`: Where along that side the dots sit.
    *
    * The second half of the answer to "where do they go". `indicatorPlacement`
@@ -23620,6 +23718,28 @@ export type CustomElements = {
    * vocabulary across the three is worth more than each family's own: a
    * consumer who has placed a drawer knows where a carousel's dots go.
    *
+   * **`overlay` is the fifth place, and it is the slides themselves**, which is
+   * where a run of dots belongs on a full-bleed carousel: the picture is the
+   * page and the chrome is on it rather than in a band beneath it. The arrows
+   * have always had this and the dots did not, so a hero carousel put its
+   * controls over the picture and left its dots stranded in a bar under it,
+   * which is the one arrangement nobody designs on purpose.
+   *
+   * **The run takes a surface, where the arrows take one each.** Over a
+   * photograph a gray dot and a primary one are both legible against about half
+   * of it, which is the reason the arrows already carry a ground and a shadow.
+   * One ground under the whole run rather than one per dot, because the dots are
+   * a single object with gaps too small to be edges, where the arrows are two
+   * targets at opposite ends of the picture with the slide showing between them.
+   * Inside it the dots keep the colors they have everywhere else, so what a
+   * reader learned from a carousel in a card still reads on one over a picture.
+   *
+   * **`indicatorAlign` still says where along the edge**, unchanged, because
+   * this placement puts the run on the block-end edge like the other four.
+   * `controlsPlacement`'s own `overlay` reinterprets its alignment, that bar
+   * being stretched across the middle of the picture rather than sitting on an
+   * edge, and the two differ for that reason rather than by oversight.
+   *
    * Independent of `controlsPlacement`. Both default to the bottom, where they
    * share the row and split it, dots to the start and arrows to the end,
    * arrived at by two defaults rather than by a rule about the pair, so moving
@@ -43248,7 +43368,7 @@ export type CustomElementsSolidJs = {
    * where an arrow over a photograph belongs.
    * - `controls-placement`/`controlsPlacement`: Which side of the slides the arrows sit on.
    *
-   * The same four sides as `indicatorPlacement` and the same default, so a
+   * The same five places as `indicatorPlacement` and the same default, so a
    * carousel that moves only one of them keeps the other where it was. `start`
    * or `end` stacks the arrows into a column, which is what a vertical track
    * usually wants.
@@ -43262,8 +43382,10 @@ export type CustomElementsSolidJs = {
    * **It is a value here rather than an axis of its own.** "The controls are
    * over the content" is the whole of what a `hero` appearance would say, and
    * the surface, the edge-to-edge arrows and the bar that catches no presses all
-   * follow from it. These two placements are the whole of where a carousel's
-   * chrome can go.
+   * follow from it. The four edges and the slides are the whole of where a
+   * carousel's chrome can go, and `indicatorPlacement` names the same five: the
+   * dots were short of this one until #389, which is how a hero ended up with
+   * its arrows on the picture and its dots in a band below.
    * - `indicator-align`/`indicatorAlign`: Where along that side the dots sit.
    *
    * The second half of the answer to "where do they go". `indicatorPlacement`
@@ -43304,6 +43426,28 @@ export type CustomElementsSolidJs = {
    * vocabulary across the three is worth more than each family's own: a
    * consumer who has placed a drawer knows where a carousel's dots go.
    *
+   * **`overlay` is the fifth place, and it is the slides themselves**, which is
+   * where a run of dots belongs on a full-bleed carousel: the picture is the
+   * page and the chrome is on it rather than in a band beneath it. The arrows
+   * have always had this and the dots did not, so a hero carousel put its
+   * controls over the picture and left its dots stranded in a bar under it,
+   * which is the one arrangement nobody designs on purpose.
+   *
+   * **The run takes a surface, where the arrows take one each.** Over a
+   * photograph a gray dot and a primary one are both legible against about half
+   * of it, which is the reason the arrows already carry a ground and a shadow.
+   * One ground under the whole run rather than one per dot, because the dots are
+   * a single object with gaps too small to be edges, where the arrows are two
+   * targets at opposite ends of the picture with the slide showing between them.
+   * Inside it the dots keep the colors they have everywhere else, so what a
+   * reader learned from a carousel in a card still reads on one over a picture.
+   *
+   * **`indicatorAlign` still says where along the edge**, unchanged, because
+   * this placement puts the run on the block-end edge like the other four.
+   * `controlsPlacement`'s own `overlay` reinterprets its alignment, that bar
+   * being stretched across the middle of the picture rather than sitting on an
+   * edge, and the two differ for that reason rather than by oversight.
+   *
    * Independent of `controlsPlacement`. Both default to the bottom, where they
    * share the row and split it, dots to the start and arrows to the end,
    * arrived at by two defaults rather than by a rule about the pair, so moving

package/types/vue.d.ts

@@ -1365,7 +1365,7 @@ where an arrow over a photograph belongs. */
   controlsAlign?: (HelixCarousel["controlsAlign"]) | undefined;
   /** Which side of the slides the arrows sit on.
 
-The same four sides as `indicatorPlacement` and the same default, so a
+The same five places as `indicatorPlacement` and the same default, so a
 carousel that moves only one of them keeps the other where it was. `start`
 or `end` stacks the arrows into a column, which is what a vertical track
 usually wants.
@@ -1379,12 +1379,14 @@ photograph is legible against about half of one.
 **It is a value here rather than an axis of its own.** "The controls are
 over the content" is the whole of what a `hero` appearance would say, and
 the surface, the edge-to-edge arrows and the bar that catches no presses all
-follow from it. These two placements are the whole of where a carousel's
-chrome can go. */
+follow from it. The four edges and the slides are the whole of where a
+carousel's chrome can go, and `indicatorPlacement` names the same five: the
+dots were short of this one until #389, which is how a hero ended up with
+its arrows on the picture and its dots in a band below. */
   "controls-placement"?: (HelixCarousel["controlsPlacement"]) | undefined;
   /** Which side of the slides the arrows sit on.
 
-The same four sides as `indicatorPlacement` and the same default, so a
+The same five places as `indicatorPlacement` and the same default, so a
 carousel that moves only one of them keeps the other where it was. `start`
 or `end` stacks the arrows into a column, which is what a vertical track
 usually wants.
@@ -1398,8 +1400,10 @@ photograph is legible against about half of one.
 **It is a value here rather than an axis of its own.** "The controls are
 over the content" is the whole of what a `hero` appearance would say, and
 the surface, the edge-to-edge arrows and the bar that catches no presses all
-follow from it. These two placements are the whole of where a carousel's
-chrome can go. */
+follow from it. The four edges and the slides are the whole of where a
+carousel's chrome can go, and `indicatorPlacement` names the same five: the
+dots were short of this one until #389, which is how a hero ended up with
+its arrows on the picture and its dots in a band below. */
   controlsPlacement?: (HelixCarousel["controlsPlacement"]) | undefined;
   /** Where along that side the dots sit.
 
@@ -1467,6 +1471,28 @@ and `block-start` would be jargon standing in for it.
 vocabulary across the three is worth more than each family's own: a
 consumer who has placed a drawer knows where a carousel's dots go.
 
+**`overlay` is the fifth place, and it is the slides themselves**, which is
+where a run of dots belongs on a full-bleed carousel: the picture is the
+page and the chrome is on it rather than in a band beneath it. The arrows
+have always had this and the dots did not, so a hero carousel put its
+controls over the picture and left its dots stranded in a bar under it,
+which is the one arrangement nobody designs on purpose.
+
+**The run takes a surface, where the arrows take one each.** Over a
+photograph a gray dot and a primary one are both legible against about half
+of it, which is the reason the arrows already carry a ground and a shadow.
+One ground under the whole run rather than one per dot, because the dots are
+a single object with gaps too small to be edges, where the arrows are two
+targets at opposite ends of the picture with the slide showing between them.
+Inside it the dots keep the colors they have everywhere else, so what a
+reader learned from a carousel in a card still reads on one over a picture.
+
+**`indicatorAlign` still says where along the edge**, unchanged, because
+this placement puts the run on the block-end edge like the other four.
+`controlsPlacement`'s own `overlay` reinterprets its alignment, that bar
+being stretched across the middle of the picture rather than sitting on an
+edge, and the two differ for that reason rather than by oversight.
+
 Independent of `controlsPlacement`. Both default to the bottom, where they
 share the row and split it, dots to the start and arrows to the end,
 arrived at by two defaults rather than by a rule about the pair, so moving
@@ -1488,6 +1514,28 @@ and `block-start` would be jargon standing in for it.
 vocabulary across the three is worth more than each family's own: a
 consumer who has placed a drawer knows where a carousel's dots go.
 
+**`overlay` is the fifth place, and it is the slides themselves**, which is
+where a run of dots belongs on a full-bleed carousel: the picture is the
+page and the chrome is on it rather than in a band beneath it. The arrows
+have always had this and the dots did not, so a hero carousel put its
+controls over the picture and left its dots stranded in a bar under it,
+which is the one arrangement nobody designs on purpose.
+
+**The run takes a surface, where the arrows take one each.** Over a
+photograph a gray dot and a primary one are both legible against about half
+of it, which is the reason the arrows already carry a ground and a shadow.
+One ground under the whole run rather than one per dot, because the dots are
+a single object with gaps too small to be edges, where the arrows are two
+targets at opposite ends of the picture with the slide showing between them.
+Inside it the dots keep the colors they have everywhere else, so what a
+reader learned from a carousel in a card still reads on one over a picture.
+
+**`indicatorAlign` still says where along the edge**, unchanged, because
+this placement puts the run on the block-end edge like the other four.
+`controlsPlacement`'s own `overlay` reinterprets its alignment, that bar
+being stretched across the middle of the picture rather than sitting on an
+edge, and the two differ for that reason rather than by oversight.
+
 Independent of `controlsPlacement`. Both default to the bottom, where they
 share the row and split it, dots to the start and arrows to the end,
 arrived at by two defaults rather than by a rule about the pair, so moving