Documentation navigation

Published API · 0.1.0-rc.1

foldkit-ui · anchor

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