Documentation navigation

Published API · 0.1.0-rc.1

themes · components/popover

Published themes API declarations for components/popover.

./components/popover

@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/popover'

Exported declarations

arrowId

Returns the bare DOM id of the popover arrow, derived from the popover's base id. The `arrow` bundle already carries this id, so reach for this when you need the id on its own, such as asserting the panel Mount's `arrowId` argument in a Scene test.

arrowId: (id: string) => string

buttonId

Returns the bare DOM id of the popover trigger button, derived from the popover's base id. Use this to associate an external label with the trigger via a native `<label for={Popover.buttonId(id)}>` or an `aria-labelledby` reference.

buttonId: (id: string) => string

close

Programmatically closes the popover. When it was open, updates the Model and returns focus and modal Commands plus a `Closed` OutMessage. When it was already closed, it is a no-op: no Commands and no OutMessage.

close: (model: Model) => UpdateReturn

embed

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

EmbedConfig

export type EmbedConfig<Message> = Readonly<{
    slotId: string;
    model: UiPopover.Model;
    toParentMessage: (message: UiPopover.Message) => Message;
    viewInputs: ViewInputs<Message>;
}>;

fold

fold: <ParentModel, ParentMessage, ParentOutMessage>(config: Omit<Update.ChildFoldWithDerivedParentOutMessage<ParentModel, ParentMessage, UiPopover.Model, UiPopover.Message, UiPopover.Message, UiPopover.OutMessage, ParentOutMessage>, 'update'>) => Update.FoldWithOutMessage<ParentModel, ParentMessage, UiPopover.Message, ParentOutMessage>

init

Creates an initial popover model from a config. Defaults to closed.

init: (config: InitConfig) => Model

Message

export type Message = typeof Message.Type;

Message

Union of all messages the popover component can produce.

Message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
    readonly RequestedOpen: {};
    readonly RequestedClose: {};
    readonly BlurredPanel: {};
    readonly PressedPointerOnButton: {
        pointerType: Schema.String;
        button: Schema.Number;
    };
    readonly CompletedFocusPanel: {};
    readonly CompletedFocusButton: {};
    readonly CompletedLockScroll: {};
    readonly CompletedUnlockScroll: {};
    readonly CompletedInertOthers: {};
    readonly CompletedRestoreInert: {};
    readonly IgnoredMouseClick: {};
    readonly SuppressedSpaceScroll: {};
    readonly CompletedAnchorPopover: {};
    readonly CompletedPortalPopoverBackdrop: {};
    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 popover component's state, tracking open/closed status and animation lifecycle.

Model: Schema.Struct<{
    readonly id: Schema.String;
    readonly isOpen: Schema.Boolean;
    readonly isAnimated: Schema.Boolean;
    readonly isModal: Schema.Boolean;
    readonly contentFocus: 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 maybeLastButtonPointerType: Schema.Option<Schema.String>;
}>

open

Programmatically opens the Popover, updating the Model and returning focus and modal Commands plus an `Opened` OutMessage.

open: (model: Model) => UpdateReturn

OutMessage

export type OutMessage = typeof OutMessage.Type;

OutMessage

Union of OutMessages the popover component can produce. Handle open and close transitions in the `foldOutMessage` of the Popover's `Update.foldChild` config.

OutMessage: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
    readonly Opened: {};
    readonly Closed: {};
}>

update

Processes a Popover Message and returns the next Model, optional Commands, and an optional OutMessage.

update: (model: Model, message: Message) => Readonly<{
    model: {
        readonly id: string;
        readonly isOpen: boolean;
        readonly isAnimated: boolean;
        readonly isModal: boolean;
        readonly contentFocus: boolean;
        readonly animation: {
            readonly id: string;
            readonly isShowing: boolean;
            readonly transitionState: "EnterAnimating" | "EnterStart" | "Idle" | "LeaveAnimating" | "LeaveStart";
            readonly transitionGeneration: number;
        };
        readonly maybeLastButtonPointerType: Option.Option<string>;
    };
    commands?: Update.Commands<{
        readonly _tag: "RequestedOpen";
    } | {
        readonly _tag: "RequestedClose";
    } | {
        readonly _tag: "BlurredPanel";
    } | {
        readonly _tag: "PressedPointerOnButton";
        readonly pointerType: string;
        readonly button: number;
    } | {
        readonly _tag: "IgnoredMouseClick";
    } | {
        readonly _tag: "SuppressedSpaceScroll";
    } | {
        readonly _tag: "CompletedAnchorPopover";
    } | {
        readonly _tag: "CompletedFocusButton";
    } | {
        readonly _tag: "CompletedFocusPanel";
    } | {
        readonly _tag: "CompletedInertOthers";
    } | {
        readonly _tag: "CompletedLockScroll";
    } | {
        readonly _tag: "CompletedPortalPopoverBackdrop";
    } | {
        readonly _tag: "CompletedRestoreInert";
    } | {
        readonly _tag: "CompletedUnlockScroll";
    } | {
        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: "Closed";
    } | {
        readonly _tag: "Opened";
    };
}>

ViewInputs

export type ViewInputs<Message> = Readonly<{
    anchor?: AnchorConfig;
    trigger: ReadonlyArray<Html | string>;
    content: ReadonlyArray<Html | string>;
    ariaLabel?: string;
    ariaLabelledBy?: string;
    isDisabled?: boolean;
    focusSelector?: string;
    arrowPadding?: number;
}>;

Rendered component example

Popover
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.Popover.embed(h, { slotId: 'filter-popover-example', model: Themes.Popover.open(Themes.Popover.init({ id: 'filter-popover-example' })).model, toParentMessage: (message) => message, viewInputs: { trigger: [h.span([], ['Filters'])], content: [h.p([], ['Choose a date range.'])] } })