@fusion.dev/helix-headless 0.100.0 → 0.101.0

package/types/jsx.d.ts

@@ -74,6 +74,8 @@ import type {
   HelixHeadlessInput,
   HelixHeadlessKbd,
   HelixHeadlessLegend,
+  HelixHeadlessLightbox,
+  HelixHeadlessLightboxItem,
   HelixHeadlessLineChart,
   HelixHeadlessList,
   HelixHeadlessListItem,
@@ -8525,6 +8527,231 @@ shadow root reads a table in that root rather than one in the document.
   textContent?: (string | number) | undefined;
 };
 
+export type HelixHeadlessLightboxItemProps = {
+  /** Whether this is the one being shown.
+
+Written by the root, which is the only thing that sees the set. */
+  current?: (HelixHeadlessLightboxItem["current"]) | undefined;
+  /** What this item is called, for the reading that says where the reader is. */
+  label?: (HelixHeadlessLightboxItem["label"]) | undefined;
+  /** What names this item, and what `active` on the root is compared against. */
+  value?: (HelixHeadlessLightboxItem["value"]) | undefined;
+};
+
+export type HelixHeadlessLightboxItemSolidJsProps = {
+  /** Whether this is the one being shown.
+
+Written by the root, which is the only thing that sees the set. */
+  "prop:current"?: (HelixHeadlessLightboxItem["current"]) | undefined;
+  /** What this item is called, for the reading that says where the reader is. */
+  "prop:label"?: (HelixHeadlessLightboxItem["label"]) | undefined;
+  /** What names this item, and what `active` on the root is compared against. */
+  "prop:value"?: (HelixHeadlessLightboxItem["value"]) | undefined;
+
+  /** Set the innerHTML of the element */
+  innerHTML?: (string) | undefined;
+  /** Set the textContent of the element */
+  textContent?: (string | number) | undefined;
+};
+
+/** `HelixHeadlessLightbox` component event */
+export type HelixHeadlessLightboxElementEvent<E = Event> = TypedEvent<
+  HelixHeadlessLightbox,
+  E
+>;
+/** `helix-activate` event type */
+export type HelixHeadlessLightboxHelixActivateElementEvent =
+  HelixHeadlessLightboxElementEvent<HelixActivateEvent>;
+/** `helix-before-activate` event type */
+export type HelixHeadlessLightboxHelixBeforeActivateElementEvent =
+  HelixHeadlessLightboxElementEvent<HelixBeforeActivateEvent>;
+/** `helix-before-close` event type */
+export type HelixHeadlessLightboxHelixBeforeCloseElementEvent =
+  HelixHeadlessLightboxElementEvent<HelixBeforeCloseEvent>;
+/** `helix-before-open` event type */
+export type HelixHeadlessLightboxHelixBeforeOpenElementEvent =
+  HelixHeadlessLightboxElementEvent<HelixBeforeOpenEvent>;
+
+export type HelixHeadlessLightboxProps = {
+  /** How long the reader may be still before the chrome hides, in milliseconds.
+
+Zero keeps it up, which is what a viewer with a caption worth reading
+wants. The wait is only ever about idling: whether anything else should
+keep the chrome up is the consumer's to decide with this. */
+  "idle-delay"?: (HelixHeadlessLightbox["idleDelay"] | `${number}`) | undefined;
+  /** How long the reader may be still before the chrome hides, in milliseconds.
+
+Zero keeps it up, which is what a viewer with a caption worth reading
+wants. The wait is only ever about idling: whether anything else should
+keep the chrome up is the consumer's to decide with this. */
+  idleDelay?: (HelixHeadlessLightbox["idleDelay"]) | undefined;
+  /** Accessible name for the viewer. */
+  label?: (HelixHeadlessLightbox["label"]) | undefined;
+  /** Whether walking past the end comes back to the beginning. */
+  loop?: (HelixHeadlessLightbox["loop"]) | undefined;
+  /** The reading that says where in the set the reader is, with `{index}` and
+`{count}` filled in.
+
+Announced rather than only drawn, because the picture changing under a
+reader who cannot see it is otherwise silent. A consumer who has their own
+counter in the chrome can empty this and say it themselves. */
+  "status-label"?: (HelixHeadlessLightbox["statusLabel"]) | undefined;
+  /** The reading that says where in the set the reader is, with `{index}` and
+`{count}` filled in.
+
+Announced rather than only drawn, because the picture changing under a
+reader who cannot see it is otherwise silent. A consumer who has their own
+counter in the chrome can empty this and say it themselves. */
+  statusLabel?: (HelixHeadlessLightbox["statusLabel"]) | undefined;
+  /** Which item is current, by its `value`.
+
+Not `option.active`, which is the option the keyboard is on: that is a
+different question from which one is chosen.
+
+Writing always applies, so `<helix-tabs active="one">` starts on that
+tab, and `default-active` is how markup says where to start without
+naming the current one. */
+  active?: (HelixHeadlessLightbox["active"]) | undefined;
+  /** Which item the markup declared current.
+
+Ignored once `active` is written. */
+  "default-active"?: (HelixHeadlessLightbox["defaultActive"]) | undefined;
+  /** Which item the markup declared current.
+
+Ignored once `active` is written. */
+  defaultActive?: (HelixHeadlessLightbox["defaultActive"]) | undefined;
+  /** Whether the element is open.
+
+One property, not two, so `dialog.open` answers the question anyone
+asking it meant. Writing always applies; `<helix-dialog open>` is the
+same statement in markup.
+
+**Not reflected, and that is required rather than tidy.** Reflection
+writes the resolved state back as an attribute, so an element that opened
+itself would put `open` on its own host: cloned, serialized for
+hydration, or diffed by a framework, it comes back holding whatever the
+last reader did rather than what the author wrote. `:state(open)` carries
+the resolved state for stylesheets, which is what the mirror is for. */
+  open?: (HelixHeadlessLightbox["open"]) | undefined;
+  /** Whether the markup declared it open. Ignored once `open` is written. */
+  "default-open"?: (HelixHeadlessLightbox["defaultOpen"]) | undefined;
+  /** Whether the markup declared it open. Ignored once `open` is written. */
+  defaultOpen?: (HelixHeadlessLightbox["defaultOpen"]) | undefined;
+
+  /** Relayed, because the platform's own does not escape. */
+  onclose?: ((e: HelixHeadlessLightboxElementEvent) => void) | undefined;
+  /** Fired once the shown item has moved, so the element already holds it. */
+  "onhelix-activate"?: ((
+    e: HelixHeadlessLightboxHelixActivateElementEvent,
+  ) => void) | undefined;
+  /** Fired before the shown item changes, and cancelable. The only way to refuse one. */
+  "onhelix-before-activate"?: ((
+    e: HelixHeadlessLightboxHelixBeforeActivateElementEvent,
+  ) => void) | undefined;
+  /** Fired before it closes, and cancelable. */
+  "onhelix-before-close"?: ((
+    e: HelixHeadlessLightboxHelixBeforeCloseElementEvent,
+  ) => void) | undefined;
+  /** Fired before it opens, and cancelable. */
+  "onhelix-before-open"?: ((
+    e: HelixHeadlessLightboxHelixBeforeOpenElementEvent,
+  ) => void) | undefined;
+  /** Says the state moved, carrying `newState` and `oldState`. */
+  ontoggle?: ((e: HelixHeadlessLightboxElementEvent) => void) | undefined;
+};
+
+export type HelixHeadlessLightboxSolidJsProps = {
+  /** How long the reader may be still before the chrome hides, in milliseconds.
+
+Zero keeps it up, which is what a viewer with a caption worth reading
+wants. The wait is only ever about idling: whether anything else should
+keep the chrome up is the consumer's to decide with this. */
+  "attr:idle-delay"?: (HelixHeadlessLightbox["idleDelay"] | `${number}`) | undefined;
+  /** How long the reader may be still before the chrome hides, in milliseconds.
+
+Zero keeps it up, which is what a viewer with a caption worth reading
+wants. The wait is only ever about idling: whether anything else should
+keep the chrome up is the consumer's to decide with this. */
+  "prop:idleDelay"?: (HelixHeadlessLightbox["idleDelay"]) | undefined;
+  /** Accessible name for the viewer. */
+  "prop:label"?: (HelixHeadlessLightbox["label"]) | undefined;
+  /** Whether walking past the end comes back to the beginning. */
+  "prop:loop"?: (HelixHeadlessLightbox["loop"]) | undefined;
+  /** The reading that says where in the set the reader is, with `{index}` and
+`{count}` filled in.
+
+Announced rather than only drawn, because the picture changing under a
+reader who cannot see it is otherwise silent. A consumer who has their own
+counter in the chrome can empty this and say it themselves. */
+  "attr:status-label"?: (HelixHeadlessLightbox["statusLabel"]) | undefined;
+  /** The reading that says where in the set the reader is, with `{index}` and
+`{count}` filled in.
+
+Announced rather than only drawn, because the picture changing under a
+reader who cannot see it is otherwise silent. A consumer who has their own
+counter in the chrome can empty this and say it themselves. */
+  "prop:statusLabel"?: (HelixHeadlessLightbox["statusLabel"]) | undefined;
+  /** Which item is current, by its `value`.
+
+Not `option.active`, which is the option the keyboard is on: that is a
+different question from which one is chosen.
+
+Writing always applies, so `<helix-tabs active="one">` starts on that
+tab, and `default-active` is how markup says where to start without
+naming the current one. */
+  "prop:active"?: (HelixHeadlessLightbox["active"]) | undefined;
+  /** Which item the markup declared current.
+
+Ignored once `active` is written. */
+  "attr:default-active"?: (HelixHeadlessLightbox["defaultActive"]) | undefined;
+  /** Which item the markup declared current.
+
+Ignored once `active` is written. */
+  "prop:defaultActive"?: (HelixHeadlessLightbox["defaultActive"]) | undefined;
+  /** Whether the element is open.
+
+One property, not two, so `dialog.open` answers the question anyone
+asking it meant. Writing always applies; `<helix-dialog open>` is the
+same statement in markup.
+
+**Not reflected, and that is required rather than tidy.** Reflection
+writes the resolved state back as an attribute, so an element that opened
+itself would put `open` on its own host: cloned, serialized for
+hydration, or diffed by a framework, it comes back holding whatever the
+last reader did rather than what the author wrote. `:state(open)` carries
+the resolved state for stylesheets, which is what the mirror is for. */
+  "prop:open"?: (HelixHeadlessLightbox["open"]) | undefined;
+  /** Whether the markup declared it open. Ignored once `open` is written. */
+  "bool:default-open"?: (HelixHeadlessLightbox["defaultOpen"]) | undefined;
+  /** Whether the markup declared it open. Ignored once `open` is written. */
+  "prop:defaultOpen"?: (HelixHeadlessLightbox["defaultOpen"]) | undefined;
+  /** Relayed, because the platform's own does not escape. */
+  "on:close"?: ((e: HelixHeadlessLightboxElementEvent) => void) | undefined;
+  /** Fired once the shown item has moved, so the element already holds it. */
+  "on:helix-activate"?: ((
+    e: HelixHeadlessLightboxHelixActivateElementEvent,
+  ) => void) | undefined;
+  /** Fired before the shown item changes, and cancelable. The only way to refuse one. */
+  "on:helix-before-activate"?: ((
+    e: HelixHeadlessLightboxHelixBeforeActivateElementEvent,
+  ) => void) | undefined;
+  /** Fired before it closes, and cancelable. */
+  "on:helix-before-close"?: ((
+    e: HelixHeadlessLightboxHelixBeforeCloseElementEvent,
+  ) => void) | undefined;
+  /** Fired before it opens, and cancelable. */
+  "on:helix-before-open"?: ((
+    e: HelixHeadlessLightboxHelixBeforeOpenElementEvent,
+  ) => void) | undefined;
+  /** Says the state moved, carrying `newState` and `oldState`. */
+  "on:toggle"?: ((e: HelixHeadlessLightboxElementEvent) => void) | undefined;
+
+  /** Set the innerHTML of the element */
+  innerHTML?: (string) | undefined;
+  /** Set the textContent of the element */
+  textContent?: (string | number) | undefined;
+};
+
 export type HelixHeadlessLineChartProps = {
   /** Whether a wash is drawn under each line, each from the floor on its own.
 The washes overlap rather than add up: for parts that make a total, use
@@ -26157,6 +26384,227 @@ export type CustomElements = {
     HelixHeadlessLegendProps & BaseProps<HelixHeadlessLegend> & BaseEvents<HelixHeadlessLegend>
   >;
 
+  /**
+   * A wrapper around whatever the consumer opened, which is the whole of what it
+   * is: a picture, a frame of video, a chart. The family shows one at a time and
+   * this is how it says which, so the content stays the consumer's and the
+   * arithmetic stays the root's.
+   *
+   * Hidden rather than unmounted while another item is current, for the reason
+   * `TabPanel` gives: what is in the markup is what a crawler reads and what a
+   * server sent, and an `<img>` that has already decoded does not decode again
+   * when the reader walks back to it.
+   *
+   * ## Attributes & Properties
+   *
+   * Component attributes and properties that can be applied to the element or by using JavaScript.
+   *
+   * - `current`: Whether this is the one being shown.
+   *
+   * Written by the root, which is the only thing that sees the set.
+   * - `label`: What this item is called, for the reading that says where the reader is.
+   * - `value`: What names this item, and what `active` on the root is compared against.
+   * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
+   *
+   * **Named `whenSettled` because `settled` is taken four times over**, by
+   * Image, Splitter and both color controls, none of them about transitions. A
+   * base class takes the name every subclass then cannot use.
+   *
+   * **The state it reports cannot be watched, which is why this exists.** A
+   * custom state is deliberately not in the DOM, so there is no
+   * `MutationObserver` equivalent for `ElementInternals.states`. Await this
+   * instead.
+   *
+   * Separate from `updateComplete`, which resolves in the microtask checkpoint
+   * the suppression is still active in. That is the distinction `readyToMove`
+   * in `@fusion.dev/helix-testing` is written around.
+   *
+   * It never resolves where `requestAnimationFrame` never fires, which is a
+   * server, a hidden tab, and happy-dom. Callers that must not hang there race
+   * it against a timeout, as the happy-dom harness's `readyToMove` does. The
+   * browser harness's awaits it alone: a browser always runs the frame, and a
+   * timer beside it was a bet on how long one takes, which a busy run lost. (property only) (readonly)
+   *
+   * ## Slots
+   *
+   * Areas where markup can be added to the component.
+   *
+   * - `(default)`: What is being shown.
+   * - `description`: A line under it saying what it is.
+   *
+   * ## CSS Parts
+   *
+   * Custom selectors for styling elements within the component.
+   *
+   * - `item`: The box the content is shown in.
+   *
+   * ## CSS States
+   *
+   * These can be used to apply styling when a component is in a given state.
+   *
+   * - `current`: While this is the item the lightbox is showing.
+   * - `settled`: Set a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.
+   */
+  "helix-headless-lightbox-item": Partial<
+    HelixHeadlessLightboxItemProps &
+      BaseProps<HelixHeadlessLightboxItem> &
+      BaseEvents<HelixHeadlessLightboxItem>
+  >;
+
+  /**
+   * **A lightbox is chrome around a picture rather than a picture.** It draws
+   * nothing of its own: what it shows is whatever the consumer opened, so this
+   * earns its place on the frame, the keyboard and the reading that says where in
+   * the set the reader is.
+   *
+   * **The modal half is the platform's.** A real `<dialog>` opened with
+   * `showModal()` brings the top layer, a backdrop, Escape and `inert` behind it,
+   * and this repository has already removed one hand-written focus trap for being
+   * worse than that: `inert` on the rest of the document is something no
+   * JavaScript trap can achieve. Every way it can close comes back through
+   * `requestOpen`, which is what `Dialog` and `Drawer` both do and for the reason
+   * they both give.
+   *
+   * **The set is this component's own and not `Carousel`'s.** A carousel is a
+   * track: a scroller with snap points, per-view arithmetic and stops it can rest
+   * between. A lightbox shows one thing at a time and has no track, so what it
+   * needs is which item is current, which is `active` and the same pair `Tabs`
+   * uses. The arrow keys move the picture under a reader whose focus stays in the
+   * dialog, which is also why `KeyboardNavigationController` is not the right
+   * tool: that one moves focus between focusable items, and these are pictures.
+   *
+   * **Chrome hides while the reader is still**, on `IdleController`, and comes
+   * back on a pointer move or a focus. `fullscreen` is `FullscreenController`, the
+   * same pair `Video` holds and the only two it shares.
+   *
+   * ## Attributes & Properties
+   *
+   * Component attributes and properties that can be applied to the element or by using JavaScript.
+   *
+   * - `idle-delay`/`idleDelay`: How long the reader may be still before the chrome hides, in milliseconds.
+   *
+   * Zero keeps it up, which is what a viewer with a caption worth reading
+   * wants. The wait is only ever about idling: whether anything else should
+   * keep the chrome up is the consumer's to decide with this.
+   * - `label`: Accessible name for the viewer.
+   * - `loop`: Whether walking past the end comes back to the beginning.
+   * - `status-label`/`statusLabel`: The reading that says where in the set the reader is, with `{index}` and
+   * `{count}` filled in.
+   *
+   * Announced rather than only drawn, because the picture changing under a
+   * reader who cannot see it is otherwise silent. A consumer who has their own
+   * counter in the chrome can empty this and say it themselves.
+   * - `active`: Which item is current, by its `value`.
+   *
+   * Not `option.active`, which is the option the keyboard is on: that is a
+   * different question from which one is chosen.
+   *
+   * Writing always applies, so `<helix-tabs active="one">` starts on that
+   * tab, and `default-active` is how markup says where to start without
+   * naming the current one.
+   * - `default-active`/`defaultActive`: Which item the markup declared current.
+   *
+   * Ignored once `active` is written.
+   * - `open`: Whether the element is open.
+   *
+   * One property, not two, so `dialog.open` answers the question anyone
+   * asking it meant. Writing always applies; `<helix-dialog open>` is the
+   * same statement in markup.
+   *
+   * **Not reflected, and that is required rather than tidy.** Reflection
+   * writes the resolved state back as an attribute, so an element that opened
+   * itself would put `open` on its own host: cloned, serialized for
+   * hydration, or diffed by a framework, it comes back holding whatever the
+   * last reader did rather than what the author wrote. `:state(open)` carries
+   * the resolved state for stylesheets, which is what the mirror is for.
+   * - `default-open`/`defaultOpen`: Whether the markup declared it open. Ignored once `open` is written.
+   * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
+   *
+   * **Named `whenSettled` because `settled` is taken four times over**, by
+   * Image, Splitter and both color controls, none of them about transitions. A
+   * base class takes the name every subclass then cannot use.
+   *
+   * **The state it reports cannot be watched, which is why this exists.** A
+   * custom state is deliberately not in the DOM, so there is no
+   * `MutationObserver` equivalent for `ElementInternals.states`. Await this
+   * instead.
+   *
+   * Separate from `updateComplete`, which resolves in the microtask checkpoint
+   * the suppression is still active in. That is the distinction `readyToMove`
+   * in `@fusion.dev/helix-testing` is written around.
+   *
+   * It never resolves where `requestAnimationFrame` never fires, which is a
+   * server, a hidden tab, and happy-dom. Callers that must not hang there race
+   * it against a timeout, as the happy-dom harness's `readyToMove` does. The
+   * browser harness's awaits it alone: a browser always runs the frame, and a
+   * timer beside it was a bet on how long one takes, which a busy run lost. (property only) (readonly)
+   *
+   * ## Events
+   *
+   * Events that will be emitted by the component.
+   *
+   * - `close`: Relayed, because the platform's own does not escape.
+   * - `helix-activate`: Fired once the shown item has moved, so the element already holds it.
+   * - `helix-before-activate`: Fired before the shown item changes, and cancelable. The only way to refuse one.
+   * - `helix-before-close`: Fired before it closes, and cancelable.
+   * - `helix-before-open`: Fired before it opens, and cancelable.
+   * - `toggle`: Says the state moved, carrying `newState` and `oldState`.
+   *
+   * ## Slots
+   *
+   * Areas where markup can be added to the component.
+   *
+   * - `(default)`: The items, which are `<helix-headless-lightbox-item>` elements.
+   * - `footer`: Chrome below the item, such as a counter or a thumbnail strip.
+   * - `header`: Chrome above the item, such as a title and a close button.
+   *
+   * ## Methods
+   *
+   * Methods that can be called to access component functionality.
+   *
+   * - `show() => void`: Opens the viewer, which makes the rest of the page inert.
+   * - `close() => void`: Asks to close, which a consumer may refuse.
+   * - `next() => void`: Shows the next item, or the first where it is past the end and looping.
+   * - `previous() => void`: Shows the previous item, or the last where it is past the start and looping.
+   * - `toggleFullscreen() => void`: Fills the screen with the viewer, or comes back.
+   * - `requestActive(next: string) => boolean`: Requests a new current item, and reports whether the request stood.
+   *
+   * Announces before it acts, so `preventDefault()` on the `helix-before-activate` is
+   * a refusal and nothing moves. Unlike a native control, nothing has moved
+   * by the time this runs, so refusing is simply not writing: there is
+   * nothing to put back. Nobody refusing means the set updates itself,
+   * whether or not a consumer declared `active`, a declared property being a
+   * seed and a correction.
+   * - `requestOpen(next: boolean) => boolean`: Requests an open-state change, and reports whether it was applied.
+   *
+   * Announces before it acts, so `preventDefault()` on the `helix-before-open` or
+   * `helix-before-close` is a refusal and nothing moves. Nobody refusing means the
+   * element opens or closes itself, whether or not a consumer declared
+   * `open`: a declared property is a seed and a correction, and a consumer
+   * who wants the decision for themselves refuses it and assigns their own.
+   * - `toggleOpen() => boolean`: Requests the opposite of the current state.
+   *
+   * ## CSS Parts
+   *
+   * Custom selectors for styling elements within the component.
+   *
+   * - `dialog`: The native dialog element.
+   * - `live`: The region that says which item is shown.
+   * - `viewport`: The box the current item is shown in.
+   *
+   * ## CSS States
+   *
+   * These can be used to apply styling when a component is in a given state.
+   *
+   * - `fullscreen`: While the viewer fills the screen.
+   * - `idle`: While the reader has been still long enough to hide the chrome.
+   * - `open`: While the viewer is open.
+   * - `settled`: Set a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.
+   */
+  "helix-headless-lightbox": Partial<
+    HelixHeadlessLightboxProps & BaseProps<HelixHeadlessLightbox> & BaseEvents<HelixHeadlessLightbox>
+  >;
+
   /**
    * The chart for a shape rather than for a quantity, which is what decides the
    * one thing a bar chart is not allowed to do.
@@ -44264,6 +44712,231 @@ export type CustomElementsSolidJs = {
       BaseEvents<HelixHeadlessLegend>
   >;
 
+  /**
+   * A wrapper around whatever the consumer opened, which is the whole of what it
+   * is: a picture, a frame of video, a chart. The family shows one at a time and
+   * this is how it says which, so the content stays the consumer's and the
+   * arithmetic stays the root's.
+   *
+   * Hidden rather than unmounted while another item is current, for the reason
+   * `TabPanel` gives: what is in the markup is what a crawler reads and what a
+   * server sent, and an `<img>` that has already decoded does not decode again
+   * when the reader walks back to it.
+   *
+   * ## Attributes & Properties
+   *
+   * Component attributes and properties that can be applied to the element or by using JavaScript.
+   *
+   * - `current`: Whether this is the one being shown.
+   *
+   * Written by the root, which is the only thing that sees the set.
+   * - `label`: What this item is called, for the reading that says where the reader is.
+   * - `value`: What names this item, and what `active` on the root is compared against.
+   * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
+   *
+   * **Named `whenSettled` because `settled` is taken four times over**, by
+   * Image, Splitter and both color controls, none of them about transitions. A
+   * base class takes the name every subclass then cannot use.
+   *
+   * **The state it reports cannot be watched, which is why this exists.** A
+   * custom state is deliberately not in the DOM, so there is no
+   * `MutationObserver` equivalent for `ElementInternals.states`. Await this
+   * instead.
+   *
+   * Separate from `updateComplete`, which resolves in the microtask checkpoint
+   * the suppression is still active in. That is the distinction `readyToMove`
+   * in `@fusion.dev/helix-testing` is written around.
+   *
+   * It never resolves where `requestAnimationFrame` never fires, which is a
+   * server, a hidden tab, and happy-dom. Callers that must not hang there race
+   * it against a timeout, as the happy-dom harness's `readyToMove` does. The
+   * browser harness's awaits it alone: a browser always runs the frame, and a
+   * timer beside it was a bet on how long one takes, which a busy run lost. (property only) (readonly)
+   *
+   * ## Slots
+   *
+   * Areas where markup can be added to the component.
+   *
+   * - `(default)`: What is being shown.
+   * - `description`: A line under it saying what it is.
+   *
+   * ## CSS Parts
+   *
+   * Custom selectors for styling elements within the component.
+   *
+   * - `item`: The box the content is shown in.
+   *
+   * ## CSS States
+   *
+   * These can be used to apply styling when a component is in a given state.
+   *
+   * - `current`: While this is the item the lightbox is showing.
+   * - `settled`: Set a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.
+   */
+  "helix-headless-lightbox-item": Partial<
+    HelixHeadlessLightboxItemProps &
+      HelixHeadlessLightboxItemSolidJsProps &
+      BaseProps<HelixHeadlessLightboxItem> &
+      BaseEvents<HelixHeadlessLightboxItem>
+  >;
+
+  /**
+   * **A lightbox is chrome around a picture rather than a picture.** It draws
+   * nothing of its own: what it shows is whatever the consumer opened, so this
+   * earns its place on the frame, the keyboard and the reading that says where in
+   * the set the reader is.
+   *
+   * **The modal half is the platform's.** A real `<dialog>` opened with
+   * `showModal()` brings the top layer, a backdrop, Escape and `inert` behind it,
+   * and this repository has already removed one hand-written focus trap for being
+   * worse than that: `inert` on the rest of the document is something no
+   * JavaScript trap can achieve. Every way it can close comes back through
+   * `requestOpen`, which is what `Dialog` and `Drawer` both do and for the reason
+   * they both give.
+   *
+   * **The set is this component's own and not `Carousel`'s.** A carousel is a
+   * track: a scroller with snap points, per-view arithmetic and stops it can rest
+   * between. A lightbox shows one thing at a time and has no track, so what it
+   * needs is which item is current, which is `active` and the same pair `Tabs`
+   * uses. The arrow keys move the picture under a reader whose focus stays in the
+   * dialog, which is also why `KeyboardNavigationController` is not the right
+   * tool: that one moves focus between focusable items, and these are pictures.
+   *
+   * **Chrome hides while the reader is still**, on `IdleController`, and comes
+   * back on a pointer move or a focus. `fullscreen` is `FullscreenController`, the
+   * same pair `Video` holds and the only two it shares.
+   *
+   * ## Attributes & Properties
+   *
+   * Component attributes and properties that can be applied to the element or by using JavaScript.
+   *
+   * - `idle-delay`/`idleDelay`: How long the reader may be still before the chrome hides, in milliseconds.
+   *
+   * Zero keeps it up, which is what a viewer with a caption worth reading
+   * wants. The wait is only ever about idling: whether anything else should
+   * keep the chrome up is the consumer's to decide with this.
+   * - `label`: Accessible name for the viewer.
+   * - `loop`: Whether walking past the end comes back to the beginning.
+   * - `status-label`/`statusLabel`: The reading that says where in the set the reader is, with `{index}` and
+   * `{count}` filled in.
+   *
+   * Announced rather than only drawn, because the picture changing under a
+   * reader who cannot see it is otherwise silent. A consumer who has their own
+   * counter in the chrome can empty this and say it themselves.
+   * - `active`: Which item is current, by its `value`.
+   *
+   * Not `option.active`, which is the option the keyboard is on: that is a
+   * different question from which one is chosen.
+   *
+   * Writing always applies, so `<helix-tabs active="one">` starts on that
+   * tab, and `default-active` is how markup says where to start without
+   * naming the current one.
+   * - `default-active`/`defaultActive`: Which item the markup declared current.
+   *
+   * Ignored once `active` is written.
+   * - `open`: Whether the element is open.
+   *
+   * One property, not two, so `dialog.open` answers the question anyone
+   * asking it meant. Writing always applies; `<helix-dialog open>` is the
+   * same statement in markup.
+   *
+   * **Not reflected, and that is required rather than tidy.** Reflection
+   * writes the resolved state back as an attribute, so an element that opened
+   * itself would put `open` on its own host: cloned, serialized for
+   * hydration, or diffed by a framework, it comes back holding whatever the
+   * last reader did rather than what the author wrote. `:state(open)` carries
+   * the resolved state for stylesheets, which is what the mirror is for.
+   * - `default-open`/`defaultOpen`: Whether the markup declared it open. Ignored once `open` is written.
+   * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
+   *
+   * **Named `whenSettled` because `settled` is taken four times over**, by
+   * Image, Splitter and both color controls, none of them about transitions. A
+   * base class takes the name every subclass then cannot use.
+   *
+   * **The state it reports cannot be watched, which is why this exists.** A
+   * custom state is deliberately not in the DOM, so there is no
+   * `MutationObserver` equivalent for `ElementInternals.states`. Await this
+   * instead.
+   *
+   * Separate from `updateComplete`, which resolves in the microtask checkpoint
+   * the suppression is still active in. That is the distinction `readyToMove`
+   * in `@fusion.dev/helix-testing` is written around.
+   *
+   * It never resolves where `requestAnimationFrame` never fires, which is a
+   * server, a hidden tab, and happy-dom. Callers that must not hang there race
+   * it against a timeout, as the happy-dom harness's `readyToMove` does. The
+   * browser harness's awaits it alone: a browser always runs the frame, and a
+   * timer beside it was a bet on how long one takes, which a busy run lost. (property only) (readonly)
+   *
+   * ## Events
+   *
+   * Events that will be emitted by the component.
+   *
+   * - `close`: Relayed, because the platform's own does not escape.
+   * - `helix-activate`: Fired once the shown item has moved, so the element already holds it.
+   * - `helix-before-activate`: Fired before the shown item changes, and cancelable. The only way to refuse one.
+   * - `helix-before-close`: Fired before it closes, and cancelable.
+   * - `helix-before-open`: Fired before it opens, and cancelable.
+   * - `toggle`: Says the state moved, carrying `newState` and `oldState`.
+   *
+   * ## Slots
+   *
+   * Areas where markup can be added to the component.
+   *
+   * - `(default)`: The items, which are `<helix-headless-lightbox-item>` elements.
+   * - `footer`: Chrome below the item, such as a counter or a thumbnail strip.
+   * - `header`: Chrome above the item, such as a title and a close button.
+   *
+   * ## Methods
+   *
+   * Methods that can be called to access component functionality.
+   *
+   * - `show() => void`: Opens the viewer, which makes the rest of the page inert.
+   * - `close() => void`: Asks to close, which a consumer may refuse.
+   * - `next() => void`: Shows the next item, or the first where it is past the end and looping.
+   * - `previous() => void`: Shows the previous item, or the last where it is past the start and looping.
+   * - `toggleFullscreen() => void`: Fills the screen with the viewer, or comes back.
+   * - `requestActive(next: string) => boolean`: Requests a new current item, and reports whether the request stood.
+   *
+   * Announces before it acts, so `preventDefault()` on the `helix-before-activate` is
+   * a refusal and nothing moves. Unlike a native control, nothing has moved
+   * by the time this runs, so refusing is simply not writing: there is
+   * nothing to put back. Nobody refusing means the set updates itself,
+   * whether or not a consumer declared `active`, a declared property being a
+   * seed and a correction.
+   * - `requestOpen(next: boolean) => boolean`: Requests an open-state change, and reports whether it was applied.
+   *
+   * Announces before it acts, so `preventDefault()` on the `helix-before-open` or
+   * `helix-before-close` is a refusal and nothing moves. Nobody refusing means the
+   * element opens or closes itself, whether or not a consumer declared
+   * `open`: a declared property is a seed and a correction, and a consumer
+   * who wants the decision for themselves refuses it and assigns their own.
+   * - `toggleOpen() => boolean`: Requests the opposite of the current state.
+   *
+   * ## CSS Parts
+   *
+   * Custom selectors for styling elements within the component.
+   *
+   * - `dialog`: The native dialog element.
+   * - `live`: The region that says which item is shown.
+   * - `viewport`: The box the current item is shown in.
+   *
+   * ## CSS States
+   *
+   * These can be used to apply styling when a component is in a given state.
+   *
+   * - `fullscreen`: While the viewer fills the screen.
+   * - `idle`: While the reader has been still long enough to hide the chrome.
+   * - `open`: While the viewer is open.
+   * - `settled`: Set a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.
+   */
+  "helix-headless-lightbox": Partial<
+    HelixHeadlessLightboxProps &
+      HelixHeadlessLightboxSolidJsProps &
+      BaseProps<HelixHeadlessLightbox> &
+      BaseEvents<HelixHeadlessLightbox>
+  >;
+
   /**
    * The chart for a shape rather than for a quantity, which is what decides the
    * one thing a bar chart is not allowed to do.