Documentation navigation

Published API · 0.1.0-rc.1

themes · components/dialog

Published themes API declarations for components/dialog.

./components/dialog

@wsagency/wseffect-themes · MIT · source · MIT license · WS-AGENCY-NOTICE

This entry point is published in @wsagency/wseffect-themes@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-themes/components/dialog'

Exported declarations

close

Programmatically closes the dialog.

close: (model: Model) => UpdateReturn

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

embed

embed: <Message>(h: HtmlBuilder<Message>, config: EmbedConfig<Message>) => Html

EmbedConfig

export type EmbedConfig<Message> = Readonly<{
    slotId: string;
    model: DialogModel;
    toParentMessage: (message: DialogMessage) => Message;
    title: string;
    description?: string;
    size?: (typeof sizes)[number];
    content: (h: HtmlBuilder<Message>) => ReadonlyArray<Html | string>;
}>;

fold

fold: <ParentModel, ParentMessage, ParentOutMessage, Input = never>(config: Omit<Update.ChildFoldWithDerivedParentOutMessage<ParentModel, ParentMessage, DialogModel, Input, DialogMessage, DialogOutMessage, ParentOutMessage>, 'update'>) => Update.FoldWithOutMessage<ParentModel, ParentMessage, {
    readonly _tag: "CompletedCloseDialog";
} | {
    readonly _tag: "CompletedReleaseDialogResources";
} | {
    readonly _tag: "FailedAcquireResources";
} | {
    readonly _tag: "FailedShowDialog";
} | {
    readonly _tag: "GotAnimationMessage";
    readonly message: {
        readonly _tag: "CompletedWaitForPaint";
        readonly generation: number;
    } | {
        readonly _tag: "EndedAnimation";
        readonly generation: number;
    } | {
        readonly _tag: "Hid";
    } | {
        readonly _tag: "Showed";
    };
} | {
    readonly _tag: "RequestedClose";
} | {
    readonly _tag: "RequestedOpen";
} | {
    readonly _tag: "SucceededAcquireResources";
} | {
    readonly _tag: "SucceededShowDialog";
} | {
    readonly _tag: "Unmounted";
}, ParentOutMessage, never>

init

Creates a closed dialog model from a config. Use `boot` when the Dialog should open as the application starts.

init: (config: InitConfig) => Model

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

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: {};
}>

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

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";
    };
}>

Rendered component example

Dialog

Release notes

The new workspace is ready.

Example usage
import * as Themes from '@wsagency/wseffect-themes'
import * as SliderRange from '@wsagency/wseffect-themes/components/slider/range'
import * as Option from 'effect/Option'
import { defineView } from '@wsagency/wseffect-foldkit/submodel'
import { inertHtml, type HtmlBuilder } from '@wsagency/wseffect-foldkit/html'

const example = (h: HtmlBuilder<unknown>) => Themes.Dialog.embed(h, { slotId: 'release-notes-example', model: Themes.Dialog.open(Themes.Dialog.init({ id: 'release-notes-example' })).model, toParentMessage: (message) => message, title: 'Release notes', content: (builder) => [builder.p([], ['The new workspace is ready.'])] })