@fusion.dev/helix-headless 0.2.0 → 0.3.0

package/dist/splitter/root/splitter-root.js

@@ -8,251 +8,27 @@ var HelixHeadlessSplitter_1;
 import { capturePointer, closestInstance, customElement, HelixBeforeCollapseEvent, HelixBeforeResizeEvent, HelixElement, requestChange, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property, state } from 'lit/decorators.js';
-/**
- * The inline size under which `orientation="auto"` stacks, in pixels.
- *
- * 32rem at the default root size. Two panes side by side under this have about
- * 240px each before the divider, which is narrower than the content anybody
- * puts in one: the sandbox at 390 gave its source pane 237px and cut every line
- * mid-token, which is the measurement this number comes from.
- *
- * A constant and not a property, until something wants a different one. The
- * axis is the decision worth exposing; where it turns is a detail of this
- * component doing what it was asked.
- */
 const STACK_BELOW = 512;
-/**
- * @summary Two panes and a divider the reader can move.
- *
- * @description
- * **One axis, and nesting is how you get two.** The sandbox this was taken from
- * moves a cross: a divider down the middle, another across the bottom, and a
- * corner that moves both. That is a layout rather than a component, and every
- * part of it that is worth sharing is one divider between two panes. A splitter
- * inside a splitter gives the cross back, and gives the three-pane and the
- * four-pane arrangements it never had.
- *
- * **Where two of them cross there is a corner, and it moves both.** A splitter
- * slotted into a pane of another, at right angles to it, has one end of its
- * divider sitting exactly on the other's. That end grows a handle: `move` under
- * the pointer, both arrow axes on the keyboard, and a drag that carries the two
- * positions at once.
- *
- * **The outer splitter draws it and the nested one announces itself upward.**
- * The nested one drawing its own is the tempting version, since it already
- * knows where its divider begins and needs no measurement of the other, and it
- * is clipped: the crossing lies on the boundary between a pane and the divider
- * beside it, a handle centered there reaches back over the boundary, and a pane
- * is `overflow: auto`. Exactly half the corner is cut off. The outer separator
- * is the one element that already straddles the seam, so the corner belongs in
- * it.
- *
- * That makes the channel between the two a single call in a single direction:
- * `cross(child, at)` says where the child crosses, `moveTo` drives either one,
- * and neither reads the other's state. The child is what calls it, because a
- * parent cannot poll for a child that has not upgraded yet.
- *
- * The one number it carries is a percentage rather than a measurement, which is
- * what keeps either of them from measuring the other, and it assumes the nested
- * splitter fills its pane. That is what slotting one into a pane does. Give the
- * nested splitter its own inset, or wrap it in something smaller than the pane,
- * and the corner is drawn where the crossing would be rather than where it is.
- *
- * **It is a client-side enhancement and says so.** Finding the parent means
- * inspecting the tree, which a server cannot do, so the corner appears at
- * `firstUpdated` and never in the served markup. That is allowed for exactly
- * this: it is an affordance rather than content, and a splitter with no corner
- * yet is a splitter with two working dividers.
- *
- * Where two dividers are parallel there is no corner, because there is nothing
- * to take hold of. Where they cross without a corner, the inner divider takes
- * the pointer: every separator sits on the same layer, so a tie goes to document
- * order and a deeper splitter is always later.
- *
- * **A divider that is moving says so, whoever is moving it.** `:hover` cannot
- * carry that: a drag holds the pointer through capture and a fast one leaves the
- * target behind, and a corner moves the nested divider while the reader is on
- * the crossing, nowhere near it. So a drag in progress is a state, and both
- * dividers a corner moves are lit for as long as it moves them.
- *
- * **The divider is a real `role="separator"` with `aria-valuenow`, moved by the
- * arrow keys as well as by pointer.** A divider only a mouse can move is
- * unusable without one, which is the reason the sandbox's carries the same, and
- * `Home` and `End` take it to its bounds.
- *
- * **It goes where it is put, all the way to either end.** `min` and `max` are
- * nothing and everything unless a consumer says otherwise, because a divider
- * that stops dead short of the edge gives a reader no way to put a pane away.
- * Where a pane should keep a sliver of itself, only whoever put the tabs on it
- * knows how much, so they say so.
- *
- * **A pane can be shut, and that is not the same as a divider at the edge.**
- * The geometry is identical and the knowledge is not: only a shut pane knows
- * where to open back to. So `collapsed` is a second state rather than a reading
- * of the position, and the position it opens to is simply the one collapsing
- * never overwrote. `collapsed-size` keeps a sliver showing where a pane has a
- * tab strip worth leaving, and collapse overrides `min` and `max`, which is
- * what those are for: they keep a pane from vanishing by accident, and this is
- * the deliberate version.
- *
- * The two are kept in step in one direction only: a drag that settles on the
- * collapsed size latches shut, and any move opens it again. Otherwise a reader
- * could drag a pane closed and the consumer's own button would still be
- * offering to close it.
- *
- * A pane shut to nothing is told apart from one shut to a sliver, because the
- * two want different dividers: a sliver still has a boundary worth drawing, and
- * nothing leaves the divider sitting on the container's own edge.
- *
- * **The box is measured once, when a drag starts.** Measuring per move is a
- * forced layout on every pointer event, in the middle of a gesture whose whole
- * job is to stay ahead of the pointer, and nothing about the box moves while the
- * divider does.
- *
- * **`helix-before-resize` fires when it settles, not while it moves.** A drag is a
- * stream of positions and only the one it ends at is a preference; announcing
- * each would ask a consumer to write to storage a hundred times to record one
- * decision. Nothing is stored here either: where a preference lives, and whether
- * it should be kept at all, is the consumer's to decide, and a component writing
- * to storage on its own would be deciding for all of them under a key it chose.
- *
- * The properties below are written by this component and read by whoever draws
- * it. A consumer sets none of them: they carry a number this element computed
- * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
- * without measuring anything itself.
- *
- * @since 0.1.0
- * @status experimental
- * @category layout
- * @aliases SplitPane, Resizable, SplitView
- * @documentation https://helix.fusion.dev/components/splitter
- *
- * @slot end - The pane after it.
- * @slot start - The pane before the divider.
- *
- * @event {HelixBeforeCollapseEvent} helix-before-collapse - Fired before a pane shuts or reopens, and cancelable.
- * @event {HelixBeforeResizeEvent} helix-before-resize - Fired before the divider settles, and cancelable.
- *
- * @csspart corner - The handle where two dividers cross, added on the client.
- * @csspart end - The box holding the second.
- * @csspart separator - The divider itself.
- * @csspart start - The box holding the first pane.
- *
- * @cssproperty --splitter-corner-at - Where a nested splitter crosses this one, as a percentage.
- * @cssproperty --splitter-position - Where the divider sits, as a percentage of the box.
- */
 let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitter extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * How much of a shut pane is still shown, as a percentage.
-         *
-         * Zero by default, which is a pane fully gone. A tab strip or a title bar
-         * that should survive its own collapse says how much of itself to keep, and
-         * only whoever put it there knows that, which is the same reason `min` is a
-         * consumer's to set.
-         */
         this.collapsedSize = 0;
-        /**
-         * Accessible name for the handle where two dividers cross.
-         */
         this.cornerLabel = 'Resize both';
-        /**
-         * Where the divider starts, where nothing declared it.
-         */
         this.defaultPosition = 50;
-        /**
-         * Accessible name for the divider.
-         */
         this.label = 'Resize panes';
-        /**
-         * Nearest it may come to the end, on the same terms as `min`.
-         */
         this.max = 100;
-        /**
-         * Nearest the divider may come to the start.
-         *
-         * A bare number is a percentage, which is what this always took. A CSS length
-         * is resolved against the splitter's own box along its axis, so `min="15rem"`
-         * means fifteen rem of pane whatever the container is doing.
-         *
-         * **The length is the one that holds.** A percentage minimum does not: twenty
-         * per cent is 280px in a 1400px splitter and 100px in a 500px one, and the
-         * number a consumer picked was almost certainly about how much text fits
-         * rather than about a ratio. The pane that a percentage protects at desk
-         * width is squeezed past reading at half of it.
-         *
-         * **It does not fight `collapsed`.** Collapse overrides `min` and `max`, as
-         * the class docstring says, so a pane can still be shut and reopened. What a
-         * minimum forbids is the space between shut and usable: a pane wide enough to
-         * be there and too narrow to read is the state nobody wants and every drag
-         * passes through.
-         */
         this.min = 0;
-        /**
-         * How far one arrow press moves it, as a percentage.
-         */
         this.step = 2;
-        /** The position, whoever set it, and `undefined` until somebody has. */
         this.positionState = undefined;
-        /** The collapse, whoever set it, and `undefined` until somebody has. */
         this.collapsedState = undefined;
-        /**
-         * Where the divider was before the gesture that may be about to shut it.
-         *
-         * A drag writes a position on every pointer move, so by the time it reaches
-         * the edge the number it started from is gone. Taken once, on the press, and
-         * written back if the gesture ends shut, so the pane opens to where it was
-         * rather than to the edge it was dragged against.
-         */
         this.opened = undefined;
-        /**
-         * Where the gesture has moved to, whether or not it was applied. See `move`.
-         *
-         * `@state`, because the divider is drawn from it while a drag is under way.
-         */
         this.reached = undefined;
-        /**
-         * Whether this divider is being moved right now, by anything.
-         *
-         * `:hover` is not enough on its own. A drag holds the pointer through capture
-         * and a fast one leaves the eight pixel target behind, and a corner moves a
-         * divider the pointer is nowhere near: the nested one, while the reader is on
-         * the crossing. Both are dividers that are moving and should say so.
-         *
-         * A `data-` attribute on an element in this shadow root, never on the host.
-         */
         this.dragging = false;
-        /**
-         * Nested splitters that cross this one, and how far along they cross it.
-         *
-         * Written by the child, not found by the parent: a parent cannot poll for a
-         * child that has not upgraded, so the child announces itself once it has. The
-         * number is the child's own `position`, which is also its offset along this
-         * divider, because the child fills the pane and the pane spans this splitter
-         * end to end on the axis the divider runs.
-         *
-         * Not `@state`, because the array is mutated in place. `cross` and `uncross`
-         * request the update themselves.
-         */
         this.crossings = [];
-        /** The splitter this one is nested in, once it has found it. */
         this.outer = null;
-        /** The last position announced upward, so an unchanged one costs nothing. */
         this.crossedAt = undefined;
-        /** The two boxes a corner drag is measured against, taken once. */
         this.cornerOrigin = null;
-        /**
-         * The host's box, measured once when a drag starts.
-         *
-         * Measuring per move is a forced layout on every pointer event, in the middle
-         * of a gesture whose whole job is to stay ahead of the pointer. Nothing about
-         * it moves while the divider does.
-         */
         this.origin = null;
-        /**
-         * Whether `auto` has resolved to stacked, which only the observer sets.
-         */
         this.stacked = false;
         this.handlePointerDown = (event) => {
             const separator = event.currentTarget;
@@ -260,14 +36,9 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
             this.origin = this.vertical
                 ? { length: box.height, start: box.top }
                 : { length: box.width, start: box.left };
-            /* Captured, so the divider keeps the pointer once it has it: a drag that
-               outruns a thin target otherwise ends the moment the pointer leaves it,
-               which on a fast gesture is immediately. */
             capturePointer(separator, event.pointerId);
             this.opened = this.collapsed ? undefined : this.position;
-            // Cleared, so a number from the last gesture cannot settle this one.
             this.reached = undefined;
-            // On the press rather than the first move, so holding it still says so too.
             this.dragging = true;
             event.preventDefault();
         };
@@ -277,9 +48,6 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
                 return;
             }
             const along = this.vertical ? event.clientY : event.clientX;
-            /* Signed against the writing direction, because a pointer is physical and
-               the panes are not: in a right-to-left document the start pane is on the
-               right, so dragging right makes it *larger*. */
             const raw = ((along - origin.start) / origin.length) * 100;
             const rtl = !this.vertical && getComputedStyle(this).direction === 'rtl';
             this.move(rtl ? 100 - raw : raw);
@@ -294,32 +62,11 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
             }
             this.origin = null;
             this.dragging = false;
-            /* Nothing moved, so nothing is announced. Settling on every press would
-               dispatch a change carrying the position it already had, so a plain click
-               rewrites a consumer's stored value from a gesture that moved nothing:
-               harmless where the value round-trips exactly, and not where it does not,
-               which is any consumer storing pixels and dividing by a box. */
             if (this.reached === undefined) {
                 return;
             }
-            /* `reached` is deliberately left standing. It is what the divider is drawn
-               from until the consumer answers, and the setter is what clears it. */
             this.settle(this.reached);
         };
-        /**
-         * The keys a separator answers.
-         *
-         * One axis, the one the divider actually travels along, plus `Home` and `End`
-         * for its bounds. The other two arrows are left alone and the page scrolls
-         * under them as it would anywhere else.
-         *
-         * **Not all four, which is the tempting version.** Taking every arrow would
-         * mean `ArrowLeft` moving a horizontal divider up and down: not a reader
-         * being helped past a wrong guess, an arrow that does not go the way it
-         * points. A reader who guesses wrong is answered better by the corner, where
-         * all four are live and each moves the divider it points along, which is the
-         * only place in a splitter where a second axis means anything.
-         */
         this.handleKeydown = (event) => {
             const back = this.vertical ? 'ArrowUp' : 'ArrowLeft';
             const forward = this.vertical ? 'ArrowDown' : 'ArrowRight';
@@ -341,19 +88,11 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
             }
             this.move(next);
             this.settle(next);
-            // Or the arrows scroll the page under the divider being moved.
             event.preventDefault();
         };
         this.handleDoubleClick = () => {
             this.reset();
         };
-        /**
-         * Both of them, because the corner moves both.
-         *
-         * Its own handler, because the corner is a sibling of the separator rather
-         * than a child of it, for the stacking reason in the stylesheet, so nothing
-         * reaches the separator's own double click by bubbling.
-         */
         this.handleCornerDoubleClick = (event) => {
             const crossing = this.crossings[Number(event.currentTarget.dataset.cross)];
             if (!crossing) {
@@ -385,14 +124,10 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
             crossing.by.opened = crossing.by.collapsed ? undefined : crossing.by.position;
             this.reached = undefined;
             crossing.by.reached = undefined;
-            /* Both of them, on the press. The nested one is reachable here because it is
-               the same class, and this is the whole of what the corner needs beyond
-               `moveTo`: a divider being moved looks like one. */
             this.dragging = true;
             crossing.by.dragging = true;
             this.leaveSeparator(event);
         };
-        /** Both axes at once, each measured against the splitter that owns it. */
         this.handleCornerMove = (event) => {
             const origin = this.cornerOrigin;
             if (!origin) {
@@ -430,11 +165,6 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
             origin.by.moveTo(origin.by.reached ?? origin.by.position, true);
             this.leaveSeparator(event);
         };
-        /**
-         * The corner takes every arrow, each moving the splitter whose axis it points
-         * along, which is the only reading a keyboard can give a handle that moves in
-         * two directions.
-         */
         this.handleCornerKeydown = (event) => {
             const crossing = this.crossings[Number(event.currentTarget.dataset.cross)];
             if (!crossing) {
@@ -457,13 +187,6 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
             this.leaveSeparator(event);
         };
     }
-    /**
-     * Where the divider sits, as a percentage of the whole.
-     *
-     * Reading gives where it is; writing declares it the consumer's, and
-     * `default-position` seeds one this element owns. The same accessor pair
-     * `Pagination.page` and the calendar's `month` carry.
-     */
     get position() {
         const shut = this.collapsed;
         if (shut) {
@@ -474,27 +197,9 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
     set position(next) {
         const previous = this.position;
         this.positionState = next;
-        /* The consumer has spoken, so the drag stops standing in for them. Without
-           this the divider flashes back: `showing` falls to the position set before
-           the gesture and is drawn there for the frame it takes them to answer the
-           announcement, snapping to where the drag started and then jumping to
-           where it was dropped. */
         this.reached = undefined;
         this.requestUpdate('position', previous);
     }
-    /**
-     * Which pane is shut, if either.
-     *
-     * The same accessor pair as `position`, and deliberately a second state
-     * rather than a reading of the first. A pane shut by dragging the divider to
-     * the edge and a pane shut on purpose look identical in geometry and are not
-     * the same thing: only the second knows where to go back to. Kept apart, the
-     * open position is simply the one collapsing never overwrote, so restoring
-     * needs no memory of its own.
-     *
-     * It overrides `min` and `max`, which is the point of it. Those keep a sliver
-     * of a pane during a drag; this is the thing that says the sliver can go.
-     */
     get collapsed() {
         const held = this.collapsedState;
         if (held === undefined) {
@@ -504,21 +209,9 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
     }
     set collapsed(next) {
         const previous = this.collapsed;
-        /* `none` rather than `undefined`, because the two mean different things
-           here and conflating them cost a spec: `undefined` is nobody having
-           spoken, which is the seed's cue to answer, so clearing a collapse handed
-           it straight back to `default-collapsed` and the pane would not open. */
         this.collapsedState = next ?? 'none';
         this.requestUpdate('collapsed', previous);
     }
-    /**
-     * Either kind of bound as a percentage of the box.
-     *
-     * Measured rather than cached: a length is only meaningful against the size
-     * the splitter is right now, and the drag that asks is already reading layout.
-     * Falls back where there is nothing to measure, which is the server and an
-     * element that is not displayed, so `aria-valuemin` is a number either way.
-     */
     toPercent(value, fallback) {
         if (typeof value === 'number') {
             return Number.isFinite(value) ? value : fallback;
@@ -543,41 +236,16 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
         const extent = this.vertical ? box.height : box.width;
         return extent > 0 ? (pixels / extent) * 100 : fallback;
     }
-    /** `min` as a percentage, whichever way it was written. */
     get minPercent() {
         return this.toPercent(this.min, 0);
     }
-    /** `max` as a percentage, whichever way it was written. */
     get maxPercent() {
         return this.toPercent(this.max, 100);
     }
-    /**
-     * The position to draw, which is not always the position to report.
-     *
-     * A controlled splitter applies nothing, so `position` holds still for the
-     * whole gesture: drawn from it, the divider stays where it was until the
-     * pointer comes up and the consumer answers, jumping to the end rather than
-     * following the hand.
-     *
-     * So a drag draws itself. The number is still not announced until it settles,
-     * and the consumer's answer takes over the moment they give one.
-     */
     get showing() {
         return this.reached === undefined ? this.position : this.clamp(this.reached);
     }
-    /**
-     * Moves the divider, and optionally says so.
-     *
-     * Public because a corner on a nested splitter has to drive the one it is
-     * nested in, and that is the whole of what it needs: the pair are not
-     * otherwise coupled and neither reads the other's state. `settled` is false
-     * for each step of a drag and true once, at the end, for the reason a drag
-     * announces once: only the position it ends at is a preference.
-     */
     moveTo(next, settled = false) {
-        /* An unsettled move is a drag in progress, which is what `settled` already
-           means, so the nested splitter a corner drives lights up without either of
-           them being told about the other's presentation. */
         this.dragging = !settled;
         if (settled) {
             this.settle(next);
@@ -586,34 +254,12 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
             this.move(next);
         }
     }
-    /** The collapsed size, held inside the range a percentage can be. */
     get sliver() {
         return Math.min(100, Math.max(0, this.collapsedSize));
     }
-    /**
-     * Whether the divider is against an edge with nothing beside it.
-     *
-     * Geometry, not state. Asking whether the pane is `collapsed` is the wrong
-     * question: a divider driven to the edge by a consumer setting `position` is
-     * just as flush and would still get a line drawn. What the stylesheet needs
-     * to know is whether there is a pane on both sides, which is a fact about
-     * where the divider is however it got there.
-     *
-     * Still not the same question as `collapsed`: a pane shut to a sliver has a
-     * boundary worth drawing, and one shut to nothing has the container's own edge
-     * there instead.
-     */
     get flush() {
         return this.sliver === 0 && this.shutAt(this.position) !== undefined;
     }
-    /**
-     * The collapse a settled position amounts to, if any, so a pane dragged shut
-     * and a pane shut by a consumer's button are the same state.
-     *
-     * No separate threshold. Landing on the collapsed size *is* the gesture, and
-     * `clamp` puts every overshoot exactly on the bound, so the default of zero
-     * latches on any drag that runs off the end.
-     */
     shutAt(position) {
         const size = this.sliver;
         if (position <= size) {
@@ -621,20 +267,11 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
         }
         return position >= 100 - size ? 'end' : undefined;
     }
-    /** Pulled between the bounds, which are the ends unless a consumer moved them. */
     clamp(next) {
         const min = Math.max(0, Math.min(100, this.minPercent));
         const max = Math.max(min, Math.min(100, this.maxPercent));
         return Math.min(max, Math.max(min, Number.isFinite(next) ? next : min));
     }
-    /**
-     * Starts or stops watching, according to what the axis was asked to be.
-     *
-     * Called from `firstUpdated` and from `updated`, so a consumer switching to
-     * `auto` after mount is observed and one switching away stops being: an
-     * observer left running would keep writing `stacked` that nothing reads, and
-     * a splitter told `horizontal` has been given its answer already.
-     */
     watchWidth() {
         if (this.orientation !== 'auto') {
             this.sizes?.disconnect();
@@ -646,58 +283,26 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
         }
         this.sizes = new ResizeObserver(([entry]) => {
             const width = entry?.borderBoxSize?.[0]?.inlineSize ?? entry?.contentRect.width ?? 0;
-            /* Zero while the element is `display: none` or not yet laid out, and a
-               zero is not a narrow splitter: taking it would stack every instance
-               that starts hidden and never turn it back. */
             if (width > 0) {
                 this.stacked = width < STACK_BELOW;
             }
         });
         this.sizes.observe(this);
     }
-    /**
-     * Public because a nested splitter compares axes with the one it is in.
-     *
-     * The one place the axis is decided, which is why `auto` costs a single line
-     * here rather than a pass over seventeen readers: the drag, the arrow keys and
-     * `aria-orientation` all ask this and all turn together.
-     */
     get vertical() {
         return this.orientation === 'vertical' || (this.orientation === 'auto' && this.stacked);
     }
-    /**
-     * Asks to move, and applies it where the position is this element's to move.
-     *
-     * Not announced per step: `helix-before-resize` is the settling, below. A drag that
-     * announced every position would be asking a consumer to record a hundred
-     * decisions to keep one.
-     */
     move(next) {
         const wanted = this.clamp(next);
-        /* Where the gesture has reached, recorded before anything decides whether to
-           apply it. A controlled splitter applies nothing, so its `position` is
-           whatever the consumer last said, and settling at *that* would announce
-           the number it already had: the drag ends where it began and the divider
-           never moves. Only the pointer is exposed to it, the keyboard computing
-           its next position rather than reading it back. */
         this.reached = wanted;
         if (wanted === this.position) {
             return;
         }
         const previous = this.position;
         this.positionState = wanted;
-        /* A divider that is moving is a pane that is opening, and a shut one is
-           still draggable precisely so it can be. Silent, like the move itself:
-           the settling below is what announces either. */
         this.collapsedState = 'none';
         this.requestUpdate('position', previous);
     }
-    /**
-     * Says the arrangement has settled, so a consumer can keep it.
-     *
-     * Through the audited path, so a consumer who owns `position` is told what was
-     * asked for and decides, and one who does not has already had it applied.
-     */
     settle(next) {
         const wanted = this.clamp(next);
         const shut = this.shutAt(wanted);
@@ -712,14 +317,9 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
             next: wanted,
         });
         if (shut !== this.collapsed) {
-            /* Two values from one gesture, so two announcements. `ChangeDetail`
-               carries a name for exactly this, and a consumer listening for one of
-               them is not made to care about the other. */
             requestChange({
                 apply: (value) => {
                     const previous = this.collapsed;
-                    // Back to where the gesture started, so opening it again is a return
-                    // rather than a jump to the edge it was dragged against.
                     if (value !== '' && this.opened !== undefined) {
                         this.positionState = this.opened;
                     }
@@ -732,30 +332,11 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
             });
         }
     }
-    /** Puts the divider back where the markup put it. */
     reset() {
-        /* `default-position`, never the position captured at first render. Those
-           are the same only when nobody owns the position: a consumer who does owns
-           what it was on that first frame too, and theirs can be a number they
-           cannot compute yet, as the sandbox's is, sizing its panel in pixels with
-           no box to divide by until it has rendered once. Home would then be
-           "panel closed" and a double click would shut the panel rather than
-           restore it.
-    
-           Declared rather than remembered, so it is a value a consumer can state
-           and change, and it needs no capture at all. */
         const home = this.clamp(this.defaultPosition);
         this.move(home);
         this.settle(home);
     }
-    /**
-     * Records that a nested splitter crosses this one at `at` percent along it.
-     *
-     * Public because it is the whole of the channel between the two, and it runs
-     * one way: the child tells the parent where it is, and the parent draws the
-     * corner and drives them both. Nothing is read back, so neither has to know
-     * anything about the other's state.
-     */
     cross(by, at) {
         const found = this.crossings.find((crossing) => crossing.by === by);
         if (found) {
@@ -769,7 +350,6 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
         }
         this.requestUpdate();
     }
-    /** Forgets a nested splitter that has left the tree. See `cross`. */
     uncross(by) {
         const at = this.crossings.findIndex((crossing) => crossing.by === by);
         if (at === -1) {
@@ -778,63 +358,22 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
         this.crossings.splice(at, 1);
         this.requestUpdate();
     }
-    /**
-     * Announces this splitter to the one it is nested in, if they cross.
-     *
-     * Client only. The server has no tree to walk, and a parent that has not
-     * upgraded has no `orientation` to compare against, so this waits for
-     * `firstUpdated`. That is what the corner is allowed to be: an affordance
-     * rather than content, absent from the served markup and appearing at
-     * hydration, with two working dividers in the meantime.
-     *
-     * `parentElement` first, so a splitter does not find itself.
-     *
-     * **By identity rather than by tag, which is what `closestInstance` exists
-     * for.** A selector like `'helix-splitter, helix-headless-splitter'` names a
-     * styled tag from a headless package and misses any third tag, which is
-     * exactly what subclassing a headless element produces: the lookup returns
-     * null, the nested splitter gets no corner, and nothing reports an error.
-     *
-     * It also crosses shadow boundaries, which `closest` does not: a splitter
-     * slotted into another component's shadow root has a `parentNode` chain
-     * ending at a `ShadowRoot`, and nesting through a slot is the ordinary case
-     * for anything composable.
-     */
     findOuter() {
         const outer = closestInstance(this.parentElement, HelixHeadlessSplitter_1);
         if (!outer || outer === this || outer.vertical === this.vertical) {
-            // Parallel dividers never meet, so there is no corner to take hold of.
             return;
         }
         this.outer = outer;
         this.crossedAt = this.position;
         outer.cross(this, this.position);
     }
-    /**
-     * Keeps a gesture on the corner to itself.
-     *
-     * The stop is not redundant with the corner being a sibling of the separator.
-     * Should a press on the corner ever reach the separator, the separator calls
-     * `setPointerCapture`, which retargets every later pointer event to *it*: the
-     * corner's `pointerup` never arrives, its origin is never cleared, and it
-     * goes on resizing with no button held. Worse than moving twice.
-     *
-     * `preventDefault` is needed either way: a drag across a pane would otherwise
-     * select the text under it.
-     */
     leaveSeparator(event) {
         event.stopPropagation();
         event.preventDefault();
     }
     connectedCallback() {
         super.connectedCallback();
-        // Only on a re-connect. The first pass waits for `firstUpdated`, which is
-        // where a parent is guaranteed to have upgraded.
         if (this.hasUpdated) {
-            /* The width watch too, and it belongs here for a plainer reason than the
-               one above: `disconnectedCallback` drops the observer on every move, so
-               a splitter reordered in the DOM would stop watching its own width and
-               `auto` would freeze on whatever it last saw. */
             this.watchWidth();
             this.findOuter();
         }
@@ -852,41 +391,23 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
         this.watchWidth();
         this.findOuter();
     }
-    /** Keeps the corner in step while this divider moves under it. */
     updated(changed) {
         super.updated(changed);
         if (changed.has('orientation')) {
             this.watchWidth();
         }
-        /* The resolved collapse, mirrored for a consumer's own rules: a shut pane
-           usually wants its contents to stop being read as well as stop being seen.
-           `data-` and not `collapsed`, so a serialized host cannot be re-parsed with
-           it declared, which is the trap `value` records. It carries which pane
-           rather than a bare boolean, and that is still a state and not a payload:
-           two names for the two sides, nothing of the consumer's in it. */
         if (this.collapsed) {
             this.dataset.collapsed = this.collapsed;
         }
         else {
             delete this.dataset.collapsed;
         }
-        /* The resolved axis, mirrored for the same reason and on the same terms: a
-           stylesheet selecting `[orientation="vertical"]` cannot see an `auto` that
-           has turned, so the layout would stay side by side while the drag, the keys
-           and `aria-orientation` had all gone the other way. That is the lie the
-           policy warns a CSS-only version tells, arrived at from the other side.
-    
-           Only where `auto` produced it. An explicit `vertical` already carries an
-           attribute saying so, and writing a second would put two sources of one
-           truth on the host and a flash of the wrong axis before hydration. */
         if (this.orientation === 'auto' && this.stacked) {
             this.dataset.axis = 'vertical';
         }
         else {
             delete this.dataset.axis;
         }
-        /* `showing` rather than `position`, so a corner drawn on the splitter above
-           follows this divider through a drag instead of catching up at the end. */
         if (this.outer && this.showing !== this.crossedAt) {
             this.crossedAt = this.showing;
             this.outer.cross(this, this.showing);
@@ -897,16 +418,6 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
     }
     render() {
         const position = this.showing;
-        /* The panes are marked while the divider moves, so the styled tier can take
-           them out of the pointer's way.
-           A pane holds whatever a consumer put in it, and an `<iframe>` is the case
-           that breaks: a cross-origin frame is its own hit-testing world, and a drag
-           whose path crosses one can be lost to it. The sandbox is exactly this, a
-           sandboxed preview sitting against the panel divider, so the drag that
-           makes the panel bigger is the drag that goes straight over it.
-           On the panes rather than on the host, which the `dragging` state above
-           records as a rule: a `data-` attribute here is one this element owns, and
-           one on the host is one a React consumer's server markup never had. */
         return html `<div
         part="start"
         ?data-dragging=${this.dragging}