@pg-labs-incubator/cobweb 0.0.0-stage → 0.0.2

package/target/tsc/surface/surface.d.ts

@@ -0,0 +1,192 @@
+import type { JSX } from "solid-js";
+import type { DomProps } from "..";
+import type { InteractableComponent, InteractableProps } from "../state";
+import { InteractableController } from "../state/controller";
+import "../container/elevation-shadow.css";
+import "./surface.css";
+/**
+ * Material surface color roles.
+ *
+ * | Value                         | Container role              | Content role         |
+ * | ----------------------------- | --------------------------- | -------------------- |
+ * | `"surface"`                   | `surface`                   | `onSurface`          |
+ * | `"surface-dim"`               | `surfaceDim`                | `onSurface`          |
+ * | `"surface-bright"`            | `surfaceBright`             | `onSurface`          |
+ * | `"surface-container-lowest"`  | `surfaceContainerLowest`    | `onSurface`          |
+ * | `"surface-container-low"`     | `surfaceContainerLow`       | `onSurface`          |
+ * | `"surface-container"`         | `surfaceContainer`          | `onSurface`          |
+ * | `"surface-container-high"`    | `surfaceContainerHigh`      | `onSurface`          |
+ * | `"surface-container-highest"` | `surfaceContainerHighest`   | `onSurface`          |
+ * | `"inverse"`                   | `inverseSurface`            | `inverseOnSurface`   |
+ * | `"primary"`                   | `primary`                   | `onPrimary`          |
+ * | `"secondary"`                 | `secondary`                 | `onSecondary`        |
+ * | `"tertiary"`                  | `tertiary`                  | `onTertiary`         |
+ * | `"error"`                     | `error`                     | `onError`            |
+ */
+export type SurfaceColor = "surface" | "surface-dim" | "surface-bright" | "surface-container-lowest" | "surface-container-low" | "surface-container" | "surface-container-high" | "surface-container-highest" | "inverse" | "primary" | "secondary" | "tertiary" | "error";
+/**
+ * Properties accepted by {@link Surface}.
+ */
+export type SurfaceBaseProps = DomProps<HTMLDivElement, Omit<JSX.HTMLAttributes<HTMLDivElement>, "role" | "tabindex" | "aria-disabled" | "aria-selected">> & {
+    /**
+     * Surface color role.
+     *
+     * The color applies to the container; content uses the matching content role. See
+     * {@link SurfaceColor}.
+     *
+     * @defaultValue `"surface-container"`
+     */
+    color?: SurfaceColor | undefined;
+    /**
+     * Material elevation level.
+     *
+     * The level selects the `cw-Elevation` shadow of the surface.
+     *
+     * @defaultValue `0`
+     */
+    elevation?: 0 | 1 | 2 | 3 | 4 | 5 | undefined;
+    /**
+     * Named corner shape or a CSS `border-radius` value.
+     *
+     * Named shapes map to the `cw-CornerRadius` roles. When omitted, the `cw-Surface-shape` role
+     * applies, which an expressive theme enlarges; an explicit shape is never overridden by a
+     * theme.
+     */
+    shape?: "none" | "extra-small" | "small" | "medium" | "large" | "extra-large" | "full" | string | undefined;
+    /**
+     * Surface is a button.
+     *
+     * When `true`, the surface has the `button` role, is keyboard focusable, activates with Enter
+     * and Space, and renders hover, focus, and press state layers.
+     *
+     * @defaultValue `false`
+     */
+    clickable?: boolean | undefined;
+    /**
+     * Surface is an independent toggle.
+     *
+     * When `true`, the surface has the `button` role and an `aria-pressed` state which activation
+     * toggles. Activating a nested interactive element, or a nested surface, does not toggle it.
+     *
+     * @defaultValue `false`
+     */
+    selectable?: boolean | undefined;
+    /**
+     * Controlled selection state.
+     *
+     * Supplying this property, even as `undefined`, makes selection controlled: activation
+     * requests a change through {@link SurfaceBaseProps.onSelectedChange | `onSelectedChange`}
+     * and the parent must update this property.
+     */
+    selected?: boolean | undefined;
+    /**
+     * Initial selection state of an uncontrolled selectable surface.
+     *
+     * @remarks
+     * This is **not** reactive.
+     *
+     * @defaultValue `false`
+     */
+    defaultSelected?: boolean | undefined;
+    /**
+     * Surface is disabled.
+     *
+     * A disabled interactive surface is removed from sequential focus, does not activate, and
+     * ignores programmatic clicks. A disabled surface is rendered at the `disabledOpacity` role.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Sequential focus index.
+     *
+     * An interactive surface defaults to `0`; a disabled interactive surface always uses `-1`.
+     */
+    tabIndex?: number | undefined;
+    /**
+     * Handle activation of a selectable surface.
+     *
+     * Invoked for controlled and uncontrolled surfaces, *before* an uncontrolled surface updates
+     * its own state.
+     *
+     * @remarks
+     * This is **not** reactive.
+     *
+     * @param selected - requested selection state
+     * @param event - activating click event
+     */
+    onSelectedChange?: ((selected: boolean, event: Event) => void) | undefined;
+};
+/**
+ * Surface properties, including the standard Cobweb interaction callbacks.
+ */
+export type SurfaceProps = InteractableProps<SurfaceBaseProps>;
+/**
+ * Client controller of a {@link Surface}.
+ *
+ * The controller owns the surface's classes, button semantics and keyboard activation. While a
+ * surface is neither clickable nor selectable, it installs no activation listeners and enables no
+ * interaction states.
+ */
+export declare class SurfaceController extends InteractableController<SurfaceBaseProps> {
+    #private;
+    /**
+     * Construct a new `SurfaceController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: SurfaceBaseProps);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Toggle a selectable surface when it, rather than a nested control, is activated.
+     *
+     * @param event - interaction event received by the controller
+     */
+    protected onEvent(event: Event): void;
+    /**
+     * Render the component's element tree.
+     *
+     * @param children - nested component children, possibly an accessor
+     * @returns rendered component elements
+     * @see {@link ../dom/client#DomController.render}
+     */
+    protected render(children: JSX.Element): JSX.Element;
+    /**
+     * Release activation listeners when the controller is disposed.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+}
+/**
+ * Material surface container.
+ *
+ * A surface is a container on a Material color role, with an optional corner shape and elevation.
+ * It can also act as a button, or as an independent toggle, while keeping native keyboard and ARIA
+ * semantics available to assistive technology.
+ *
+ * # States
+ *
+ * A {@link SurfaceBaseProps.clickable | clickable} or {@link SurfaceBaseProps.selectable |
+ * selectable} surface has the `button` role and enters the {@link FocusState | focus}, {@link
+ * HoverState | hover}, and {@link PressState | press} interaction states, unless it is {@link
+ * SurfaceBaseProps.disabled | disabled}. A selectable surface exposes its selection through
+ * `aria-pressed`; a selected surface uses the selected container and content colors.
+ *
+ * # Design
+ *
+ * Surface design is controlled through the [`cw-Surface`](./surface.yaml) component design
+ * attribute. The `cw-Surface-clickable`, `cw-Surface-selectable`, `cw-Surface-selected`, and
+ * `cw-Surface-disabled` classes reflect the corresponding properties, and `cw-Surface-<state>`
+ * classes reflect the entered interaction state. State layers use the `cw-State` layer opacities
+ * on the content color, and the focus indicator uses the `cw-State` focus indicator roles.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const Surface: InteractableComponent<SurfaceBaseProps>;

package/target/tsc/text/index.css.d.ts

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MPL-2.0
+
+export {};

package/target/tsc/text/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Typography and typescale definitions.
+ *
+ * This module defines the {@link Text} component, which renders text according to the baseline
+ * and emphasized styles of the [`cw-Typescale`](./typescale.yaml) design attribute, and the {@link
+ * Typography} component, which selects the [`cw-LineHeight`](./line-height.yaml) category of a
+ * subtree by language.
+ *
+ * Fonts are named by the [`cw-Typeface`](./typeface.yaml) design attribute; Cobweb does not
+ * bundle them, so applications load the named fonts, for example with `@font-face` rules. The
+ * root stylesheet defines the `cw-LineHeight` properties referenced by every typescale role.
+ *
+ * @packageDocumentation
+ */
+export type { TextEmphasis, TextProps, TextRole, TextSize, Typescale } from "./text";
+export { Text } from "./text";
+export type { TypographyHeight, TypographyProps } from "./typography";
+export { Typography } from "./typography";

package/target/tsc/text/text.css.d.ts

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MPL-2.0
+
+export {};

package/target/tsc/text/text.d.ts

@@ -0,0 +1,94 @@
+import type { JSX, VoidProps } from "solid-js";
+import type { DomComponent, DomProps } from "..";
+import "./text.css";
+/**
+ * {@link Text} display role enumeration.
+ *
+ * This equals the top-level group roles of the [`cw-Typescale`](./typescale.yaml) design
+ * attribute.
+ *
+ * @see {@link Typescale}
+ */
+export type TextRole = "body" | "display" | "headline" | "label" | "title";
+/**
+ * {@link Text} size enumeration.
+ *
+ * This equals the {@link TextRole | role} size group roles of the
+ * [`cw-Typescale`](./typescale.yaml) design attribute.
+ *
+ * @see {@link Typescale}
+ */
+export type TextSize = "large" | "medium" | "small";
+/**
+ * {@link Text} emphasis enumeration.
+ *
+ * Emphasized styles use the same role and size as their baseline counterparts, with a heavier
+ * weight and the tracking specified by Material 3 Expressive.
+ *
+ * @see {@link Typescale}
+ */
+export type TextEmphasis = "emphasized";
+/**
+ * Typescale a {@link Text | text} is rendered with.
+ *
+ * Typescale may be a {@link TextRole | role}, {@link TextSize | size}, and optional {@link
+ * TextEmphasis | emphasis}, delimited by hyphens, or just a role. When set to just a role, the
+ * default `"large"` size and baseline style are applied.
+ *
+ * @see {@link TextProps.scale}
+ */
+export type Typescale = `${TextRole}-${TextSize}-${TextEmphasis}` | `${TextRole}-${TextSize}` | TextRole;
+/**
+ * {@link Text} component properties.
+ */
+export type TextProps = VoidProps<DomProps<HTMLSpanElement, JSX.HTMLElementTags["span"]>> & {
+    /**
+     * Typescale text is rendered with.
+     *
+     * @defaultValue `"body-large"`
+     */
+    scale?: Typescale;
+    /**
+     * Text content.
+     */
+    value?: string;
+};
+/**
+ * Text rendered with {@link Typescale | typescale}.
+ *
+ * This renders {@link TextProps.value | `props.value`} with typescale CSS properties based on
+ * {@link TextProps.scale | `props.scale`}.
+ *
+ * ```tsx
+ * import type { JSX, VoidProps } from "solid-js";
+ *
+ * import { Text } from "@pg-labs-incubator/cobweb/text";
+ *
+ * export default function(_props: VoidProps): JSX.Element {
+ * return <>
+ *     <Text value="Body (large): --cw-Typescale-body-large" />
+ *     <Text
+ *         scale="body-small"
+ *         value="Body (small): --cw-Typescale-body-small" />
+ *     <Text
+ *         scale="label"
+ *         value="Label (large): --cw-Typescale-label-large" />
+ * </>;
+ * }
+ * ```
+ *
+ * # Design
+ *
+ * The [`cw-Typescale`](./typescale.yaml) design attribute controls the typescale CSS properties
+ * of the rendered text. Typescale size and roles can be controlled using `props.scale`. Fonts are
+ * selected by the [`cw-Typeface`](./typeface.yaml) design attribute and are not bundled; see its
+ * description for loading them. Line heights follow the language within a {@link
+ * ./typography#Typography | typography} scope.
+ *
+ * Note that the rendered text is *not* selectable or interactable. If selection or interaction
+ * is required, `user-select`, `pointer-events`, and `touch-action` should be used.
+ *
+ * @param props - text properties
+ * @returns rendered element
+ */
+export declare const Text: DomComponent<TextProps>;

package/target/tsc/text/typography.css.d.ts

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MPL-2.0
+
+export {};

package/target/tsc/text/typography.d.ts

@@ -0,0 +1,82 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps } from "..";
+import "./typography.css";
+/**
+ * Line height category of a {@link Typography} scope.
+ *
+ * Categories select line heights of the [`cw-LineHeight`](./line-height.yaml) design attribute:
+ *
+ * | Category       | Line heights                                                         |
+ * | -------------- | -------------------------------------------------------------------- |
+ * | `"auto"`       | Category of the language, see {@link Typography}.                   |
+ * | `"small"`      | Default role values, Material's type scale line heights.             |
+ * | `"medium"`     | `medium` theme, for dense and tall scripts.                          |
+ * | `"large"`      | `large` theme, for Burmese and Telugu.                               |
+ * | `"extraLarge"` | `extraLarge` theme, for script styles such as Nastaliq.              |
+ */
+export type TypographyHeight = "auto" | "small" | "medium" | "large" | "extraLarge";
+/**
+ * {@link Typography} component properties.
+ */
+export type TypographyProps = DomProps<HTMLDivElement, JSX.HTMLElementTags["div"]> & {
+    /**
+     * Line height category applied within the scope.
+     *
+     * An explicit category applies to the whole scope, including nested elements declaring another
+     * language, until a nested scope selects its own height. `"auto"` selects the category by
+     * language, also within a scope of an explicit category.
+     *
+     * @defaultValue `"auto"`
+     */
+    height?: TypographyHeight;
+};
+/**
+ * Typography scope selecting line heights by language.
+ *
+ * Text rendered with [`cw-Typescale`](./typescale.yaml) roles uses the line heights of the
+ * [`cw-LineHeight`](./line-height.yaml) design attribute. Outside of a scope, these are the small
+ * category: Material's type scale line heights, which suit English-like scripts. Within a scope,
+ * the scope element and every nested element with a `lang` attribute select the first of:
+ *
+ * 1. the {@link TypographyProps.height | height} of the nearest scope, unless `"auto"`;
+ *
+ * 2. the category of the script subtag of the nearest language tag: medium for dense and tall
+ *    scripts (Arabic, Bengali, Devanagari, Ethiopic, Gujarati, Gurmukhi, Han, Hangul, Japanese
+ *    kana, Kannada, Khmer, Lao, Malayalam, Odia, Sinhala, Tamil, Thai, and Tibetan), large for
+ *    Burmese and Telugu, and small for Cyrillic, Greek, Hebrew, and Latin, except Vietnamese;
+ *
+ * 3. the category of the language: medium for languages written in a dense or tall script by
+ *    default and for Vietnamese, large for Burmese and Telugu, and small for every other
+ *    language, including undetermined ones.
+ *
+ * Nastaliq requires an explicit `"extraLarge"` height, since an Arabic script or language tag does
+ * not identify the font style. Baseline and emphasized styles share their line heights, while
+ * `cw-Typescale` line height overrides and authored `line-height` declarations retain their normal
+ * priority. Categories are resolved by CSS alone, so the server renders the same markup regardless
+ * of the language of the document.
+ *
+ * ```tsx
+ * import { Text, Typography } from "@pg-labs-incubator/cobweb/text";
+ *
+ * <Typography attr:lang="ar">
+ *     <Text value="مرحبا" />
+ *     <Typography height="extraLarge" attr:lang="ur">
+ *         <Text value="خوش آمدید" />
+ *     </Typography>
+ * </Typography>
+ * ```
+ *
+ * # Design
+ *
+ * The categories are the default values and the `medium`, `large`, and `extraLarge` themes of the
+ * [`cw-LineHeight`](./line-height.yaml) design attribute. Categories are a Cobweb web adaptation;
+ * Material's type scale defines the small category only.
+ *
+ * # Styles
+ *
+ * The scope element has the `cw-Typography` class.
+ *
+ * @param props - typography scope properties
+ * @returns rendered scope element
+ */
+export declare const Typography: DomComponent<TypographyProps>;

package/target/tsc/util/box-side.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Top {@link BoxSide | side} of box, equivalent to `block-start`.
+ *
+ * @see {@link BoxSide}
+ */
+export declare const BoxTop = 0;
+/**
+ * Right {@link BoxSide | side} of box, equivalent to `inline-end`.
+ *
+ * @see {@link BoxSide}
+ */
+export declare const BoxRight = 1;
+/**
+ * Bottom {@link BoxSide | side} of box, equivalent to `block-end`.
+ *
+ * @see {@link BoxSide}
+ */
+export declare const BoxBottom = 2;
+/**
+ * Left {@link BoxSide | side} of box, equivalent to `inline-start`.
+ *
+ * @see {@link BoxSide}
+ */
+export declare const BoxLeft = 3;
+/**
+ * Union of box sides.
+ *
+ * Each side discriminant evaluates to an integer equal to the common CSS value order for the
+ * respective side. For example, the
+ * [`border-color`](https://developer.mozilla.org/en-US/docs/Web/CSS/border-color) property can
+ * be assigned to a list of values which style the top, right, bottom, and left border color.
+ *
+ * @see {@link LogicalBoxSides}
+ */
+export type BoxSide = typeof BoxBottom | typeof BoxLeft | typeof BoxRight | typeof BoxTop;
+/**
+ * Table mapping logical box {@link BoxSide | side} to physical side.
+ *
+ * The {@link BoxTop}, {@link BoxRight}, {@link BoxBottom}, and {@link BoxLeft} constants can be
+ * used to retrieve the physical side block-start, inline-end, block-end, and inline-start logical
+ * sides map to, respectively.
+ *
+ * @see {@link BoxSide}
+ * @see {@link logicalBoxSidesOf}
+ */
+export type LogicalBoxSides = [
+    top: BoxSide,
+    right: BoxSide,
+    bottom: BoxSide,
+    left: BoxSide
+];
+/**
+ * Determine whether a box side lies on the `x` or `y` axis.
+ *
+ * @param side - side to test
+ * @returns `0` or `1` if `side` lies on `x` or `y` axis, respectively
+ */
+export declare function axisOfBoxSide(side: BoxSide): 0 | 1;
+/**
+ * Determine the logical box side {@link LogicalBoxSides | mapping} based on the current style of
+ * an element.
+ *
+ * This determines the logical to physical side mapping for `elem`, or pseudo-element `pseudoElem`
+ * of `elem`, based on the `direction` and `writing-mode` CSS properties currently styled for the
+ * element or pseudo-element. Unknown writing modes are mapped as `horizontal-tb`.
+ *
+ * In a {@link solid-js/web#isServer | server} environment, or when the document of `elem` has no
+ * browsing context, this returns the mapping of the `horizontal-tb` writing mode and the `ltr`
+ * direction.
+ *
+ * @param elem - element to determine logical side mapping of
+ * @param pseudoElem - pseudo-element selector, within `elem`, to resolve logical sides of, or
+ * `undefined` to resolve logical sides of `elem`
+ * @returns logical to physical side mapping
+ */
+export declare function logicalBoxSidesOf(elem: Element, pseudoElem?: string): LogicalBoxSides;

package/target/tsc/util/debug.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Fail if {@link solid-js#DEV | debugging} is enabled *and* condition evaluates to `false`.
+ *
+ * If `cond` is a `boolean`, it is validated as-is; otherwise, `cond` must be a function which
+ * evaluates to a `boolean`, which is then validated.
+ *
+ * @param cond - condition to validate or function whose condition should be evaluated
+ * @param msg - message to fail with
+ * @throws {@link Error} debugging is enabled and `cond` is `false`
+ */
+export declare function assertDebug(cond: boolean | (() => boolean), msg?: string): asserts cond;
+/**
+ * Print message if {@link solid-js#DEV | debugging} is enabled.
+ *
+ * This invokes `console.log()` with `msg` and `args` if, and only if, debugging is enabled.
+ *
+ * @param msg - message to print
+ * @param args - additional message arguments to print
+ */
+export declare function printDebug(msg?: unknown, ...args: unknown[]): void;

package/target/tsc/util/dom.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Resolve the value an element attribute is assigned to.
+ *
+ * Attribute values are resolved as follows:
+ *
+ * | `value`               | ARIA and keyword attributes | Other attributes |
+ * | --------------------- | --------------------------- | ---------------- |
+ * | `undefined` or `null` | `null`                      | `null`           |
+ * | `true`                | `true` state keyword        | `""`             |
+ * | `false`               | `false` state keyword       | `null`           |
+ * | `number` or `string`  | text of `value`             | text of `value`  |
+ *
+ * ARIA states and properties, such as `aria-expanded` or `aria-pressed`, distinguish a `"false"`
+ * value from a missing attribute, unlike boolean attributes, such as `disabled` or `hidden`; their
+ * state keywords are `"true"` and `"false"`. The state keywords of other enumerated attributes
+ * are listed in {@link KEYWORD_ATTRIBUTES}.
+ *
+ * @param name - name of attribute
+ * @param value - value to resolve
+ * @returns value the attribute is assigned to, or `null` if the attribute is removed
+ */
+export declare function attributeValueOf(name: string, value: boolean | number | string | null | undefined): string | null;
+/**
+ * Set attribute for element or remove attribute from element.
+ *
+ * The attribute is assigned to the value {@link attributeValueOf | resolved} for `value`, or is
+ * removed if `value` resolves to `null`. Values of any type other than `boolean`, `number`,
+ * `string`, `null`, or `undefined` leave the attribute unchanged.
+ *
+ * @param elem - element to set attribute on
+ * @param name - name of attribute
+ * @param value - value to set to
+ * @see {@link attributeValueOf}
+ */
+export declare function setAttribute(elem: Element, name: string, value: unknown): void;

package/target/tsc/util/event.d.ts

@@ -0,0 +1,93 @@
+/**
+ * User-agent supports passive event listeners.
+ *
+ * @remarks
+ * In a {@link solid-js/web#isServer | server} environment, this always evaluates to `false`.
+ */
+export declare const HAS_PASSIVE_EVENT_LISTENERS: boolean;
+/**
+ * Transform event listener options to options supported by user-agent.
+ *
+ * @param opts - options to transform
+ * @param _target - ignored; accepted so that callers may pass the target the listener is
+ * registered with
+ * @returns `opts` if, and only if, user-agent {@link HAS_PASSIVE_EVENT_LISTENERS | supports}
+ * passive events; otherwise, `opts.capture` or `false` if `opts.capture` was not specified,
+ * respectively
+ */
+export declare function eventListenerOptionsOf(opts: AddEventListenerOptions, _target?: EventTarget): AddEventListenerOptions | boolean;
+/**
+ * Defer a component request until bubbling consumers had an opportunity to cancel an event.
+ *
+ * Components listen to events on their elements directly, while SolidJS invokes delegated event
+ * handlers, such as `onClick` and `event:click` handlers, from a listener of the document, which
+ * is invoked *after* component listeners. This defers the request of a component, received
+ * through `event`, until delegated handlers, and listeners of the window, had an opportunity to
+ * veto the request by cancelling `event` with `preventDefault()`. If `event` was cancelled by
+ * then, the request is discarded. Otherwise, the request is accepted: the default action of
+ * `event` is cancelled, if `preventDefault` is `true`, and `action` is invoked in a microtask.
+ *
+ * If `event` bubbles to a document, requests settle at the first of:
+ *
+ * 1. `event` reaching the window, once listeners of the window, registered before `event` was
+ *    dispatched, were invoked.
+ *
+ * 2. the end of propagation at the document, if propagation was stopped by then, for example, by
+ *    a delegated handler, once listeners of the document were invoked.
+ *
+ * 3. a microtask, queued when `stopPropagation()` or `stopImmediatePropagation()` is invoked on
+ *    `event`; this observes propagation stopped before `event` reaches the document.
+ *
+ * 4. a task, or a microtask if `event` is not trusted, queued when the request is deferred, if
+ *    none of the above is observed, for example, as propagation was stopped through the
+ *    `cancelBubble` setter, or a listener of the window deferred the request.
+ *
+ * If `event` does not bubble, does not propagate to a document, or was stopped from propagating
+ * further, no delegated handler can observe it, and requests settle in a microtask.
+ *
+ * The default action of `event` can be cancelled only while `event` is dispatched. Microtasks
+ * run once the JavaScript execution context stack is empty. When the user agent dispatches an
+ * event, for example, in response to user input, the stack is empty after each listener returns,
+ * so a microtask queued by a listener runs *before* the next listener is invoked, while the event
+ * is still dispatched. When script dispatches an event, for example, through `dispatchEvent()`,
+ * `click()`, or `focus()`, the stack is empty only after that script returns, which is *after*
+ * the event was dispatched; requests which settle in a microtask still invoke their actions, but
+ * can no longer cancel the default action.
+ *
+ * @param event - event the request is received through
+ * @param _root - ignored, as the propagation path is resolved from `event`; accepted so that
+ * callers may pass the element whose listener received `event`
+ * @param action - function to invoke when the request is accepted
+ * @param preventDefault - `true` if, and only if, the default action of `event` is cancelled when
+ * the request is accepted; defaults to `true`
+ * @remarks
+ * Deferred requests are subject to the following:
+ *
+ * - Any invocation of `preventDefault()` before requests settle vetoes them, including those not
+ *   intended to veto a component request, such as that of a router handling a click on a link.
+ *
+ * - Requests deferred for the same event settle together, in the order they were deferred. The
+ *   first accepted request which cancels the default action consumes the event, and requests
+ *   deferred after it are discarded; for example, of nested components handling the same event,
+ *   the innermost component consumes the event.
+ *
+ * - An action which tests `event.defaultPrevented` must not cancel the default action
+ *   (`preventDefault` is `false`); otherwise, the action observes its own cancellation.
+ *
+ * - Listeners invoked after requests settled, such as listeners of the same target as the
+ *   listener which stopped propagation, cannot veto requests.
+ */
+export declare function deferAfterDelegatedCancellation(event: Event, _root: Element | null, action: () => void, preventDefault?: boolean): void;
+/**
+ * Test whether a pointer leaving an element moves into the element, or one of its descendants.
+ *
+ * Chromium dispatches `pointerleave` to a pseudo-element the pointer leaves for its originating
+ * element, or a descendant of it, while a capturing `pointerleave` listener is installed on an
+ * ancestor. The event is retargeted to the originating element, although the pointer is still
+ * within it: such a leave toward its own subtree is not a leave of the element.
+ *
+ * @param event - `pointerleave` event received
+ * @param elem - element `event` is targeted at
+ * @returns `true` if, and only if, the related target of `event` is `elem`, or a descendant of it
+ */
+export declare function isLeaveWithin(event: PointerEvent, elem: Element): boolean;

package/target/tsc/util/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Utility definitions.
+ *
+ * @packageDocumentation
+ */
+export type { BoxSide, LogicalBoxSides } from "./box-side";
+export { BoxBottom, BoxLeft, BoxRight, BoxTop, axisOfBoxSide, logicalBoxSidesOf } from "./box-side";
+export { assertDebug, printDebug } from "./debug";
+export { attributeValueOf, setAttribute } from "./dom";
+export { HAS_PASSIVE_EVENT_LISTENERS, deferAfterDelegatedCancellation, eventListenerOptionsOf } from "./event";
+export { checkArgument, checkArray, checkBoolean, checkBrowser, checkNumber, checkObject, checkServer, checkState, checkString, checkValueDefined } from "./preconditions";
+export { consumeProps, isPropReactive } from "./reactive";