@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,491 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @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.**
+ * Built the other way round first, because a splitter already knows where its
+ * own divider begins and needs no measurement of the other, and that version was
+ * 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 was 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.
+ */
+export declare class HelixHeadlessSplitter extends HelixElement {
+    /**
+     * Which way the panes are laid out.
+     *
+     * `horizontal` is side by side with an upright divider between them, and
+     * `aria-orientation` on that divider is therefore `vertical`: a separator's
+     * orientation is the direction it is *drawn* in, not the axis it moves along,
+     * so the two words are opposite each other here on purpose. The code had this
+     * right and the sentence beside it said the reverse.
+     *
+     * Unset is horizontal and stays unset, so a reflected default cannot appear on
+     * a host whose server output never had it.
+     *
+     * **`auto` lays the panes out along whichever axis the splitter has room for**,
+     * stacking them once its own inline size falls under `STACK_BELOW`. It is a
+     * value rather than a default because turning a splitter is not a style
+     * change: the drag axis, the arrow keys and `aria-orientation` all turn with
+     * it, so a CSS-only version would look stacked and behave side by side, with
+     * the keyboard moving the wrong way and the accessibility tree saying
+     * something untrue. Everything here reads `vertical` rather than this
+     * property, which is what makes one getter enough to turn all three together.
+     *
+     * **Its own width and not the viewport**, per the responsiveness policy in
+     * `.claude/rules/helix.md`: a splitter in a 300px panel of a 1400px window has
+     * no room for two panes side by side, and a media query would hand it the
+     * desktop branch. A `ResizeObserver` on the host asks the only question that
+     * has an honest answer.
+     */
+    orientation?: 'auto' | 'horizontal' | 'vertical';
+    /**
+     * 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(): number;
+    set position(next: number);
+    /**
+     * Where the divider starts, where nothing declared it.
+     */
+    defaultPosition: number;
+    /**
+     * 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(): 'end' | 'start' | undefined;
+    set collapsed(next: 'end' | 'start' | undefined);
+    /**
+     * Which pane starts shut, where nothing declared it.
+     */
+    defaultCollapsed?: 'end' | 'start';
+    /**
+     * 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.
+     */
+    collapsedSize: number;
+    /**
+     * 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.
+     */
+    min: number | string;
+    /**
+     * Nearest it may come to the end, on the same terms as `min`.
+     */
+    max: number | string;
+    /**
+     * 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.
+     */
+    private toPercent;
+    /** `min` as a percentage, whichever way it was written. */
+    private get minPercent();
+    /** `max` as a percentage, whichever way it was written. */
+    private get maxPercent();
+    /**
+     * How far one arrow press moves it, as a percentage.
+     */
+    step: number;
+    /**
+     * Accessible name for the divider.
+     */
+    label: string;
+    /**
+     * Accessible name for the handle where two dividers cross.
+     */
+    cornerLabel: string;
+    /** The position, whoever set it, and `undefined` until somebody has. */
+    private positionState;
+    /** The collapse, whoever set it, and `undefined` until somebody has. */
+    private collapsedState;
+    /**
+     * 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.
+     */
+    private opened;
+    /**
+     * 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.
+     */
+    private reached;
+    /**
+     * 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 and the divider stayed where it was until the pointer came up
+     * and the consumer answered: it jumped to the end rather than following the
+     * hand. Reported as resizing that was not seamless and did not work as it had.
+     *
+     * So a drag draws itself. The number is not announced until it settles, which
+     * is the rule that has not changed, and the consumer's answer takes over the
+     * moment they give one. It is what the sandbox did for itself before it used
+     * this component: write the size on every pointer move, tell anyone once.
+     */
+    private get showing();
+    /**
+     * 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.
+     */
+    private dragging;
+    /**
+     * 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.
+     */
+    private crossings;
+    /** The splitter this one is nested in, once it has found it. */
+    private outer;
+    /** The last position announced upward, so an unchanged one costs nothing. */
+    private crossedAt;
+    /** The two boxes a corner drag is measured against, taken once. */
+    private cornerOrigin;
+    /**
+     * 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.
+     */
+    private origin;
+    /**
+     * 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: number, settled?: boolean): void;
+    /** The collapsed size, held inside the range a percentage can be. */
+    private get sliver();
+    /**
+     * Whether the divider is against an edge with nothing beside it.
+     *
+     * Geometry, not state, which is the second answer here: it asked whether the
+     * pane was `collapsed`, and a divider driven to the edge by a consumer setting
+     * `position` is just as flush and drew a line anyway. What the stylesheet
+     * needs to know is whether there is a pane on both sides, and that 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.
+     */
+    private get flush();
+    private shutAt;
+    /** Pulled between the bounds, which are the ends unless a consumer moved them. */
+    private clamp;
+    /**
+     * Whether `auto` has resolved to stacked, which only the observer sets.
+     */
+    private stacked;
+    /** Watches this element's own width while `auto` is what it was asked for. */
+    private sizes;
+    /**
+     * 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.
+     */
+    private watchWidth;
+    /**
+     * 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(): boolean;
+    /**
+     * 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.
+     */
+    private move;
+    /**
+     * 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.
+     */
+    private settle;
+    private readonly handlePointerDown;
+    private readonly handlePointerMove;
+    private readonly handlePointerUp;
+    /**
+     * 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.
+     *
+     * *Corrected 18 Aug 2026. This said "both axes, always", on the reasoning
+     * `KeyboardNavigationController` uses for a set of items: a reader who guesses
+     * the wrong arrow gets nothing. The code has never done it, and measuring the
+     * three tab stops of a nested pair is what turned that up, so the prose was
+     * describing a decision nobody implemented.*
+     *
+     * *Leaving it as one axis, because nesting is what settles it. Taking all four
+     * would mean `ArrowLeft` moving a horizontal divider up and down, which is not
+     * a reader being helped past a guess, it is an arrow that does not go the way
+     * it points. And the guess it was protecting against is answered better by the
+     * corner: there, all four arrows are live and each moves the divider it points
+     * along, which is the only place in a splitter where a second axis means
+     * anything.*
+     */
+    private readonly handleKeydown;
+    /** Puts the divider back where the markup put it. */
+    private reset;
+    private readonly handleDoubleClick;
+    /**
+     * Both of them, because the corner moves both.
+     *
+     * It needs its own handler now. Inside the separator this came free by
+     * bubbling, and moving the corner out to sit against the host for the stacking
+     * reason took the double click with it: the divider reset and the crossing
+     * did not. Reported.
+     */
+    private readonly handleCornerDoubleClick;
+    /**
+     * 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: HelixHeadlessSplitter, at: number): void;
+    /** Forgets a nested splitter that has left the tree. See `cross`. */
+    uncross(by: HelixHeadlessSplitter): void;
+    /**
+     * 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 `closestInstance` exists for and
+     * counts this file in its own documentation.** It matched
+     * `'helix-splitter, helix-headless-splitter'`, and only `@fusion.dev/helix` registers
+     * the first of those: a headless package naming a styled one by string. Under
+     * any third tag, which is exactly what subclassing a headless element is for and
+     * what `helix/styled` itself does, the lookup returned null and a nested
+     * splitter had no corner, with no error anywhere.
+     *
+     * 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.
+     */
+    private findOuter;
+    private readonly handleCornerDown;
+    /** Both axes at once, each measured against the splitter that owns it. */
+    private readonly handleCornerMove;
+    private readonly handleCornerUp;
+    /**
+     * 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.
+     */
+    private readonly handleCornerKeydown;
+    /**
+     * Keeps a gesture on the corner to itself.
+     *
+     * The corner was a child of the separator first, and every one of its events
+     * bubbled there, so the separator started its own drag from the same press.
+     * That is worse than moving twice: the separator calls `setPointerCapture`,
+     * which retargets every later pointer event to *it*, so the corner's
+     * `pointerup` never arrived, its origin was never cleared, and it went on
+     * resizing with no button held. Reported as resizing without a press.
+     *
+     * The corner is a sibling now, for the stacking reason in the stylesheet, so
+     * nothing reaches the separator by bubbling. This stays because the fix should
+     * not depend on where the element happens to sit, and `preventDefault` is
+     * still needed either way: a drag across a pane would otherwise select the
+     * text under it.
+     */
+    private leaveSeparator;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    /** Keeps the corner in step while this divider moves under it. */
+    protected updated(changed: PropertyValues): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}