On this pageFunctions
Ui/Dialog
/**
* Returns the framework-managed description id, the
* `-dialog-description` suffix on `model.id`.
*
* The primary path is spreading `RenderInfo`'s `description` onto your
* description element (`h.p([...description], [...])`), which carries this id
* for you. Reach for this helper only when you need the id as a value outside
* `toView`: a Command that calls `getElementById`, a cross-element
* `aria-describedby`, or a test. When the description is rendered, set
* `ViewInputs.hasDescription` so the dialog points at this id. Do not
* hand-roll the id string.
*/
(model: {
animation: {
id: string
isShowing: boolean
transitionGeneration: number
transitionState: "Idle" | "EnterStart" | "EnterAnimating" | "LeaveStart" | "LeaveAnimating"
}
id: string
isAnimated: boolean
isOpen: boolean
maybeFocusSelector: Option<string>
}): string/**
* Returns the framework-managed id the dialog's `aria-labelledby` points at,
* the `-dialog-title` suffix on `model.id`.
*
* The primary path is spreading `RenderInfo`'s `title` onto your heading
* (`h.h2([...title], [...])`), which carries this id for you. Reach for this
* helper only when you need the id as a value outside `toView`: a Command that
* calls `getElementById`, a cross-element `aria-describedby`, or a test. Do not
* hand-roll the id string.
*/
(model: {
animation: {
id: string
isShowing: boolean
transitionGeneration: number
transitionState: "Idle" | "EnterStart" | "EnterAnimating" | "LeaveStart" | "LeaveAnimating"
}
id: string
isAnimated: boolean
isOpen: boolean
maybeFocusSelector: Option<string>
}): string/**
* Configuration for creating a dialog model with `init`. The `id` must be
* non-empty and unique within the document: it keys the dialog element, its
* ARIA references, and the framework's per-dialog resource cleanup, so a
* duplicate or empty id breaks cleanup accounting.
*
* The dialog derives framework-managed ids from this `id`: `-dialog-title`,
* `-dialog-description`, and `-panel` (the animation panel). Spread
* `RenderInfo`'s `title` / `description` onto your heading and description
* elements rather than constructing those ids yourself.
*/
type InitConfig = Readonly<{
focusSelector: string
id: string
isAnimated: boolean
}>/**
* Render-time payload published to the consumer's `toView`.
*
* - `dialog`: attributes for the native `<dialog>` element. Carries
* the id, ARIA labelling and modal state, `open` prop, positioning style, a `cancel` handler
* that prevents a file picker's native cancellation from closing the dialog
* while mapping `Dom.showDialog`'s Escape signal to `RequestedClose`,
* an `OnMount` acquisition that restores modal resources for an initially
* visible or development-preserved Dialog, and an `OnUnmount` backstop that
* releases framework hygiene (scroll lock, focus trap, background
* isolation, return focus) if the element is removed from the DOM while
* still open, such as navigating away from a route-keyed subtree.
* The consumer MUST render an `h.dialog(...)` element so the framework
* can open and close it, and so the unmount backstop can fire.
* - `backdrop`: attributes for the backdrop element. Includes the
* Animation data attributes and the `OnClick` handler that closes
* the dialog on outside-click (suppressed while a leave animation
* is in progress).
* - `panel`: attributes for the panel element. Includes the panel id
* (`${model.id}-panel`) and the Animation data attributes.
* - `title`: attributes for the accessible-name heading. Carries the
* framework-managed id the dialog's `aria-labelledby` points at. Spread
* onto your heading element (`h.h2([...title], [...])`) so labelling
* wires up without hand-rolling the id.
* - `description`: attributes for the description element. Carries the
* framework-managed id referenced by `aria-describedby` when
* `ViewInputs.hasDescription` is true. Spread onto your description element
* (`h.p([...description], [...])`).
* - `initialFocus`: attributes for the element that should receive focus when
* the dialog opens. Spread onto that element (`h.input([...initialFocus])`).
* A configured `focusSelector` (see `init`) takes precedence, and focus
* falls back to the default when no element carries the group.
* - `closeButton`: attributes for an in-panel close control such as a Cancel
* or dismiss button. Carries the `OnClick` handler that closes the
* dialog (suppressed while a leave animation is in progress). Spread
* onto your own button so a plain close needs no parent message. Sets
* `type="button"` so that a close control inside a `form` element in the
* panel closes without also submitting the form. Spread a later `h.Type`
* to override it.
* - `isVisible`: derived from `isOpen` and the Animation
* `transitionState`. The consumer renders backdrop + panel only
* while this is true.
*/
type RenderInfo = Readonly<{
backdrop: ReadonlyArray<ChildAttribute>
closeButton: ReadonlyArray<ChildAttribute>
description: ReadonlyArray<ChildAttribute>
dialog: ReadonlyArray<ChildAttribute<Mount.RequirementsOf<typeof mounts>>>
initialFocus: ReadonlyArray<ChildAttribute>
isVisible: boolean
panel: ReadonlyArray<ChildAttribute>
title: ReadonlyArray<ChildAttribute>
}>/** Per-render view inputs passed to `view` via `h.block`'s `viewInputs` field. */
type ViewInputs = Readonly<{
hasDescription: boolean
toView: (render: RenderInfo) => Html
}>/**
* Data attribute the dialog places on the `initialFocus` RenderInfo group and
* focuses on open.
*/
const initialFocusMarkerAttribute: "foldkit-dialog-initial-focus"