Documentation navigation

Published API · 0.1.0-rc.1

foldkit-ui · popover

Published foldkit-ui API declarations for popover.

./popover

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

Exported declarations

AnchorConfig

Static configuration for anchor-based positioning of a floating element relative to a button.

AnchorConfig: Schema.Struct<{
    readonly placement: Schema.optional<Schema.Literals<readonly ["top", "right", "bottom", "left", "top-start", "top-end", "right-start", "right-end", "bottom-start", "bottom-end", "left-start", "left-end"]>>;
    readonly gap: Schema.optional<Schema.Number>;
    readonly offset: Schema.optional<Schema.Number>;
    readonly padding: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.Struct<{
        readonly top: Schema.optionalKey<Schema.Number>;
        readonly right: Schema.optionalKey<Schema.Number>;
        readonly bottom: Schema.optionalKey<Schema.Number>;
        readonly left: Schema.optionalKey<Schema.Number>;
    }>]>>;
    readonly portal: Schema.optional<Schema.Boolean>;
    readonly isPlacementLocked: Schema.optional<Schema.Boolean>;
}>

AnchorConfig

export type AnchorConfig = typeof AnchorConfig.Type;

AnchorPopover

The anchor-positioning Mount this Popover renders on its panel. Exposed so Scene tests can call `Scene.Mount.resolve(AnchorPopover, CompletedAnchorPopover())` to acknowledge the mount produced by the rendered panel.

AnchorPopover: Mount.MountDefinitionWithArgs<"AnchorPopover", {
    buttonId: Schema.String;
    anchor: Schema.Struct<{
        readonly placement: Schema.optional<Schema.Literals<readonly ["top", "right", "bottom", "left", "top-start", "top-end", "right-start", "right-end", "bottom-start", "bottom-end", "left-start", "left-end"]>>;
        readonly gap: Schema.optional<Schema.Number>;
        readonly offset: Schema.optional<Schema.Number>;
        readonly padding: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.Struct<{
            readonly top: Schema.optionalKey<Schema.Number>;
            readonly right: Schema.optionalKey<Schema.Number>;
            readonly bottom: Schema.optionalKey<Schema.Number>;
            readonly left: Schema.optionalKey<Schema.Number>;
        }>]>>;
        readonly portal: Schema.optional<Schema.Boolean>;
        readonly isPlacementLocked: Schema.optional<Schema.Boolean>;
    }>;
    focusSelector: Schema.optional<Schema.String>;
    arrowId: Schema.optional<Schema.String>;
    arrowPadding: Schema.optional<Schema.Number>;
}, {
    readonly _tag: "CompletedAnchorPopover";
}>

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

BlurredPanel

export type BlurredPanel = typeof Message.BlurredPanel.Type;

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

Closed

export type Closed = typeof OutMessage.Closed.Type;

DetectMovementOrAnimationEnd

Detects whether the popover button moved or the leave animation ended. Whichever comes first; both outcomes signal the Animation submodel that leave is complete.

DetectMovementOrAnimationEnd: Command.CommandDefinitionWithArgs<"DetectMovementOrAnimationEnd", {
    id: Schema.String;
    generation: Schema.Number;
}, Effect.Effect<{
    readonly _tag: "GotAnimationMessage";
    readonly message: {
        readonly _tag: "CompletedWaitForPaint";
        readonly generation: number;
    } | {
        readonly _tag: "EndedAnimation";
        readonly generation: number;
    } | {
        readonly _tag: "Hid";
    } | {
        readonly _tag: "Showed";
    };
}, never, never>>

FocusButton

Moves focus back to the popover button after closing.

FocusButton: Command.CommandDefinitionWithArgs<"FocusButton", {
    id: Schema.String;
}, Effect.Effect<{
    readonly _tag: "CompletedFocusButton";
}, never, never>>

FocusPanel

Moves focus to the popover panel after opening.

FocusPanel: Command.CommandDefinitionWithArgs<"FocusPanel", {
    id: Schema.String;
}, Effect.Effect<{
    readonly _tag: "CompletedFocusPanel";
}, never, never>>

IgnoredMouseClick

export type IgnoredMouseClick = typeof Message.IgnoredMouseClick.Type;

InertOthers

Marks all elements outside the popover as inert for modal behavior.

InertOthers: Command.CommandDefinitionWithArgs<"InertOthers", {
    id: Schema.String;
}, Effect.Effect<{
    readonly _tag: "CompletedInertOthers";
}, never, never>>

init

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

init: (config: InitConfig) => Model

InitConfig

Configuration for creating a popover model with `init`. `isAnimated` enables animation coordination (default `false`). `isModal` locks page scroll and inerts other elements when open (default `false`). `contentFocus` hands focus ownership to the consumer. The panel is not focusable and does not close on blur, so the consumer must focus a descendant on open and close the popover on its own blur rules (default `false`).

export type InitConfig = Readonly<{
    id: string;
    isAnimated?: boolean;
    isModal?: boolean;
    contentFocus?: boolean;
}>;

LockScroll

Prevents page scrolling while the popover is open in modal mode.

LockScroll: Command.CommandDefinitionNoArgs<"LockScroll", Effect.Effect<{
    readonly _tag: "CompletedLockScroll";
}, never, never>>

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

Opened

export type Opened = typeof OutMessage.Opened.Type;

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

PortalPopoverBackdrop

The backdrop-portaling Mount this Popover renders. Exposed so Scene tests can call `Scene.Mount.resolve(PortalPopoverBackdrop, CompletedPortalPopoverBackdrop())` to acknowledge the mount produced by the rendered backdrop.

PortalPopoverBackdrop: Mount.MountDefinitionNoArgs<"PortalPopoverBackdrop", {
    readonly _tag: "CompletedPortalPopoverBackdrop";
}>

PressedPointerOnButton

export type PressedPointerOnButton = typeof Message.PressedPointerOnButton.Type;

RenderInfo

Render-time payload published to the consumer's `toView`. - `button`: attribute bundle for the trigger button. - `panel`: attribute bundle for the floating panel. Includes the anchor Mount that positions the panel via Floating UI, ARIA linkage to the button, and panel keydown/blur handlers. - `backdrop`: attribute bundle for the modal backdrop. Includes the portal Mount that moves the backdrop to document.body. Inside a `<dialog>`, it moves the backdrop to directly before the element it is rendered in, so render it inside the positioned wrapper that holds the button. The backdrop's OnClick closes the popover. - `arrow`: attribute bundle for an arrow element inside the panel. Carries the id the anchor Mount resolves and hides the element from assistive technology. Spread it onto your own element and place it with the `--arrow-x` and `--arrow-y` custom properties Anchor publishes on the panel. Nothing renders until you do. - `isVisible`: derived from `isOpen` and the Animation `transitionState`. The consumer renders the panel + backdrop only while this is true.

export type RenderInfo = Readonly<{
    button: ReadonlyArray<ChildAttribute>;
    panel: ReadonlyArray<ChildAttribute>;
    backdrop: ReadonlyArray<ChildAttribute>;
    arrow: ReadonlyArray<ChildAttribute>;
    isVisible: boolean;
}>;

RequestedClose

export type RequestedClose = typeof Message.RequestedClose.Type;

RequestedOpen

export type RequestedOpen = typeof Message.RequestedOpen.Type;

RestoreInert

Removes the inert attribute from elements outside the popover.

RestoreInert: Command.CommandDefinitionWithArgs<"RestoreInert", {
    id: Schema.String;
}, Effect.Effect<{
    readonly _tag: "CompletedRestoreInert";
}, never, never>>

SuppressedSpaceScroll

export type SuppressedSpaceScroll = typeof Message.SuppressedSpaceScroll.Type;

UnlockScroll

Re-enables page scrolling after the popover closes.

UnlockScroll: Command.CommandDefinitionNoArgs<"UnlockScroll", Effect.Effect<{
    readonly _tag: "CompletedUnlockScroll";
}, never, never>>

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

view

Renders a headless popover with a trigger button and a floating panel.

view: import("@wsagency/wseffect-foldkit/submodel").View<{
    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>;
}, {
    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";
    };
}, Readonly<{
    anchor: AnchorConfig;
    toView: (render: RenderInfo) => Html;
    isDisabled?: boolean;
    focusSelector?: string;
    arrowPadding?: number;
    ariaLabel?: string;
    ariaLabelledBy?: string;
}>>

ViewInputs

Per-render view inputs passed to `view` via `h.submodel`'s `viewInputs` field.

export type ViewInputs = Readonly<{
    anchor: AnchorConfig;
    toView: (render: RenderInfo) => Html;
    isDisabled?: boolean;
    focusSelector?: string;
    arrowPadding?: number;
    ariaLabel?: string;
    ariaLabelledBy?: string;
}>;