@fusion.dev/helix-headless 0.0.0-dev → 0.0.2

package/dist/dialog/root/dialog-root.js

@@ -70,34 +70,28 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
          * Accessible name for the dialog.
          */
         this.label = '';
+        /* Opened and closed from anywhere on the page, without a line of script:
+           `<helix-button commandfor="…" command="--show">`. See `CommandController`
+           for why this is the platform's invoker rather than a `data-` recipe. */
+        this.commands = new CommandController(this, {
+            commands: {
+                '--close': () => this.close(),
+                '--show': () => this.show(),
+                '--toggle': () => this.toggleOpen(),
+            },
+        });
         /**
-         * Whether Escape can close it.
+         * Whether Escape or a press on the backdrop can close it.
          *
          * Off for a dialog that must be answered. It does not disable the close
          * control a consumer slots in: refusing to be dismissed is not the same as
          * refusing to be closed, and a dialog with no way out at all is a trap.
          *
-         * Escape *and* a press on the backdrop, which it now genuinely means. The
-         * sentence said both for a long time while nothing listened for a backdrop
-         * press, so it promised a behavior a consumer would have written their
-         * markup around; the fix then was to narrow the sentence, and the fix now is
-         * to build the half that was missing.
-         *
          * A persistent dialog does not ignore that press. It answers it: see
          * `refuse`, which is the only way a dialog that will not be dismissed can say
          * so at the moment a reader asks.
          */
         this.persistent = false;
-        /* Opened and closed from anywhere on the page, without a line of script:
-           `<helix-button commandfor="…" command="--show">`. See `CommandController`
-           for why this is the platform's invoker rather than a `data-` recipe. */
-        this.commands = new CommandController(this, {
-            commands: {
-                '--close': () => this.close(),
-                '--show': () => this.show(),
-                '--toggle': () => this.toggleOpen(),
-            },
-        });
         /** What a value set before the element existed is kept in. */
         this.returned = '';
         /**
@@ -134,7 +128,7 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
         
                `cancel` is deliberately not relayed. `handleCancel` prevents it so that
                Escape is a request rather than an act, so the native one never completes:
-               relaying it would announce a dismissal that was refused. See 296. */
+               relaying it would announce a dismissal that was refused. */
             this.relayNativeEvent(event);
         };
         /**
@@ -172,9 +166,9 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
      *
      * **The whole point of a `<dialog>` returning a value is lost behind a shadow
      * boundary**, which is where this one is: the platform's contract is
-     * `close(value)` then read `returnValue`, and a consumer could do neither
-     * because `querySelector` does not reach the element. A confirmation asking
-     * which button was pressed is the ordinary case and had no answer.
+     * `close(value)` then read `returnValue`, and `querySelector` does not reach
+     * the element to do either. A confirmation asking which button was pressed is
+     * the ordinary case.
      *
      * Held here as well as on the element, so a value set before the first render
      * survives to it and a consumer reading one back gets what they wrote.
@@ -273,19 +267,48 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
      * this decides only when it happens. Removed first so a second press
      * restarts it: without that, pressing twice does nothing the second time,
      * which is the impression the whole thing exists to avoid.
+     *
+     * **`once: true` is not a release when the event cannot arrive.** Under
+     * `prefers-reduced-motion: reduce` the styled tier sets `animation: none`, so
+     * no animation runs, `animationend` never fires, and every refused press left
+     * a listener that could not be removed and an attribute that stayed on. The
+     * controller bounds it to one listener, aborted before the next is added.
+     *
+     * **And the attribute is cleared at once when no animation is running**, asked
+     * of the platform rather than of a media query: this tier does not know what
+     * refusing looks like, and the same silence arrives from a consumer's
+     * stylesheet, from reduced motion, and from no styled tier being loaded at
+     * all.
+     *
+     * **`CSSAnimation` specifically, because `getAnimations` returns transitions
+     * too.** A panel that is still running its entrance transition answers the
+     * bare `length` check with a truthy number while no animation exists to end,
+     * so a refusal landing inside that window took the listener branch and waited
+     * for an `animationend` that was never coming: the attribute stayed on until
+     * the next refused press. That is the same bug this method exists to close,
+     * one window narrower. `getAnimations` flushes pending style itself, so no
+     * reflow is forced for it.
      */
     refuse() {
         const panel = this.dialog;
         if (!panel) {
             return;
         }
+        this.refusal?.abort();
         panel.removeAttribute('data-refused');
         // Read forces the removal to land before the attribute goes back on, or the
         // two happen in one frame and the animation never restarts.
         void panel.offsetWidth;
         panel.setAttribute('data-refused', '');
+        const animating = panel.getAnimations().some((one) => one instanceof CSSAnimation);
+        if (!animating) {
+            panel.removeAttribute('data-refused');
+            return;
+        }
+        this.refusal = new AbortController();
         panel.addEventListener('animationend', () => panel.removeAttribute('data-refused'), {
             once: true,
+            signal: this.refusal.signal,
         });
     }
     render() {
@@ -304,15 +327,15 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
     </dialog>`;
     }
 };
+__decorate([
+    property({ attribute: 'closedby', reflect: true })
+], HelixHeadlessDialog.prototype, "closedBy", void 0);
 __decorate([
     property()
 ], HelixHeadlessDialog.prototype, "label", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessDialog.prototype, "persistent", void 0);
-__decorate([
-    property({ attribute: 'closedby', reflect: true })
-], HelixHeadlessDialog.prototype, "closedBy", void 0);
 HelixHeadlessDialog = __decorate([
     customElement('helix-headless-dialog')
 ], HelixHeadlessDialog);

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

@@ -26,10 +26,6 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @csspart line - The rule itself, or each half of it where something is set in.
  */
 export declare class HelixHeadlessDivider extends HelixElement {
-    /**
-     * Which way the rule runs.
-     */
-    orientation?: 'horizontal' | 'vertical';
     /**
      * Whether the rule is announced as a separator.
      *
@@ -45,14 +41,17 @@ export declare class HelixHeadlessDivider extends HelixElement {
      * here has to be.
      */
     announced: boolean;
+    /**
+     * Which way the rule runs.
+     */
+    orientation?: 'horizontal' | 'vertical';
     /**
      * Marks the middle region when nothing has been set into it.
      *
      * A divider with no content has to be one continuous line, and the space
      * either side of the content is what would break it. `:empty` cannot answer
      * this and neither can `:host(:has(...))`, which is invalid CSS dropped at
-     * parse time: `check:selectors` caught exactly that rule here, written in
-     * this file, by an author who had already read the note saying so.
+     * parse time.
      *
      * On the region inside the shadow root rather than on the host, because an
      * attribute written onto the host is a change to markup the consumer rendered.

package/dist/divider/root/divider-root.js

@@ -57,8 +57,7 @@ let HelixHeadlessDivider = class HelixHeadlessDivider extends HelixElement {
      * A divider with no content has to be one continuous line, and the space
      * either side of the content is what would break it. `:empty` cannot answer
      * this and neither can `:host(:has(...))`, which is invalid CSS dropped at
-     * parse time: `check:selectors` caught exactly that rule here, written in
-     * this file, by an author who had already read the note saying so.
+     * parse time.
      *
      * On the region inside the shadow root rather than on the host, because an
      * attribute written onto the host is a change to markup the consumer rendered.
@@ -104,12 +103,12 @@ let HelixHeadlessDivider = class HelixHeadlessDivider extends HelixElement {
       <div part="line" role="presentation"></div>`;
     }
 };
-__decorate([
-    property({ reflect: true })
-], HelixHeadlessDivider.prototype, "orientation", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessDivider.prototype, "announced", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessDivider.prototype, "orientation", void 0);
 HelixHeadlessDivider = __decorate([
     customElement('helix-headless-divider')
 ], HelixHeadlessDivider);

package/dist/donut-chart/root/donut-chart-root.d.ts

@@ -15,7 +15,7 @@ declare const HelixHeadlessDonutChart_base: typeof HelixElement & (new (...args:
  *
  * **It refuses negative values rather than drawing them.** A share of a whole
  * cannot be less than nothing, and an arc for a negative number either runs
- * backwards over its neighbours or is silently dropped. Those rows are skipped
+ * backwards over its neighbors or is silently dropped. Those rows are skipped
  * and the total is of what is left, which is the only reading that stays true.
  *
  * **The shape is drawn with a dashed stroke, not with arc commands.** One
@@ -70,11 +70,10 @@ export declare class HelixHeadlessDonutChart extends HelixHeadlessDonutChart_bas
      * reading for opposite sides of the chart. So the slices say which one they
      * are and this only holds the answer.
      *
-     * Set here rather than in a constructor, and that is not a style choice. The
-     * analyzer reads `this.pointer.axis = 'none'` in a constructor body as a
-     * declaration of a public field called `axis`, and failed the build with
-     * `HelixHeadlessDonutChart.tracks has no description` for a member that does not
-     * exist on this class at all.
+     * Set here rather than in a constructor, and it must not move there: the
+     * analyzer reads `this.pointer.axis = 'none'` in a constructor body as the
+     * declaration of a public field, and fails the build demanding a description
+     * for a member this class does not have.
      */
     connectedCallback(): void;
     /**
@@ -90,11 +89,11 @@ export declare class HelixHeadlessDonutChart extends HelixHeadlessDonutChart_bas
      * measured from anything but zero is, which is why this is a value here and
      * the bar chart's baseline is not a property at all.
      *
-     * **Geometry rather than a CSS hook, and it had to move.** This was
-     * `--donut-chart-thickness`, and the dash arithmetic needs the circumference,
-     * which needs the radius: reading a custom property means `getComputedStyle`,
-     * which is client-only, so a server would have drawn a different ring than
-     * the client. A plot's proportions are markup for the same reason `curve` is.
+     * **Geometry rather than a CSS hook.** The dash arithmetic needs the
+     * circumference, which needs the radius, and reading a custom property means
+     * `getComputedStyle`, which is client-only: a server would draw a different
+     * ring than the client. A plot's proportions are markup for the same reason
+     * `curve` is.
      */
     hole?: 'large' | 'none' | 'small';
     /**
@@ -110,11 +109,10 @@ export declare class HelixHeadlessDonutChart extends HelixHeadlessDonutChart_bas
      * the band is, this is angular and says how far round it goes. A `half`
      * `none` is a semi-pie and is a real thing to want.
      *
-     * **Not a gauge**, and the distinction is worth stating because this row was
-     * first filed as one. A gauge is one value against a range, which is a
-     * different data shape entirely and is `Meter`, whose `round` example already
-     * draws the reading as a ring. This divides a whole into parts and then
-     * declines to use the bottom half of the circle.
+     * **Not a gauge.** A gauge is one value against a range, which is a different
+     * data shape entirely and is `Meter`, whose `round` example already draws the
+     * reading as a ring. This divides a whole into parts and then declines to use
+     * the bottom half of the circle.
      *
      * Reflected, because the stylesheet has three things to say about it: the
      * rotation that puts the first slice at nine o'clock, the aspect ratio of a
@@ -172,15 +170,14 @@ export declare class HelixHeadlessDonutChart extends HelixHeadlessDonutChart_bas
      * path is here for every donut and is `fill: none; stroke: none` until
      * something asks for it.
      *
-     * **Not a replacement for the dash, which was the first plan.** The dash
-     * carries three jobs and only one of them is the shape: a share growing is a
-     * `stroke-dasharray` interpolating with no reflow, and `@starting-style` on
-     * that same property is the whole reason the ring sweeps in rather than
-     * appearing. A `d` cannot do either. CSS interpolates one only between paths
-     * of identical command structure, and the large-arc flag flips the moment a
-     * slice crosses a half turn, so a growing slice would pop partway through the
-     * transition it was meant to smooth. Both animations stay on the dash and this
-     * path follows it.
+     * **Not a replacement for the dash.** The dash carries three jobs and only
+     * one of them is the shape: a share growing is a `stroke-dasharray`
+     * interpolating with no reflow, and `@starting-style` on that same property is
+     * the whole reason the ring sweeps in rather than appearing. A `d` cannot do
+     * either. CSS interpolates one only between paths of identical command
+     * structure, and the large-arc flag flips the moment a slice crosses a half
+     * turn, so a growing slice would pop partway through the transition it was
+     * meant to smooth. Both animations stay on the dash and this path follows it.
      *
      * The turn to twelve o'clock is arithmetic here rather than the rotation the
      * stylesheet gives the circles. That rule uses `transform-box: fill-box`, so

package/dist/donut-chart/root/donut-chart-root.js

@@ -29,12 +29,10 @@ const GAP = 9999;
  * How much of the radius the ring takes, by name.
  *
  * **The outer edge is fixed and the radius follows the thickness**, which is
- * what makes `none` a pie and makes clipping impossible. The stroke sits astride
- * its own radius, so a ring drawn at a fixed `r` grows outward as well as
- * inward: measured against a 100 box, the old fixed `r=40` had an unstated
- * ceiling at a thickness of 20, and anything past it crossed the view box and
- * was cut with nothing to say so. Closing the hole that way would have needed a
- * thickness of 80, spanning `r=0` to `r=80` in a box whose half is 50.
+ * what makes `none` a pie. The stroke sits astride its own radius, so a ring
+ * drawn at a fixed `r` grows outward as well as inward: against a 100 box, a
+ * fixed `r=40` has an unstated ceiling at a thickness of 20, and anything past
+ * it crosses the view box and is cut with nothing to say so.
  *
  * Derived instead, `r = EDGE - thickness / 2`, the outer edge lands on `EDGE`
  * for every value and the inner edge is `EDGE - thickness`. A pie is where the
@@ -65,7 +63,7 @@ const THICKNESS = {
  *
  * **It refuses negative values rather than drawing them.** A share of a whole
  * cannot be less than nothing, and an arc for a negative number either runs
- * backwards over its neighbours or is silently dropped. Those rows are skipped
+ * backwards over its neighbors or is silently dropped. Those rows are skipped
  * and the total is of what is left, which is the only reading that stays true.
  *
  * **The shape is drawn with a dashed stroke, not with arc commands.** One
@@ -110,7 +108,6 @@ const THICKNESS = {
  * @cssproperty --donut-chart-stroke - How thick the ring is drawn, derived from `hole`.
  */
 let HelixHeadlessDonutChart = class HelixHeadlessDonutChart extends MixinChartSource(HelixElement) {
-    /* The slices, in table order, with anything negative dropped. */
     /**
      * The pointer is not mapped across this one.
      *
@@ -121,11 +118,10 @@ let HelixHeadlessDonutChart = class HelixHeadlessDonutChart extends MixinChartSo
      * reading for opposite sides of the chart. So the slices say which one they
      * are and this only holds the answer.
      *
-     * Set here rather than in a constructor, and that is not a style choice. The
-     * analyzer reads `this.pointer.axis = 'none'` in a constructor body as a
-     * declaration of a public field called `axis`, and failed the build with
-     * `HelixHeadlessDonutChart.tracks has no description` for a member that does not
-     * exist on this class at all.
+     * Set here rather than in a constructor, and it must not move there: the
+     * analyzer reads `this.pointer.axis = 'none'` in a constructor body as the
+     * declaration of a public field, and fails the build demanding a description
+     * for a member this class does not have.
      */
     connectedCallback() {
         super.connectedCallback();
@@ -176,16 +172,10 @@ let HelixHeadlessDonutChart = class HelixHeadlessDonutChart extends MixinChartSo
      */
     renderPlot(shares) {
         /* The thickness is declared here, on the box that holds both the ring and
-           the middle, and not on the slices.
-         *
-         * It was on each `<circle>`, and `[part="center"]` read it to size the hole
-         * it fills. A custom property inherits down and never sideways, so the
-         * middle, being a sibling, always got the fallback: the hole was sized as if
-         * every ring were the resting thickness. At `hole="large"` that made the
-         * middle smaller than the actual hole and the total fitted with room to
-         * spare, and at the default the two matched exactly and the total overflowed
-         * onto the slices. One reads as fine and the other as a bug, from one
-         * mistake. */
+           the middle, and never on the slices. A custom property inherits down and
+           never sideways, so `[part="center"]` is a sibling of the circles and would
+           only ever read the fallback, sizing the hole as if every ring were the
+           resting thickness. */
         return html `<div
       aria-hidden="true"
       id="helix-chart-plot"
@@ -263,15 +253,14 @@ let HelixHeadlessDonutChart = class HelixHeadlessDonutChart extends MixinChartSo
      * path is here for every donut and is `fill: none; stroke: none` until
      * something asks for it.
      *
-     * **Not a replacement for the dash, which was the first plan.** The dash
-     * carries three jobs and only one of them is the shape: a share growing is a
-     * `stroke-dasharray` interpolating with no reflow, and `@starting-style` on
-     * that same property is the whole reason the ring sweeps in rather than
-     * appearing. A `d` cannot do either. CSS interpolates one only between paths
-     * of identical command structure, and the large-arc flag flips the moment a
-     * slice crosses a half turn, so a growing slice would pop partway through the
-     * transition it was meant to smooth. Both animations stay on the dash and this
-     * path follows it.
+     * **Not a replacement for the dash.** The dash carries three jobs and only
+     * one of them is the shape: a share growing is a `stroke-dasharray`
+     * interpolating with no reflow, and `@starting-style` on that same property is
+     * the whole reason the ring sweeps in rather than appearing. A `d` cannot do
+     * either. CSS interpolates one only between paths of identical command
+     * structure, and the large-arc flag flips the moment a slice crosses a half
+     * turn, so a growing slice would pop partway through the transition it was
+     * meant to smooth. Both animations stay on the dash and this path follows it.
      *
      * The turn to twelve o'clock is arithmetic here rather than the rotation the
      * stylesheet gives the circles. That rule uses `transform-box: fill-box`, so
@@ -317,16 +306,14 @@ let HelixHeadlessDonutChart = class HelixHeadlessDonutChart extends MixinChartSo
            Ids are scoped to the shadow root, so an index is enough to keep them
            apart, and two donuts on a page cannot collide. */
         /* **`fill="none"` as an attribute, not a rule, because this tier has
-             no rules.** An SVG path fills black by default and the styled tier
-             says `fill: none` in its own stylesheet, so the shape was invisible
-             there and four black slices covering the ring everywhere else. Caught
-             by retaking the visual baselines: the headless donut lost two of its
-             four greys to a closed shape nobody had told to stop filling.
+             no rules.** An SVG path fills black by default, and the styled tier's
+             own `fill: none` covers only that tier: everywhere else these closed
+             shapes paint over the ring.
     
              A presentation attribute loses to any CSS rule, so the styled tier
              still decides and a consumer can still fill this if they want one.
-             What it cannot do any more is fill by accident on the tier whose
-             whole premise is that it ships no CSS. */
+             What it cannot do is fill by accident on the tier whose whole premise
+             is that it ships no CSS. */
         const clip = `helix-donut-edge-${index}`;
         return svg `<clipPath id=${clip}><path d=${shape} /></clipPath>
     <path
@@ -353,24 +340,23 @@ let HelixHeadlessDonutChart = class HelixHeadlessDonutChart extends MixinChartSo
         if (!share) {
             return drawTooltip(this.sourceRows, at, this.tag('tooltip'));
         }
-        /* **Outside the ring, on the slice's own bearing.** Centered in the hole was
-           the first version: harmless over a donut, since the hole is empty, and it
-           covers the data on a pie, and in neither case does it say *which* slice it
-           means. Out here it does, and one rule serves both.
-         *
-         * The mid-angle, less a quarter turn because the ring is rotated to start
-         * at twelve o'clock and this arithmetic starts at three. The point is the
-         * outer edge, and the box is pushed a little further along the same bearing
-         * so its arrow rests on the ring rather than in it. */
+        /* **Outside the ring, on the slice's own bearing**, rather than centered in
+           the hole: centered covers the data on a pie, and in neither shape does it
+           say *which* slice it means. Out here one rule serves both.
+    
+           The mid-angle, less a quarter turn because the ring is rotated to start
+           at twelve o'clock and this arithmetic starts at three. The point is the
+           outer edge, and the box is pushed a little further along the same bearing
+           so its arrow rests on the ring rather than in it. */
         const angle = (share.start + share.fraction / 2) * 2 * Math.PI - Math.PI / 2;
         const edge = EDGE;
         const x = CENTER + Math.cos(angle) * edge;
         const y = CENTER + Math.sin(angle) * edge;
         return drawTooltip(this.sourceRows, at, this.tag('tooltip'), {
             /* The preferred side from the bearing's dominant axis, and
-               `FloatingController` moves it if that side does not fit. Four fixed
-               sides could not express a bearing at all, which is what made the arrow
-               miss the ring; a preference plus flipping can. */
+               `FloatingController` moves it if that side does not fit. A fixed side
+               cannot express a bearing, so the arrow misses the ring; a preference
+               plus flipping can. */
             placement: Math.abs(Math.cos(angle)) > Math.abs(Math.sin(angle))
                 ? Math.cos(angle) > 0
                     ? 'right'

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

@@ -5,8 +5,9 @@ declare const HelixHeadlessDrawer_base: (new (...args: any[]) => import("@fusion
  * @summary A panel that slides in from an edge.
  *
  * @description
- * Takes `MixinControllerOpen`, so `open`, `defaultOpen`, and `OpenChange` behave exactly
- * as they do on an accordion item, and a consumer already knows the API.
+ * Takes `MixinControllerOpen`, so `open`, `defaultOpen` and the
+ * `helix-before-open` and `helix-before-close` requests behave exactly as they
+ * do on an accordion item, and a consumer already knows the API.
  *
  * Modal by default, which is three things together and not one: focus is
  * trapped inside, Escape and an outside press close it, and the page behind is
@@ -15,16 +16,10 @@ declare const HelixHeadlessDrawer_base: (new (...args: any[]) => import("@fusion
  *
  * Content stays mounted when closed, so it is in the server's markup and can
  * animate. A closed `<dialog>` is already out of the tab order and out of the
- * accessibility tree, so nothing here writes `inert`.
- *
- * **This described a hand-written `inert` until 21 Aug 2026, and had done since
- * the panel became a `<dialog>`.** The rewrite took the `role`, the
- * `aria-modal`, the scrim and the `inert` with it, because the element brings
- * all four, and the comments at the two call sites say so. The class doc did
- * not, and `drawer-root.ssr.spec.ts` has asserted the panel carries no `inert`
- * the whole time: a spec three files away existing to contradict the prose is
- * the same shape as `Stat`'s `detail` slot, which is what `check:references`
- * was written after and is the half it cannot see.
+ * accessibility tree, so nothing here writes `inert`. The `role`, the
+ * `aria-modal` and the scrim come from the element too, and
+ * `drawer-root.ssr.spec.ts` asserts the panel carries no hand-written `inert`
+ * and no hand-written `role`.
  *
  * Opened declaratively with the platform's invoker attributes:
  *
@@ -44,7 +39,7 @@ declare const HelixHeadlessDrawer_base: (new (...args: any[]) => import("@fusion
  *
  * @event {Event} close - Relayed, because the platform's own does not escape.
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the panel closes, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the drawer opens or closes. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the panel opens. Cancelable: refusing it takes the decision and nothing moves.
  * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
  *
  * @csspart content - The scrolling content region.
@@ -54,14 +49,18 @@ declare const HelixHeadlessDrawer_base: (new (...args: any[]) => import("@fusion
 export declare class HelixHeadlessDrawer extends HelixHeadlessDrawer_base {
     protected readonly commands: CommandController;
     /**
-     * Which edge the drawer comes from.
+     * Which close requests the browser answers on its own.
      *
-     * Unset is `end`, which the styled tier reads as `:host(:not([placement]))`
-     * beside `:host([placement="end"])` rather than as a value written here: a
-     * default assigned to the property would reflect onto every host and put a
-     * `placement="end"` into markup no consumer wrote.
+     * `<dialog closedby>`, forwarded, and safe to forward because every path it
+     * opens still comes back through this element: a close request fires `cancel`
+     * first, `handleCancel` prevents it, and `requestOpen` decides. So
+     * `closedby="any"` gains light dismiss without giving up the refusal, which is
+     * the property this component exists to keep.
+     *
+     * Absent by default, which is the platform's `auto` and this library's rule
+     * that a resting value is an attribute's absence.
      */
-    placement?: 'start' | 'end' | 'top' | 'bottom';
+    closedBy?: 'any' | 'closerequest' | 'none';
     /**
      * Accessible name for the panel.
      */
@@ -81,18 +80,14 @@ export declare class HelixHeadlessDrawer extends HelixHeadlessDrawer_base {
      */
     modal: boolean;
     /**
-     * Which close requests the browser answers on its own.
-     *
-     * `<dialog closedby>`, forwarded, and safe to forward because every path it
-     * opens still comes back through this element: a close request fires `cancel`
-     * first, `handleCancel` prevents it, and `requestOpen` decides. So
-     * `closedby="any"` gains light dismiss without giving up the refusal, which is
-     * the property this component exists to keep.
+     * Which edge the drawer comes from.
      *
-     * Absent by default, which is the platform's `auto` and this library's rule
-     * that a resting value is an attribute's absence.
+     * Unset is `end`, which the styled tier reads as `:host(:not([placement]))`
+     * beside `:host([placement="end"])` rather than as a value written here: a
+     * default assigned to the property would reflect onto every host and put a
+     * `placement="end"` into markup no consumer wrote.
      */
-    closedBy?: 'any' | 'closerequest' | 'none';
+    placement?: 'start' | 'end' | 'top' | 'bottom';
     /**
      * What the dialog closed with, the way `<dialog>` reports it.
      *

package/dist/drawer/root/drawer-root.js

@@ -11,8 +11,9 @@ import { property } from 'lit/decorators.js';
  * @summary A panel that slides in from an edge.
  *
  * @description
- * Takes `MixinControllerOpen`, so `open`, `defaultOpen`, and `OpenChange` behave exactly
- * as they do on an accordion item, and a consumer already knows the API.
+ * Takes `MixinControllerOpen`, so `open`, `defaultOpen` and the
+ * `helix-before-open` and `helix-before-close` requests behave exactly as they
+ * do on an accordion item, and a consumer already knows the API.
  *
  * Modal by default, which is three things together and not one: focus is
  * trapped inside, Escape and an outside press close it, and the page behind is
@@ -21,16 +22,10 @@ import { property } from 'lit/decorators.js';
  *
  * Content stays mounted when closed, so it is in the server's markup and can
  * animate. A closed `<dialog>` is already out of the tab order and out of the
- * accessibility tree, so nothing here writes `inert`.
- *
- * **This described a hand-written `inert` until 21 Aug 2026, and had done since
- * the panel became a `<dialog>`.** The rewrite took the `role`, the
- * `aria-modal`, the scrim and the `inert` with it, because the element brings
- * all four, and the comments at the two call sites say so. The class doc did
- * not, and `drawer-root.ssr.spec.ts` has asserted the panel carries no `inert`
- * the whole time: a spec three files away existing to contradict the prose is
- * the same shape as `Stat`'s `detail` slot, which is what `check:references`
- * was written after and is the half it cannot see.
+ * accessibility tree, so nothing here writes `inert`. The `role`, the
+ * `aria-modal` and the scrim come from the element too, and
+ * `drawer-root.ssr.spec.ts` asserts the panel carries no hand-written `inert`
+ * and no hand-written `role`.
  *
  * Opened declaratively with the platform's invoker attributes:
  *
@@ -50,7 +45,7 @@ import { property } from 'lit/decorators.js';
  *
  * @event {Event} close - Relayed, because the platform's own does not escape.
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the panel closes, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the drawer opens or closes. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the panel opens. Cancelable: refusing it takes the decision and nothing moves.
  * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
  *
  * @csspart content - The scrolling content region.
@@ -115,7 +110,7 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
         
                `cancel` is deliberately not relayed. `handleCancel` prevents it so that
                Escape is a request rather than an act, so the native one never completes:
-               relaying it would announce a dismissal that was refused. See 296. */
+               relaying it would announce a dismissal that was refused. */
             this.relayNativeEvent(event);
         };
         /**
@@ -167,10 +162,8 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
            throws and `close()` on a shut one fires a second `close` event.
          *
          * `showModal` when modal and `show` when not, which is the whole of what
-         * `modal` means now: both put the panel in the top layer, and only the
-         * first brings a backdrop, a focus trap and `inert` behind it. This was a
-         * hand-built `position: fixed` panel with a scrim div, a focus trap and a
-         * dismisser, none of which the platform needed telling. */
+         * `modal` means: both put the panel in the top layer, and only the first
+         * brings a backdrop, a focus trap and `inert` behind it. */
         const panel = this.panel;
         if (!panel) {
             return;
@@ -205,8 +198,8 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
     }
 };
 __decorate([
-    property({ reflect: true })
-], HelixHeadlessDrawer.prototype, "placement", void 0);
+    property({ attribute: 'closedby', reflect: true })
+], HelixHeadlessDrawer.prototype, "closedBy", void 0);
 __decorate([
     property()
 ], HelixHeadlessDrawer.prototype, "label", void 0);
@@ -214,8 +207,8 @@ __decorate([
     property({ converter: onUnlessFalse })
 ], HelixHeadlessDrawer.prototype, "modal", void 0);
 __decorate([
-    property({ attribute: 'closedby', reflect: true })
-], HelixHeadlessDrawer.prototype, "closedBy", void 0);
+    property({ reflect: true })
+], HelixHeadlessDrawer.prototype, "placement", void 0);
 HelixHeadlessDrawer = __decorate([
     customElement('helix-headless-drawer')
 ], HelixHeadlessDrawer);