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