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

package/target/tsc/state/component.d.ts

@@ -0,0 +1,276 @@
+import type { ClientDomProps, DomComponent, DomProps, RenderServerDom } from "..";
+import type { InteractionState } from "./state";
+import { InteractableController } from "./controller";
+import "./component.css";
+/**
+ * Interaction user-trigger event handler.
+ *
+ * These handlers are invoked when an event, which *may* trigger entry into or exit from an
+ * interaction {@link ./state#InteractionState | state}, is received. The event is accepted from
+ * the element which the interaction state accepts events for: focus events always target the
+ * function element, and pointer enter and leave events always target the style element. Click
+ * events may target a descendant of either element, unless a nested native control or
+ * interactable owns them. Handlers are invoked when the event is triggered, irrespective of
+ * whether the interaction state of the event is {@link
+ * ./controller#InteractableController.isInteractionStateEnabled | enabled}.
+ *
+ * @typeParam E - event type
+ * @typeParam P - component properties type
+ * @see {@link InteractableProps}
+ *
+ * @param event - native event received by the component
+ * @param cont - controller owning the interaction
+ */
+export type InteractionEventHandler<E extends Event, P extends DomProps> = (event: E, cont: InteractableController<P>) => void;
+/**
+ * Interaction {@link ./state#InteractionState | state} handler.
+ *
+ * These handlers are invoked *after* an interaction state is {@link
+ * InteractableProps.onInteractionStateEntered | entered} into or {@link
+ * InteractableProps.onInteractionStateExited | exited} from.
+ *
+ * @typeParam P - component properties type
+ * @see {@link InteractableProps.onInteractionStateEntered}
+ * @see {@link InteractableProps.onInteractionStateExited}
+ *
+ * @param state - interaction state entered or exited
+ * @param cont - controller owning the state
+ * @param event - originating event, if any
+ */
+export type InteractionStateHandler<P extends DomProps> = (state: InteractionState, cont: InteractableController<P>, event?: Event) => void;
+/**
+ * Interactable {@link InteractableComponent | component} properties.
+ *
+ * @typeParam P - underlying DOM component properties type
+ */
+export type InteractableProps<P extends DomProps = DomProps> = P & {
+    /**
+     * Handle entry of pointing device into hit test boundaries of the component.
+     *
+     * The handler specified, if any, is invoked *before* any {@link ./state#HoverState |
+     * hover} state *may* have been entered into.
+     *
+     * @remarks
+     * This is **not** reactive.
+     */
+    readonly onPointerEnter?: InteractionEventHandler<PointerEvent, P> | undefined;
+    /**
+     * Handle exit of pointing device from hit test boundaries of the component.
+     *
+     * The handler specified, if any, is invoked *before* any {@link ./state#HoverState |
+     * hover} state *may* have been exited from.
+     *
+     * @remarks
+     * This is **not** reactive.
+     */
+    readonly onPointerLeave?: InteractionEventHandler<PointerEvent, P> | undefined;
+    /**
+     * Handle activation of the component.
+     *
+     * The handler specified, if any, is invoked *before* any {@link ./state#PressState |
+     * press} state *may* have been exited from.
+     *
+     * @remarks
+     * This is **not** reactive.
+     */
+    readonly onClick?: InteractionEventHandler<MouseEvent, P> | undefined;
+    /**
+     * Handle component receiving focus.
+     *
+     * The handler specified, if any, is invoked *before* any {@link ./state#FocusState |
+     * focus} state *may* have been entered into.
+     *
+     * @remarks
+     * This is **not** reactive.
+     */
+    readonly onFocusIn?: InteractionEventHandler<FocusEvent, P> | undefined;
+    /**
+     * Handle component losing focus.
+     *
+     * The handler specified, if any, is invoked *before* any {@link ./state#FocusState |
+     * focus} state *may* have been exited from.
+     *
+     * @remarks
+     * This is **not** reactive.
+     */
+    readonly onFocusOut?: InteractionEventHandler<FocusEvent, P> | undefined;
+    /**
+     * Handle entry into an interaction state.
+     *
+     * The handler specified, if any, is invoked *after* the component enters into a state.
+     *
+     * @remarks
+     * This is **not** reactive.
+     */
+    readonly onInteractionStateEntered?: InteractionStateHandler<P> | undefined;
+    /**
+     * Handle exit from a interaction state.
+     *
+     * The handler specified, if any, is invoked *after* the component exits from a state.
+     *
+     * @remarks
+     * This is **not** reactive.
+     */
+    readonly onInteractionStateExited?: InteractionStateHandler<P> | undefined;
+};
+/**
+ * Interactable {@link ..#DomComponent | DOM} component.
+ *
+ * Interactable components are DOM components which allow user interaction. Interactable
+ * components are usually defined using {@link defineInteractableComponent}, and are controlled
+ * using an implementation of {@link ./controller#InteractableController}.
+ *
+ * @typeParam P - component properties
+ * @see {@link defineInteractableComponent}
+ */
+export type InteractableComponent<P extends DomProps> = DomComponent<InteractableProps<P>>;
+/**
+ * Define an {@link InteractableComponent | interactable} DOM component.
+ *
+ * This should be used, in place of {@link ..#defineDomComponent}, to define a component which
+ * renders elements that support user interaction. Like {@link ..#defineDomComponent}, the `server`
+ * and `client` suppliers are used to provide the server-side DOM rendering function and
+ * client-side DOM {@link ./controller#InteractableController | controller} implementation.
+ *
+ * The server-side render function behaves the same as {@link ..#defineDomComponent}. The
+ * client-side supplier, however, is invoked with the base interactable component controller, and
+ * is expected to return a controller implementation which extends the specified base controller.
+ *
+ * All interactable components support the {@link InteractableProps | base} interactable component
+ * properties. These properties are not forwarded to the server-side render function or client-side
+ * controller implementation.
+ *
+ * ```tsx
+ * import type { DomProps } from "@pg-labs-incubator/cobweb";
+ * import type { InteractableComponent, InteractableProps } from "@pg-labs-incubator/cobweb/state";
+ * import type { JSX } from "solid-js";
+ *
+ * import {
+ *     HoverState,
+ *     PressState,
+ *     defineInteractableComponent
+ * } from "@pg-labs-incubator/cobweb/state";
+ *
+ * export type MyProps = DomProps<HTMLSpanElement, JSX.HTMLElementTags["span"]> & {
+ *     size?: "large" | "medium" | "small";
+ * };
+ *
+ * export const MyComponent: InteractableComponent<MyProps> = defineInteractableComponent(
+ *     // Render on server-side:
+ *     () => (elemProps, localProps) => <span
+ *         {...elemProps}
+ *         classList={{
+ *             ...elemProps.classList,
+ *             [`MyComponent-size-${localProps.size ?? "small"}`]: true,
+ *             "MyComponent": true
+ *         }}
+ *     />,
+ *     // Render on client-side:
+ *     (Base) => class extends Base<MyProps> {
+ *         constructor(props: MyProps) {
+ *             super(props, {
+ *                 // Our style element is our function element; without this, we would need to
+ *                 // include the function reference.
+ *                 styleElementIsFunction: true,
+ *                 // By default, our element supports hovering and pressing states:
+ *                 enabledInteractionStates: HoverState | PressState
+ *             });
+ *         }
+ *
+ *         protected override applyComponentProps(): void {
+ *             // Invoked in a reactive context. When `size` changes, we'll get invoked again.
+ *             const [size, sizeChanged] = super.readProp("size");
+ *
+ *             if (sizeChanged) {
+ *                 // `size` changed, update the style
+ *                 super.setClass("size", `MyComponent-size-${size ?? "small"}`);
+ *             }
+ *         }
+ *
+ *         protected override render(children: JSX.Element): JSX.Element {
+ *             return <span class="MyComponent">{children}</span>;
+ *         }
+ *     }
+ * );
+ * ```
+ *
+ * # Design
+ *
+ * Interactable components render state-layer, which is used to apply visual styling to the style
+ * element to indicate the state of the component. The component author is expected to define the
+ * following CSS properties, when an interaction state is entered into, to control the state-layer.
+ *
+ * | Property                                     | Description                                   |
+ * | -------------------------------------------- | --------------------------------------------- |
+ * | `--cw-interactable-focusIndicator-color`     | Focus indicator color.                        |
+ * | `--cw-interactable-focusIndicator-offset`    | Offset of focus indicator from style container, where a value greater than, less than, or equal to zero place the indicator outside of the style element, inside the style element, or directly on top of the style element, respectively. |
+ * | `--cw-interactable-focusIndicator-thickness` | Thickness, in pixels, of the focus indicator. |
+ * | `--cw-interactable-stateLayer-color`         | State-layer color.                            |
+ * | `--cw-interactable-stateLayer-opacity`       | Opacity of state-layer.                       |
+ * | `--cw-interactable-ripple-color`             | Press ripple color.                           |
+ * | `--cw-interactable-ripple-opacity`           | Opacity of press ripple.                      |
+ * | `--cw-interactable-ripple-radius`            | Radius of an unbounded press ripple, or `auto` for a bounded ripple. |
+ *
+ * The `focusIndicator` properties can be set even if the component hasn't entered into the {@link
+ * FocusState | focus} state, as these properties are applied to the state-layer style only when
+ * the focus state is entered into. The state-layer properties, however, must be set whenever the
+ * respective state is entered into, as they determine the state-layer color for as long as the
+ * component has an interaction state enabled.
+ *
+ * The {@link PressState | press} state is shown by a ripple, painted above the state layer of the
+ * hover or focus state, whose class remains applied during a press. The ripple properties are
+ * read once the press class has been applied, and the ripple keeps them until it has faded out,
+ * after the press has been released. They are therefore set within the press class, rather than
+ * the state-layer properties, as Compose shows a press with a ripple of the pressed opacity
+ * (`RippleAlpha.pressedAlpha`), not with its state layer. A `currentcolor` ripple color is the
+ * color of the style element. A component which renders no ripple, as it is constructed with
+ * `noPressRipple`, may set the state-layer properties within its press class instead.
+ *
+ * A ripple is bounded by default: it spreads from the press position until it covers the state
+ * layer. A component whose Compose counterpart uses an unbounded ripple, such as a checkbox
+ * (`ripple(bounded = false, radius = CheckboxTokens.StateLayerSize / 2)`), assigns its radius to
+ * `--cw-interactable-ripple-radius` instead; the ripple then spreads from the center of the state
+ * layer to that radius.
+ *
+ * In the example below, `.MyComponent` is always applied to the style element, and the
+ * controller is constructed with `_MyComponent` as `baseInteractionCssClassName`. The focus
+ * indicator, when rendered, is blue, 2 pixels outside the style element, and 3 pixels wide. The
+ * state-layer is purple, except in the focus state, whose state-layer is red. Presses ripple in
+ * the state-layer color.
+ *
+ * ```css
+ * .MyComponent {
+ *     --cw-interactable-focusIndicator-color: blue;
+ *     --cw-interactable-focusIndicator-offset: 2px;
+ *     --cw-interactable-focusIndicator-thickness: 3px;
+ *     --cw-interactable-stateLayer-color: purple;
+ * }
+ *
+ * ._MyComponent-hover {
+ *     --cw-interactable-stateLayer-opacity: 0.08;
+ * }
+ *
+ * ._MyComponent-focus {
+ *     --cw-interactable-stateLayer-color: red;
+ *     --cw-interactable-stateLayer-opacity: 0.1;
+ * }
+ *
+ * ._MyComponent-press {
+ *     --cw-interactable-ripple-color: var(--cw-interactable-stateLayer-color);
+ *     --cw-interactable-ripple-opacity: 0.1;
+ * }
+ * ```
+ *
+ * The [`cw-State`](./state.yaml) system design attribute can be used to assign the above
+ * properties to standard values. As the value of these properties change, the state-layer color
+ * transitions with the fast effects spring, and the focus indicator geometry with the fast
+ * spatial spring. A component which overrides the transitions of the state-layer pseudo-element
+ * must transition `color`, the state-layer color, not `background-color`.
+ *
+ * @typeParam P - component properties type
+ * @param server - server-side DOM render function supplier
+ * @param client - client-side DOM controller implementation provider
+ * @returns resulting component
+ * @see {@link ..#defineDomComponent}
+ */
+export declare function defineInteractableComponent<P extends DomProps>(server: () => RenderServerDom<P>, client: (Controller: typeof InteractableController) => (new (props: P) => InteractableController<P>)): InteractableComponent<ClientDomProps<InteractableProps<P>>>;

package/target/tsc/state/controller.d.ts

@@ -0,0 +1,257 @@
+import type { DomControllerOptions, DomProps, FunctionElement, StyleElement } from "..";
+import type { InteractableProps } from "./component";
+import type { InteractionState } from "./state";
+import { DomController } from "../dom/client";
+/**
+ * Interactable {@link InteractableController | controller} options.
+ */
+export interface InteractableControllerOptions extends DomControllerOptions {
+    /**
+     * Base CSS class name of interaction states.
+     *
+     * The name specified is used as the base name for classes applied, to the style element,
+     * when an interaction state is entered into. For example, if a component enters into the
+     * {@link ./state#HoverState | hover} state, the class applied is `<base>-hover`, where
+     * `<base>` is the value specified.
+     *
+     * @defaultValue `"cw-interactable"`
+     */
+    baseInteractionCssClassName?: string;
+    /**
+     * Mask of enabled interaction {@link ./state#InteractionState | states}.
+     *
+     * @defaultValue `0`
+     * @see {@link InteractableController.isInteractionStateEnabled}
+     */
+    enabledInteractionStates?: number;
+    /**
+     * Ripple motion is not applied when entering into {@link ./state#PressState | press}
+     * state.
+     *
+     * @defaultValue `false`
+     * @see {@link InteractableController.isPressRippleDisabled}
+     */
+    noPressRipple?: boolean;
+    /**
+     * Focus-ring is not rendered, around style element, when container enters into a keyboard
+     * initiated {@link ./state#FocusState | focus} state.
+     *
+     * @defaultValue `false`
+     * @see {@link InteractableController.isFocusIndicatorDisabled}
+     */
+    noFocusIndicator?: boolean;
+}
+/**
+ * Client-side interactable {@link ./component#InteractableComponent | component} controller.
+ *
+ * Instances of this control the state of an interactable component instance, with respect to the
+ * {@link InteractableProps | properties} *and* interaction {@link InteractionState | states}
+ * the component is configured with. The base implementation of this extends the {@link
+ * DomController | base} DOM controller, and extends it with support for interactable component
+ * {@link InteractableProps | properties}. Implementations are expected to {@link
+ * InteractableController.setEnabledInteractionStates | control} interaction states and their local
+ * component properties, if any.
+ *
+ * The {@link DomController.onStyleElementChanged | `onStyleElementChanged`} and {@link
+ * DomController.onFunctionElementChanged | `onFunctionElementChanged`} methods, declared by {@link
+ * DomController}, are implemented by the base controller. If an implementation overrides these
+ * methods, they **must** invoke the implementations provided by this class. All other methods
+ * declared by {@link DomController} must be implemented as required by {@link DomController}.
+ *
+ * Controller instances can be constructed with {@link InteractableControllerOptions | options}.
+ * These options extend the {@link DomControllerOptions | base} options accepted by {@link
+ * DomController}. The initial set of {@link InteractableController.setEnabledInteractionStates |
+ * enabled} interaction states can be specified in {@link
+ * InteractableControllerOptions.enabledInteractionStates | `enabledInteractionStates`}.
+ *
+ * Each controller instance listens for user-trigger events to perform entry into or exit from
+ * {@link InteractableController.isInteractionStateEnabled | enabled} interaction states. If
+ * event listeners are defined in the properties the controller is constructed with, then those
+ * event listeners are invoked *irrespective* of whether the corresponding interaction state, for
+ * the respective event, is enabled or not.
+ *
+ * # Elements
+ *
+ * Styling is applied only to the {@link DomController.styleElement | style} element. User-events,
+ * however, are listened for on both the style and {@link DomController.functionElement | function}
+ * elements. The state type determines which element an event is accepted from, in terms of a
+ * trigger.
+ *
+ * | State                      | Element  | Description                                          |
+ * | -------------------------- | -------- | ---------------------------------------------------- |
+ * | {@link FocusState | Focus} | Function | Entry into and exit from the focus state is controlled by the `focusin` and `focusout` events targeted at the function element itself; focus moving within its descendants is ignored. When `focusin` is received, the focus state is entered into if, and only if, the `:focus-visible` pseudo-class is applied to the function element. |
+ * | {@link HoverState | Hover} | Style    | Entry into and exit from the hover state is controlled by the `pointerenter` and `pointerleave` events targeted at the style element, for any pointing device except touch. |
+ * | {@link PressState | Press} | Both     | A press begins with `pointerdown` from the primary pointing device, a `click` which no press preceded, or <kbd>Space</kbd> on a native function `button`. Events targeted at a descendant belong to the controller, unless a nested native control or interactable owns them. The press ends with the `click` following its release, and is cancelled by `pointercancel`, `contextmenu`, `pointerleave` of a non-touch pointer before release, or loss of focus during a keyboard press. |
+ * | {@link DragState | Drag}   | Both     | Entry into the drag state occurs once the pointer of a press moves {@link DRAG_THRESHOLD_PX} or more, after which the style element captures the pointer until release, cancellation, or lost capture. |
+ *
+ * # Styles
+ *
+ * The `cw-interactable` CSS class is added to the style element *while* the component has at least
+ * **one** interaction state {@link InteractableController.setEnabledInteractionStates | enabled}.
+ * The `cw-interactable` CSS class sets the `position` and `z-index` properties, of the style
+ * element, to `relative` and `0`, respectively. These two properties are *required* as the
+ * state-layer, rendered within the `::before` pseudo-element of the style element, has an
+ * absolute position.
+ *
+ * As states are entered into or exited from, state CSS classes are applied or removed from the
+ * style element. The CSS class applied or removed from the style element takes the form
+ * `<base>-<state>`, where `<base>` is configured by {@link
+ * InteractableControllerOptions.baseInteractionCssClassName}, and `<state>` is the {@link
+ * ./state#nameOfInteractionState | name} of the respective interaction state. For example, when
+ * `<base>` is `foo` and the state being entered into (or exited from) is the hover state, then
+ * the class applied (or removed) is `foo-hover`. Only the class of the highest-precedence state
+ * entered into is applied, except while the press state is the highest-precedence state: the
+ * class of the highest-precedence state below it then remains applied, since a press is shown by
+ * a ripple painted above the state layer of that state. The focus indicator is rendered for as
+ * long as the focus state is entered into.
+ *
+ * Entry into the press state applies a ripple, unless {@link
+ * InteractableControllerOptions.noPressRipple | disabled}, which follows the Compose ripple
+ * (`RippleAnimation.kt`). The ripple paints the `--cw-interactable-ripple-color` and
+ * `--cw-interactable-ripple-opacity` of the style element, read once the press class has been
+ * applied, and fades out once the press is released or cancelled, independently of the press
+ * class.
+ *
+ * # Documents and shadow roots
+ *
+ * Trigger events are delegated: a single set of capture listeners is installed on each document
+ * containing mapped elements, and on each closed shadow root containing them, since a document
+ * cannot resolve nodes within a closed shadow root. The document and closed shadow roots of an
+ * element are settled once, after the synchronous render which mapped the element. An element
+ * which is still detached at that point settles its roots on its first trigger event.
+ *
+ * Moving an already-connected control into another document, or into a closed shadow root, is
+ * **not** supported; render the control there instead. Events dispatched synchronously, within the
+ * task which rendered a control into another document or into a closed shadow root, are not
+ * delegated.
+ *
+ * # Synchronized states
+ *
+ * When interaction states become enabled, or elements are rendered into a connected tree (such as
+ * during hydration), the controller enters into the states which already apply: the focus state if
+ * the function element matches `:focus-visible`, and the hover state if the style element matches
+ * `:hover` while a pointing device of the user-agent can hover.
+ *
+ * @typeParam P - component properties type
+ * @see {@link ./component#defineInteractableComponent}
+ */
+export declare abstract class InteractableController<P extends DomProps> extends DomController<P> {
+    #private;
+    /**
+     * Construct a new interactable DOM controller.
+     *
+     * @param props - component properties
+     * @param opts - options to construct controller with
+     * @throws {@link Error} `opts.enabledInteractionStates` is not a valid interaction state mask
+     */
+    constructor(props: InteractableProps<P>, opts?: InteractableControllerOptions);
+    /**
+     * Owner of the component has released the controller.
+     *
+     * This is `true` as soon as cleanup has begun, including while interaction callbacks invoked
+     * by the cleanup are still on the stack.
+     *
+     * @returns `true` if, and only if, the controller has been released
+     */
+    protected get isControllerDisposed(): boolean;
+    /**
+     * Press triggered ripple motion is disabled.
+     *
+     * If this returns `true`, then the ripple motion is *not* applied when the component
+     * enters into a {@link PressState | press} state.
+     *
+     * @returns `true` if, and only if, press ripple is disabled
+     */
+    isPressRippleDisabled(): boolean;
+    /**
+     * Focus indicator is disabled.
+     *
+     * If this returns `true`, then a focus indicator is *not* rendered when the component
+     * enters into a {@link FocusState | focus} state.
+     *
+     * @returns `true` if, and only if, focus indicator is disabled
+     */
+    isFocusIndicatorDisabled(): boolean;
+    /**
+     * Mask of interaction {@link ./state#InteractionState | states} which are currently
+     * {@link InteractableController.setEnabledInteractionStates | enabled}.
+     *
+     * @returns enabled interaction state mask
+     * @see {@link InteractableController.isInteractionStateEnabled}
+     */
+    get enabledInteractionStates(): number;
+    /**
+     * Mask of interaction {@link ./state#InteractionState | states} which are currently
+     * entered into.
+     *
+     * @returns entered interaction state mask
+     * @see {@link InteractableController.isInteractionStateEntered}
+     */
+    get enteredInteractionStates(): number;
+    /**
+     * Test whether an interaction {@link ./state#InteractionState | state} has been {@link
+     * InteractableController.setEnabledInteractionStates | enabled}.
+     *
+     * @param state - state to test
+     * @returns `true` if, and only if, `state` is enabled
+     * @see {@link InteractableController.enabledInteractionStates}
+     */
+    isInteractionStateEnabled(state: InteractionState): boolean;
+    /**
+     * Test whether an interaction {@link ./state#InteractionState | state} has been entered
+     * into.
+     *
+     * @param state - state to test
+     * @returns `true` if, and only if, `state` has been entered into
+     * @see {@link InteractableController.enteredInteractionStates}
+     */
+    isInteractionStateEntered(state: InteractionState): boolean;
+    /**
+     * Set enabled interaction {@link ./state#InteractionState | states}.
+     *
+     * Upon return, only states set in `states` will be enabled for the component. Each entered
+     * state which is not set in `states` is exited from, and each newly enabled state which already
+     * applies is {@link InteractableController.#syncInteractionStates | entered} into.
+     *
+     * @param states - mask of states to enable
+     * @throws {@link Error} `states` is not a {@link ./state#isInteractionStateMask | valid}
+     * interaction state mask
+     */
+    setEnabledInteractionStates(states: number): void;
+    /**
+     * Handle trigger event.
+     *
+     * This is invoked whenever a trigger event is received for the component. By default,
+     * this will invoke the interaction event {@link InteractionEventHandler | handler}
+     * installed for the respective event, if any: `click`, `focusin` and `focusout` of the
+     * function element, and `pointerenter` and `pointerleave` of the style element, for any
+     * pointing device except touch.
+     *
+     * @param event - trigger event received
+     */
+    protected onEvent(event: Event): void;
+    /**
+     * Handle style element replacement before the controller reference is updated.
+     *
+     * The style-element getter still exposes the previous element during this hook.
+     *
+     * @param curr - new style element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onStyleElementChanged}
+     */
+    protected onStyleElementChanged(curr: StyleElement | null): void;
+    /**
+     * Handle function element replacement before the controller reference is updated.
+     *
+     * The function-element getter still exposes the previous element during this hook.
+     *
+     * @param curr - new function element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onFunctionElementChanged}
+     */
+    protected onFunctionElementChanged(curr: FunctionElement<P> | null): void;
+    /**
+     * Release delegated listeners and active interaction state with the owning Solid root.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Component state definitions.
+ *
+ * This module exports definitions for implementing user interaction states, as
+ * [defined](https://m3.material.io/foundations/interaction/states/overview) by the Material 3
+ * design specification. The {@link ./component#defineInteractableComponent} function can be
+ * used to define an interactable component, which renders DOM elements.
+ *
+ * Components defined using {@link ./component#defineInteractableComponent}, by default, render
+ * a state-layer within the `::before` pseudo element of the style element. The state-layer
+ * supports ripple press motions and focus indicators.
+ *
+ * @packageDocumentation
+ */
+export type { InteractableController, InteractableControllerOptions } from "./controller";
+export type { InteractionState, InteractionStateName } from "./state";
+export type { InteractableComponent, InteractableProps, InteractionEventHandler, InteractionStateHandler } from "./component";
+export { defineInteractableComponent } from "./component";
+export { DragState, FocusState, HoverState, PressState, isInteractionState, isInteractionStateMask, nameOfInteractionState } from "./state";

package/target/tsc/state/ripple.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Press ripple applied to a {@link ./style#STATE_LAYER_PSEUDO_ELEMENT | state-layer}.
+ *
+ * A ripple is painted above the state layer, so the state layer of the hover or focus state
+ * remains visible beneath it, and removes itself once it has faded out.
+ *
+ * @see {@link applyRipple}
+ */
+export interface Ripple {
+    /**
+     * Fade the ripple out, once it has spread.
+     *
+     * This is invoked once the press of the ripple is released or cancelled, as Compose finishes
+     * a ripple on `PressInteraction.Release` and `PressInteraction.Cancel`
+     * (`RippleAnimation.finish()`). A ripple still fading in switches to its full opacity, and
+     * fades out once it has spread. Subsequent invocations have no effect.
+     */
+    finish(): void;
+    /**
+     * Remove the ripple immediately.
+     *
+     * This is required only when a ripple must disappear before it has faded out, such as when its
+     * element is released.
+     */
+    cancel(): void;
+}
+/**
+ * Apply ripple motion to an element with a {@link ./style#STATE_LAYER_PSEUDO_ELEMENT |
+ * state-layer}.
+ *
+ * The ripple follows the Compose ripple (`RippleAnimation.kt`): its circle starts with a radius of
+ * 30% of the largest state-layer dimension, at the press position, and grows 10px beyond the
+ * radius covering the state layer, while its center moves to the center of the state layer. An
+ * unbounded ripple, whose `--cw-interactable-ripple-radius` is a length, starts at the center
+ * instead, and grows to that radius. The ripple paints the `--cw-interactable-ripple-color` and
+ * `--cw-interactable-ripple-opacity` of `elem`, read when the ripple is applied, above the state
+ * layer, and fades out once {@link Ripple.finish | finished}.
+ *
+ * Ripples already painted by `elem` are finished, and keep fading out while the new ripple spreads.
+ * Durations and easings are fixed, as in Compose, rather than following the motion scheme.
+ *
+ * Applying a ripple measures `elem` and its state layer once; no layout or style is read while the
+ * ripple moves.
+ *
+ * @param elem - element to enter into ripple for
+ * @param origin - position, in client coordinates, of the press or `undefined` to center the
+ * ripple within `elem`
+ * @returns applied ripple, or `undefined` when the ripple could not be applied
+ */
+export declare function applyRipple(elem: Element, origin?: readonly [number, number]): Ripple | undefined;