Skip to main content
On this pageFunctions

Ui/Dialog

Functions

descriptionId

functionsource
/**
 * 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

titleId

functionsource
/**
 * 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

Types

InitConfig

typesource
/**
 * 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
}>

RenderInfo

typesource
/**
 * 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>
}>

ViewInputs

typesource
/** Per-render view inputs passed to `view` via `h.block`'s `viewInputs` field. */
type ViewInputs = Readonly<{
  hasDescription: boolean
  toView: (render: RenderInfo) => Html
}>

Constants

initialFocusMarkerAttribute

constsource
/**
 * Data attribute the dialog places on the `initialFocus` RenderInfo group and
 *  focuses on open.
 */
const initialFocusMarkerAttribute: "foldkit-dialog-initial-focus"

initialFocusMarkerSelector

constsource
/**
 * Selector for initialFocusMarkerAttribute, focused against the open
 *  dialog when no `focusSelector` is configured.
 */
const initialFocusMarkerSelector: "[data-foldkit-dialog-initial-focus]"