Published foldkit-ui API declarations for dialog.
./dialog
@wsagency/wseffect-foldkit-ui · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES
This entry point is published in @wsagency/wseffect-foldkit-ui@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.
import * as Wseffect from '@wsagency/wseffect-foldkit-ui/dialog'
Exported declarations
AcquireResources
Reacquires an initially visible Dialog's framework resources when its
element mounts, including after development Model preservation restores an
open Dialog without replaying initialization Commands. A successful
acquisition also resumes a preserved animation transition from its current
phase.
AcquireResources: Mount.MountDefinitionWithArgs<"AcquireResources", {
id: Schema.String;
focusSelector: Schema.String;
}, {
readonly _tag: "SucceededAcquireResources";
} | {
readonly _tag: "FailedAcquireResources";
}>
boot
Creates a Dialog and opens it through the normal update path. Use the
returned Model and Commands during application initialization so the
initially visible Dialog acquires modal isolation, scroll locking, focus
management, stack registration, and runtime-owned cleanup.
boot: (config: InitConfig) => UpdateReturn
close
Programmatically closes the dialog.
close: (model: Model) => UpdateReturn
Closed
export type Closed = typeof OutMessage.Closed.Type;
CloseDialog
Calls `close()` on the native dialog element and unlocks page scroll when
the close released the resources `ShowDialog` installed. A close that runs
before the show has installed them leaves the lock alone. When the show
then fails, it releases the lock itself. When the show succeeds, update
closes the dialog again. If the dialog element is gone by the time the
close runs, the Command calls `Dom.releaseDialogResources` instead. That
releases the scroll lock, focus trap, return focus, and stack entry if the
dialog still holds them. The background is restored before return focus.
CloseDialog: Command.CommandDefinitionWithArgs<"CloseDialog", {
id: Schema.String;
}, Effect.Effect<{
readonly _tag: "CompletedCloseDialog";
}, never, never>>
CompletedCloseDialog
export type CompletedCloseDialog = typeof Message.CompletedCloseDialog.Type;
CompletedReleaseDialogResources
export type CompletedReleaseDialogResources = typeof Message.CompletedReleaseDialogResources.Type;
descriptionId
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.
descriptionId: (model: Model) => string
FailedAcquireResources
export type FailedAcquireResources = typeof Message.FailedAcquireResources.Type;
FailedShowDialog
export type FailedShowDialog = typeof Message.FailedShowDialog.Type;
init
Creates a closed dialog model from a config. Use `boot` when the Dialog
should open as the application starts.
init: (config: InitConfig) => Model
InitConfig
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.
export type InitConfig = Readonly<{
id: string;
isAnimated?: boolean;
/** CSS selector for the element that receives focus when the dialog opens.
* A selector-based override of the `initialFocus` RenderInfo marker, for the
* cases a spread-on marker cannot express: an element whose id you do not
* own, or a descendant selector. Takes precedence over `initialFocus`. With
* neither set, focus falls to the first focusable element. */
focusSelector?: string;
}>;
Message
export type Message = typeof Message.Type;
Message
Union of all messages the dialog component can produce.
Message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
readonly RequestedOpen: {};
readonly RequestedClose: {};
readonly SucceededShowDialog: {};
readonly FailedShowDialog: {};
readonly SucceededAcquireResources: {};
readonly FailedAcquireResources: {};
readonly CompletedCloseDialog: {};
readonly Unmounted: {};
readonly CompletedReleaseDialogResources: {};
readonly GotAnimationMessage: {
message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
readonly Showed: {};
readonly Hid: {};
readonly CompletedWaitForPaint: {
generation: Schema.Number;
};
readonly EndedAnimation: {
generation: Schema.Number;
};
}>;
};
}>
Model
export type Model = typeof Model.Type;
Model
Schema for the dialog component's state, tracking its unique ID, open/closed status, animation support, and animation lifecycle phase.
Model: Schema.Struct<{
readonly id: Schema.String;
readonly isOpen: Schema.Boolean;
readonly isAnimated: Schema.Boolean;
readonly animation: Schema.Struct<{
readonly id: Schema.String;
readonly isShowing: Schema.Boolean;
readonly transitionState: Schema.Literals<readonly ["Idle", "EnterStart", "EnterAnimating", "LeaveStart", "LeaveAnimating"]>;
readonly transitionGeneration: Schema.Number;
}>;
readonly maybeFocusSelector: Schema.Option<Schema.String>;
}>
open
Programmatically opens the dialog.
open: (model: Model) => UpdateReturn
Opened
export type Opened = typeof OutMessage.Opened.Type;
OutMessage
export type OutMessage = typeof OutMessage.Type;
OutMessage
Union of out-messages the dialog component can produce.
OutMessage: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
readonly Opened: {};
readonly Closed: {};
}>
ReleaseDialogResources
Releases the framework hygiene the dialog holds while open (scroll lock,
focus trap, return focus, stack entry, background isolation) when the
element unmounts without a purposeful close. Calling it after
`CloseDialog` released those resources is a no-op.
ReleaseDialogResources: Command.CommandDefinitionWithArgs<"ReleaseDialogResources", {
id: Schema.String;
}, Effect.Effect<{
readonly _tag: "CompletedReleaseDialogResources";
}, never, never>>
RenderInfo
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.
export type RenderInfo = Readonly<{
dialog: ReadonlyArray<ChildAttribute>;
backdrop: ReadonlyArray<ChildAttribute>;
panel: ReadonlyArray<ChildAttribute>;
title: ReadonlyArray<ChildAttribute>;
description: ReadonlyArray<ChildAttribute>;
initialFocus: ReadonlyArray<ChildAttribute>;
closeButton: ReadonlyArray<ChildAttribute>;
isVisible: boolean;
}>;
RequestedClose
export type RequestedClose = typeof Message.RequestedClose.Type;
RequestedOpen
export type RequestedOpen = typeof Message.RequestedOpen.Type;
ShowDialog
Opens the native dialog element through `Dom.showDialog`, then locks page
scroll when that call acquired the dialog resources. `Dom.showDialog`
makes the background inert while leaving DevTools available as a separate
developer overlay. It calls `show()` rather than `showModal()` so DevTools
can stay interactive, layers the dialog with a high z-index, and traps
focus. For an unhandled Escape on the topmost Dialog, the
helper dispatches a `CustomEvent` named `cancel`; the Dialog view maps that
signal to `RequestedClose` while suppressing native `cancel` events. The
Dialog component supplies its own backdrop. If the dialog element is gone
by the time the show runs, the Command reports `FailedShowDialog` without
taking the scroll lock. The update function then closes the Model. The
acquisition becomes uninterruptible after the committed element is found,
so modal resources and the scroll lock cannot split. A concurrent
lifecycle acquisition reuses the resources already held by the id.
ShowDialog: Command.CommandDefinitionWithArgs<"ShowDialog", {
id: Schema.String;
focusSelector: Schema.String;
}, Effect.Effect<{
readonly _tag: "SucceededShowDialog";
} | {
readonly _tag: "FailedShowDialog";
}, never, never>>
SucceededAcquireResources
export type SucceededAcquireResources = typeof Message.SucceededAcquireResources.Type;
SucceededShowDialog
export type SucceededShowDialog = typeof Message.SucceededShowDialog.Type;
titleId
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.
titleId: (model: Model) => string
Unmounted
export type Unmounted = typeof Message.Unmounted.Type;
update
Processes a Dialog Message and returns the next Model and optional Commands.
update: (model: Model, message: Message) => Readonly<{
model: {
readonly id: string;
readonly isOpen: boolean;
readonly isAnimated: boolean;
readonly animation: {
readonly id: string;
readonly isShowing: boolean;
readonly transitionState: "EnterAnimating" | "EnterStart" | "Idle" | "LeaveAnimating" | "LeaveStart";
readonly transitionGeneration: number;
};
readonly maybeFocusSelector: Option.Option<string>;
};
commands?: Update.Commands<{
readonly _tag: "RequestedOpen";
} | {
readonly _tag: "RequestedClose";
} | {
readonly _tag: "SucceededShowDialog";
} | {
readonly _tag: "FailedShowDialog";
} | {
readonly _tag: "SucceededAcquireResources";
} | {
readonly _tag: "FailedAcquireResources";
} | {
readonly _tag: "CompletedCloseDialog";
} | {
readonly _tag: "Unmounted";
} | {
readonly _tag: "CompletedReleaseDialogResources";
} | {
readonly _tag: "GotAnimationMessage";
readonly message: {
readonly _tag: "CompletedWaitForPaint";
readonly generation: number;
} | {
readonly _tag: "EndedAnimation";
readonly generation: number;
} | {
readonly _tag: "Hid";
} | {
readonly _tag: "Showed";
};
}, never>;
outMessage?: {
readonly _tag: "Opened";
} | {
readonly _tag: "Closed";
};
}>
view
Renders a headless modal dialog backed by the native `<dialog>` element.
`ShowDialog` and the dialog's Mount open it through `Dom.showDialog`,
isolate the background, trap focus, and handle Escape on the topmost
dialog. The component supplies its own backdrop.
view: import("@wsagency/wseffect-foldkit/submodel").View<{
readonly id: string;
readonly isOpen: boolean;
readonly isAnimated: boolean;
readonly animation: {
readonly id: string;
readonly isShowing: boolean;
readonly transitionState: "EnterAnimating" | "EnterStart" | "Idle" | "LeaveAnimating" | "LeaveStart";
readonly transitionGeneration: number;
};
readonly maybeFocusSelector: Option.Option<string>;
}, {
readonly _tag: "RequestedOpen";
} | {
readonly _tag: "RequestedClose";
} | {
readonly _tag: "SucceededShowDialog";
} | {
readonly _tag: "FailedShowDialog";
} | {
readonly _tag: "SucceededAcquireResources";
} | {
readonly _tag: "FailedAcquireResources";
} | {
readonly _tag: "CompletedCloseDialog";
} | {
readonly _tag: "Unmounted";
} | {
readonly _tag: "CompletedReleaseDialogResources";
} | {
readonly _tag: "GotAnimationMessage";
readonly message: {
readonly _tag: "CompletedWaitForPaint";
readonly generation: number;
} | {
readonly _tag: "EndedAnimation";
readonly generation: number;
} | {
readonly _tag: "Hid";
} | {
readonly _tag: "Showed";
};
}, Readonly<{
toView: (render: RenderInfo) => Html;
hasDescription?: boolean;
}>>
ViewInputs
Per-render view inputs passed to `view` via `h.submodel`'s `viewInputs` field.
export type ViewInputs = Readonly<{
toView: (render: RenderInfo) => Html;
hasDescription?: boolean;
}>;