Documentation navigation

Published API · 0.1.0-rc.1

foldkit-ui · tooltip, tooltip/group

Published foldkit-ui API declarations for tooltip, tooltip/group.

./tooltip

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

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;

AnchorTooltip

The anchor-positioning Mount this Tooltip renders on its panel.

AnchorTooltip: Mount.MountDefinitionWithArgs<"AnchorTooltip", {
    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>;
    }>;
}, {
    readonly _tag: "CompletedAnchorTooltip";
}>

BlurredTrigger

export type BlurredTrigger = typeof Message.BlurredTrigger.Type;

EnteredTrigger

export type EnteredTrigger = typeof Message.EnteredTrigger.Type;

FocusedTrigger

export type FocusedTrigger = typeof Message.FocusedTrigger.Type;

Hidden

export type Hidden = typeof OutMessage.Hidden.Type;

init

Creates an initial tooltip model from a config. Defaults to hidden.

init: (config: InitConfig) => Model

InitConfig

Configuration for creating a tooltip model with `init`.

export type InitConfig = Readonly<{
    id: string;
    showDelay?: Duration.Input;
}>;

LeftTrigger

export type LeftTrigger = typeof Message.LeftTrigger.Type;

Message

export type Message = typeof Message.Type;

Message

Union of all messages the tooltip component can produce.

Message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
    readonly EnteredTrigger: {};
    readonly LeftTrigger: {};
    readonly FocusedTrigger: {};
    readonly BlurredTrigger: {};
    readonly PressedEscape: {};
    readonly PressedPointerOnTrigger: {
        pointerType: Schema.String;
    };
    readonly CompletedWaitBeforeShowing: {
        version: Schema.Number;
    };
    readonly CompletedAnchorTooltip: {};
}>

Model

export type Model = typeof Model.Type;

Model

Schema for the tooltip component's state. `isOpen` is visibility; `isHovered` tracks pointer on trigger; `isFocused` tracks tooltip-affirming focus on the trigger (focus arriving without a preceding mouse press, like keyboard, touch, or pen; mouse-click-induced focus is excluded since it doesn't affirm the user wants the tooltip visible); `isDismissed` suppresses re-opening after the user dismissed the tooltip (via Escape) until they disengage (leave or blur). `showDelay` is the hover-to-show duration. `maybeLastPointerType` records the most recent pointer type that pressed the trigger, so a mouse-click-induced focus can be distinguished from other focus.

Model: Schema.Struct<{
    readonly id: Schema.String;
    readonly isOpen: Schema.Boolean;
    readonly isHovered: Schema.Boolean;
    readonly isFocused: Schema.Boolean;
    readonly isDismissed: Schema.Boolean;
    readonly showDelay: Schema.DurationFromMillis;
    readonly pendingShowVersion: Schema.Number;
    readonly maybeLastPointerType: Schema.Option<Schema.String>;
}>

OutMessage

export type OutMessage = typeof OutMessage.Type;

OutMessage

Union of out-messages the tooltip component can produce.

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

PressedEscape

export type PressedEscape = typeof Message.PressedEscape.Type;

PressedPointerOnTrigger

export type PressedPointerOnTrigger = typeof Message.PressedPointerOnTrigger.Type;

reflectShowDelay

Reflects an externally-sourced hover show-delay onto the Model without emitting an OutMessage. Use to mirror an external config value (a user preference, a restored setting) onto the tooltip.

reflectShowDelay: Reflect<Model, Duration.Input>

RenderInfo

Render-time payload published to the consumer's `toView`. - `trigger`: attribute bundle for the trigger element. Carries the hover/focus/keyboard handlers + ARIA `aria-describedby` linking to the panel. - `panel`: attribute bundle for the panel element. Carries the `role="tooltip"`, the anchor Mount that positions the panel via Floating UI, and a `data-open` attribute when visible. - `isVisible`: derived state. The consumer decides whether to render the panel conditionally on this.

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

Shown

export type Shown = typeof OutMessage.Shown.Type;

triggerId

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

triggerId: (id: string) => string

update

Processes a Tooltip Message and returns the next Model, optional Commands, and an optional OutMessage. `Shown`/`Hidden` fire only on `isOpen` transitions, so consumers don't get spurious events for messages that only update hover/focus/delay state without changing visibility.

update: (model: Model, message: Message) => Update.ReturnWithOutMessage<Model, Message, OutMessage>

view

Renders a headless tooltip with an anchored non-interactive panel. Shows on hover (after delay) or focus (from keyboard, touch, or pen; mouse-click focus is excluded). Hides on leave, blur, or Escape.

view: import("@wsagency/wseffect-foldkit/submodel").View<{
    readonly id: string;
    readonly isOpen: boolean;
    readonly isHovered: boolean;
    readonly isFocused: boolean;
    readonly isDismissed: boolean;
    readonly showDelay: Duration.Duration;
    readonly pendingShowVersion: number;
    readonly maybeLastPointerType: Option.Option<string>;
}, {
    readonly _tag: "BlurredTrigger";
} | {
    readonly _tag: "EnteredTrigger";
} | {
    readonly _tag: "FocusedTrigger";
} | {
    readonly _tag: "LeftTrigger";
} | {
    readonly _tag: "PressedEscape";
} | {
    readonly _tag: "CompletedWaitBeforeShowing";
    readonly version: number;
} | {
    readonly _tag: "CompletedAnchorTooltip";
} | {
    readonly _tag: "PressedPointerOnTrigger";
    readonly pointerType: string;
}, Readonly<{
    anchor: AnchorConfig;
    toView: (render: RenderInfo) => Html;
    isDisabled?: boolean;
    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;
    ariaLabel?: string;
    ariaLabelledBy?: string;
}>;

WaitBeforeShowing

Waits for the tooltip's show delay before emitting `CompletedWaitBeforeShowing`.

WaitBeforeShowing: Command.CommandDefinitionWithArgs<"WaitBeforeShowing", {
    delay: Schema.DurationFromMillis;
    version: Schema.Number;
}, Effect.Effect<{
    readonly _tag: "CompletedWaitBeforeShowing";
    readonly version: number;
}, never, never>>

./tooltip/group

@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/tooltip/group'

Exported declarations

GroupConfig

export type GroupConfig = Readonly<{
    openDelay: number;
    skipDelay: number;
}>;

init

init: (config?: GroupConfig) => Model

Message

export type Message = typeof Message.Type;

Message

Message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
    readonly TooltipOpened: {
        now: Schema.Number;
    };
    readonly TooltipClosed: {
        now: Schema.Number;
    };
    readonly SkipExpired: {
        version: Schema.Number;
    };
}>

Model

export type Model = typeof Model.Type;

Model

Model: Schema.Struct<{
    readonly isSkipping: Schema.Boolean;
    readonly expiryVersion: Schema.Number;
    readonly skipDelay: Schema.Number;
}>

reflectShowDelay

reflectShowDelay: (model: Model, config?: GroupConfig) => number

SkipDelay

SkipDelay: Command.CommandDefinitionWithArgs<"TooltipGroupSkipDelay", {
    version: Schema.Number;
    delay: Schema.Number;
}, Effect.Effect<{
    readonly _tag: "SkipExpired";
    readonly version: number;
}, never, never>>

update

update: (model: Model, message: Message) => Update.Return<Model, Message>