Published foldkit-ui API declarations for anchor.
./anchor
@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/anchor'
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;
anchorSetup
Positions a floating element relative to its button using Floating UI, then
returns a cleanup function. Designed to be called inside an `OnMount`
action: the consumer wraps the call in `Effect.sync` and stashes the
returned cleanup in the `Mount` result. When `interceptTab` is true
(default), Tab key in portal mode refocuses the button. Set to false for
components like Popover where Tab should navigate naturally within the
panel. When `focusAfterPosition` is true, the element is focused after the
first position computation clears visibility, deferred via
requestAnimationFrame so the element is painted before focus fires. That
focus passes `preventScroll`. Floating UI has already placed the element
in view, so a scroll-on-focus can only move the page under it, which
happens when the element's top edge lands within the document's
`scroll-padding-top`.
`focusSelector` optionally targets a descendant (e.g. a calendar grid
inside a popover panel) instead of the panel itself.
A portaled element whose button sits inside a `position: fixed` ancestor
is positioned with Floating UI's fixed strategy, so it stays under the
button while the page scrolls instead of moving with the document until
`autoUpdate` repositions it.
The side the element currently sits on is written to `data-placement`, so
CSS can react to it. When `isPlacementLocked` is true, the element keeps the
side that the first positioning picks, `flip` is removed from every later
update, and `data-placement` holds that locked side. Otherwise the attribute
tracks the side each update resolves to, including the ones `flip` moves.
anchorSetup: (element: Element, config: SetupConfig) => (() => void)
Padding
export type Padding = typeof Padding.Type;
Padding
Schema mirroring `@floating-ui/dom`'s `Padding` type: a uniform number or a
partial per-side object (`top`/`right`/`bottom`/`left`).
Padding: 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>;
}>]>
Placement
export type Placement = typeof Placement.Type;
Placement
Schema mirroring `@floating-ui/dom`'s `Placement` literal union: a side
(`top`/`right`/`bottom`/`left`) optionally suffixed with `-start` or `-end`.
Placement: Schema.Literals<readonly ["top", "right", "bottom", "left", "top-start", "top-end", "right-start", "right-end", "bottom-start", "bottom-end", "left-start", "left-end"]>
portalBackdrop
Relocates a click-outside backdrop and returns a cleanup function that
removes it again. Outside a `<dialog>`, it does what
`portalToContainingRoot` does. Inside a `<dialog>`, the backdrop moves to
directly before the element it was rendered in, which is the component
wrapper that holds the trigger. The backdrop then covers the dialog's
content, and the wrapper stays above it, so a click on a Combobox input
reaches the input while a click anywhere else in the dialog reaches the
backdrop. The wrapper must be positioned, for example `position:
relative`, which is also what keeps it above a backdrop in the containing
root. While the backdrop is there, it is a sibling of the wrapper, so
sibling-based selectors such as `:first-child` or Tailwind's `divide-y`
count it. Some CSS on an ancestor between the wrapper and the dialog
confines the backdrop to that ancestor: anything that makes the ancestor
the containing block for fixed-position elements, for example
`transform`, `scale`, `filter`, `backdrop-filter`, or `container-type`.
A click outside that ancestor then leaves the overlay open, and if it
also lands outside the dialog panel, it closes the whole dialog. A
backdrop rendered directly in the dialog goes into the dialog's portal
root instead. Designed to be called from inside an `OnMount` action,
like `portalToContainingRoot`.
portalBackdrop: (element: Element) => (() => void)
portalToContainingRoot
Relocates an element into a portal root and returns a cleanup function
that removes it again. Inside a `<dialog>`, the portal root is a div
appended to that dialog, so the element stays above the dialog's content
and interactive while a modal dialog makes everything outside it inert.
The cleanup removes that div once it is empty. Otherwise the portal root
is the shared `foldkit-portal-root` div within the element's containing
root: the shadow root when mounted inside one, otherwise `document.body`.
Either way the element escapes the clipping and stacking contexts of the
ancestors it leaves, and keeps its root's scoped styles. Use
`portalBackdrop` for a click-outside backdrop. Designed to be called from
inside an `OnMount` action: the consumer wraps the call in `Effect.sync`
and stashes the returned cleanup in the `Mount` result.
portalToContainingRoot: (element: Element) => (() => void)
SetupConfig
Config for `anchorSetup`.
- `buttonId`: id of the trigger to position against, resolved through the
element's own root.
- `anchor`: the static positioning options.
- `interceptTab`: returns focus to the trigger on Tab inside a portaled
panel. Defaults to `true`.
- `focusAfterPosition`: focuses the element once the first position
resolves. Defaults to `false`.
- `focusSelector`: focuses this descendant instead of the element itself.
Read only when `focusAfterPosition` is true.
- `arrowId`: id of an arrow element inside the panel, resolved through the
element's own root. An id that resolves to an element outside the panel is
ignored, and any element type is accepted, so an `<svg>` arrow works. When
it resolves, the arrow's offset along the panel edge is published as
`--arrow-x` and `--arrow-y`, with the axis the placement does not use
reset to `initial`, and the panel is no longer made a scroll container,
since scrolling clips on both axes and an arrow sits half outside the
panel's box.
- `arrowPadding`: distance in pixels the arrow keeps from the panel's
corners. Defaults to `0`. Separate from `anchor.padding`, which is the
viewport padding.
export type SetupConfig = Readonly<{
buttonId: string;
anchor: AnchorConfig;
interceptTab?: boolean;
focusAfterPosition?: boolean;
focusSelector?: string;
arrowId?: string;
arrowPadding?: number;
}>;