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

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

@@ -0,0 +1,92 @@
+/**
+ * Release speed, in pixels per second, from which a drag is a fling.
+ *
+ * A fling settles at the next anchor in its direction, irrespective of how far it travelled.
+ */
+export declare const FLING_VELOCITY_THRESHOLD = 125;
+/**
+ * Largest release velocity, in pixels per second, of a drag.
+ *
+ * @see MAXIMUM_FLING_VELOCITY in Android `ViewConfiguration`, the default of Compose's
+ * `ViewConfiguration.maximumFlingVelocity`
+ */
+export declare const MAX_FLING_VELOCITY = 8000;
+/**
+ * Time, in milliseconds, after the last pointer move from which a pointer is considered stopped.
+ *
+ * @see AssumePointerMoveStoppedMilliseconds in Compose `VelocityTracker.kt`
+ */
+export declare const POINTER_STOPPED_MSEC = 40;
+/**
+ * Find the anchor closest to a position, optionally searching in one direction only.
+ *
+ * If `upwards` is not `undefined`, then anchors in the other direction are infinitely far away,
+ * and are only found if no anchor lies in the searched direction. Of equally close anchors, the
+ * last one in `anchors` is found. An anchor which is `NaN` is never found.
+ *
+ * @param anchors - anchor positions, in any order
+ * @param position - position to search from
+ * @param upwards - `true` to search anchors at or above `position`, `false` to search anchors at
+ * or below it, or `undefined` to search both directions
+ * @returns position of the closest anchor, or `position` if no anchor is found
+ */
+export declare function closestAnchorOf(anchors: readonly number[], position: number, upwards?: boolean): number;
+/**
+ * Choose the anchor at which a released drag settles.
+ *
+ * A drag released at rest settles at the closest anchor. A fling settles at the next anchor in
+ * its direction. A slower release settles at the next anchor in its direction if, and only if, it
+ * travelled at least `threshold` from the anchor behind it; otherwise, it returns to that anchor.
+ *
+ * @param anchors - anchor positions, in any order
+ * @param offset - offset at release
+ * @param velocity - release velocity, in pixels per second, positive towards greater positions
+ * @param threshold - positional threshold, in pixels
+ * @returns position of the target anchor
+ * @see {@link FLING_VELOCITY_THRESHOLD}
+ */
+export declare function settleTargetOf(anchors: readonly number[], offset: number, velocity: number, threshold: number): number;
+/**
+ * Resolve the pointer events a pointer event coalesces.
+ *
+ * Browsers expose `getCoalescedEvents` to secure contexts only, and report no coalesced events for
+ * synthetic events; the event itself stands in for its coalesced events then.
+ *
+ * @param event - pointer event
+ * @returns coalesced events, or `event` itself when the browser does not report them
+ */
+export declare function coalescedEventsOf(event: PointerEvent): readonly PointerEvent[];
+/**
+ * Estimator of the release velocity of a dragging pointer along one axis.
+ *
+ * Every position of a pointer event is tracked, including the positions it coalesces. Release
+ * events repeat the last tracked position, so they are not tracked; a release later than {@link
+ * POINTER_STOPPED_MSEC} after the last move has no velocity.
+ *
+ * @see VelocityTracker.addPointerInputChange in Compose `VelocityTracker.kt`
+ */
+export declare class DragVelocity {
+    #private;
+    /**
+     * Construct a new `DragVelocity`.
+     */
+    constructor();
+    /**
+     * Forget the tracked positions, before a new drag.
+     */
+    reset(): void;
+    /**
+     * Track the positions of a pointer down or move event.
+     *
+     * @param event - pointer event
+     * @param positionOf - read the position of the pointer along the axis
+     */
+    track(event: PointerEvent, positionOf: (sample: PointerEvent) => number): void;
+    /**
+     * Estimate the velocity of a released pointer.
+     *
+     * @param event - releasing pointer event
+     * @returns velocity, in pixels per second, within {@link MAX_FLING_VELOCITY}
+     */
+    release(event: PointerEvent): number;
+}

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

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

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

@@ -0,0 +1,292 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps, StyleElement } from "..";
+import { DomController } from "../dom/client";
+import "../container/elevation-shadow.css";
+import "./gestures.css";
+export type { CarouselItemProps, CarouselLayout, CarouselProps } from "./carousel";
+export { Carousel, CarouselController, CarouselItem, CarouselSlide } from "./carousel";
+/**
+ * Swipe axis.
+ */
+export type SwipeAxis = "horizontal" | "vertical";
+/**
+ * Swipe direction passed to the dismissal callback.
+ *
+ * Horizontal directions are logical: `"start"` moves toward the start of the writing direction.
+ */
+export type SwipeDirection = "start" | "end" | "up" | "down";
+/**
+ * Properties accepted by {@link SwipeToDismiss}.
+ */
+export type SwipeToDismissProps = DomProps<HTMLDivElement, Omit<JSX.HTMLAttributes<HTMLDivElement>, "role" | "aria-hidden">> & {
+    /**
+     * Gesture axis.
+     *
+     * @defaultValue `"horizontal"`
+     */
+    axis?: SwipeAxis | undefined;
+    /**
+     * Disable the gesture and the Delete key.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Fraction of the item size a slow release must travel to dismiss.
+     *
+     * When omitted, Material's positional threshold of 56 pixels applies. Values are clamped
+     * between `0.05` and `1`. Flings dismiss regardless of the distance travelled.
+     */
+    threshold?: number | undefined;
+    /**
+     * Content revealed underneath the item while it moves.
+     */
+    background?: JSX.Element;
+    /**
+     * Notify the consumer of a dismissal.
+     *
+     * Called once the content has slid off after a released swipe, the Delete key, or {@link
+     * SwipeToDismissController.dismiss}. The item is then hidden from accessibility and inert, and
+     * focus inside it has moved to the next focusable element. Remove the item in this callback,
+     * or call {@link SwipeToDismissController.reset} to restore it.
+     *
+     * @param direction - logical horizontal or physical vertical dismissal direction
+     * @param event - releasing pointer event or Delete key event, or `undefined` when dismissed
+     * programmatically
+     */
+    onDismiss?: ((direction: SwipeDirection, event?: PointerEvent | KeyboardEvent) => void) | undefined;
+    /**
+     * Notify the consumer while the item moves.
+     *
+     * @param offset - physical offset of the item along the axis, in pixels
+     * @param event - moving pointer event, or `undefined` while the item settles
+     */
+    onOffsetChange?: ((offset: number, event?: PointerEvent) => void) | undefined;
+};
+/**
+ * Client controller of a {@link SwipeToDismiss} container.
+ *
+ * A primary pointer moving along the axis, past {@link GESTURE_SLOP}, captures the pointer and
+ * drags the content; movement across the axis first releases the gesture to native scrolling. A
+ * {@link ./drag#DragVelocity | velocity estimator} follows every pointer position. On release, the
+ * content settles at its resting or a dismissed position, chosen as Compose's anchored drag does,
+ * with a spatial spring seeded with the release velocity. A pointer pressed while the content
+ * settles catches it, without slop, and drags it from where it is.
+ */
+export declare class SwipeToDismissController extends DomController<SwipeToDismissProps> {
+    #private;
+    /**
+     * Construct a new `SwipeToDismissController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: SwipeToDismissProps);
+    /**
+     * Read the current physical offset of the content along the axis.
+     *
+     * While the content settles, this is the most recently animated offset.
+     *
+     * @returns offset, in pixels
+     */
+    offset(): number;
+    /**
+     * Dismiss the item without a gesture.
+     *
+     * The content slides off in `direction`, as after a swipe, and {@link
+     * SwipeToDismissProps.onDismiss | `onDismiss`} is notified once it has. This has no effect on a
+     * disabled or already dismissed item.
+     *
+     * @param direction - dismissal direction; defaults to `"start"`, or `"up"` for a vertical axis
+     */
+    dismiss(direction?: SwipeDirection): void;
+    /**
+     * Restore the item to its resting position at once, dismissed or not.
+     */
+    reset(): void;
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): 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;
+    /**
+     * Render the component's element tree.
+     *
+     * This renders the elements of the server rendering, with the current properties: the
+     * background is a reactive slot, while attributes are static.
+     *
+     * @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;
+}
+/**
+ * Container whose content is dismissed by a horizontal or vertical swipe.
+ *
+ * A released swipe settles where Material's anchored drag would: a fling of at least 125 pixels per
+ * second continues to the next position in its direction, and a slower release dismisses once it
+ * has travelled the positional threshold of 56 pixels, or the {@link SwipeToDismissProps.threshold
+ * | `threshold`} fraction of the item size. The content then slides off, or back, with a spatial
+ * spring which continues the release velocity; pressing it while it moves catches it. Once slid
+ * off, the content is inert and hidden from accessibility, and {@link SwipeToDismissProps.onDismiss
+ * | `onDismiss`} is notified.
+ *
+ * Gestures are an enhancement: the Delete key dismisses the item when focus is inside it, outside
+ * text fields, and {@link SwipeToDismissController.dismiss} supports a visible alternative action.
+ *
+ * # States
+ *
+ * While dragged, the container has the `cw-SwipeToDismiss-dragging` class; once dismissed, the
+ * `cw-SwipeToDismiss-dismissed` class. A disabled container has the `cw-SwipeToDismiss-disabled`
+ * class.
+ *
+ * @param props - component properties
+ * @returns rendered container
+ */
+export declare const SwipeToDismiss: DomComponent<SwipeToDismissProps>;
+/**
+ * Properties accepted by {@link PullToRefresh}.
+ */
+export type PullToRefreshProps = DomProps<HTMLDivElement, Omit<JSX.HTMLAttributes<HTMLDivElement>, "role" | "aria-busy">> & {
+    /**
+     * Controlled refreshing state.
+     */
+    refreshing?: boolean | undefined;
+    /**
+     * Initial refreshing state of an uncontrolled region.
+     *
+     * @defaultValue `false`
+     */
+    defaultRefreshing?: boolean | undefined;
+    /**
+     * Disable pulling and the Enter key; content remains interactive.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Accessible name of the refresh region.
+     *
+     * @defaultValue `"Pull to refresh"`
+     */
+    label?: string | undefined;
+    /**
+     * Pointer travel, in pixels, a released pull must reach to refresh.
+     *
+     * The indicator travels at half the pointer speed and reaches its resting position at the
+     * threshold. Values below 24 are raised to 24.
+     *
+     * @defaultValue `160`
+     */
+    threshold?: number | undefined;
+    /**
+     * Indicator content shown while pulling and refreshing.
+     *
+     * When omitted, a circular progress indicator follows the pull and turns indeterminate while
+     * refreshing.
+     */
+    indicator?: JSX.Element;
+    /**
+     * Sequential focus index of the refresh region.
+     *
+     * @defaultValue `0`
+     */
+    tabIndex?: number | undefined;
+    /**
+     * Start refresh work after a completed pull or the Enter key.
+     *
+     * A returned promise requests completion when it settles; returning no promise completes on the
+     * next microtask. Controlled refreshing state requires the parent to accept
+     * `onRefreshingChange(false)`. Handle refresh errors in the supplied work.
+     *
+     * @param event - pointer, touch, or keyboard event starting the request
+     */
+    onRefresh?: ((event: PointerEvent | TouchEvent | KeyboardEvent) => void | Promise<void>) | undefined;
+    /**
+     * Notify the consumer of a refreshing state change, or request one when controlled.
+     *
+     * @param refreshing - new or requested refreshing state
+     * @param event - triggering event, if any
+     */
+    onRefreshingChange?: ((refreshing: boolean, event?: Event) => void) | undefined;
+};
+/**
+ * Client controller of a {@link PullToRefresh} region.
+ *
+ * Mouse and pen pulls use pointer capture; touch pulls use non-passive touch events, which claim
+ * a downward move at the scroll origin before the user-agent starts panning. The indicator, not
+ * the content, follows the pull at half speed, with diminishing travel past the threshold.
+ */
+export declare class PullToRefreshController extends DomController<PullToRefreshProps> {
+    #private;
+    /**
+     * Construct a new `PullToRefreshController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: PullToRefreshProps);
+    /**
+     * Complete an active uncontrolled refresh.
+     *
+     * Clears the internal refreshing state and notifies `onRefreshingChange(false)`. This method
+     * has no effect on a controlled refresh region; update its `refreshing` property directly.
+     *
+     * @param event - event supplied to the state-change callback, if any
+     */
+    complete(event?: Event): void;
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): 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;
+    /**
+     * Render the component's element tree.
+     *
+     * This renders the elements of the server rendering, with the current state: the indicator is
+     * a reactive slot, and the default indicator follows the pull progress, while attributes are
+     * static.
+     *
+     * @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;
+}
+/**
+ * Region whose content refreshes after a downward pull at its scroll origin.
+ *
+ * The region scrolls natively. Pulling down from the top moves an elevated circular indicator,
+ * at half the pointer speed; releasing beyond the {@link PullToRefreshProps.threshold |
+ * threshold} starts a refresh, and the indicator rests in view while refreshing. The focused
+ * region refreshes with the Enter key; applications should also offer a visible refresh action.
+ *
+ * # States
+ *
+ * The region has `aria-busy="true"` and the `cw-PullToRefresh-refreshing` class while refreshing,
+ * the `cw-PullToRefresh-dragging` class while pulled, the `cw-PullToRefresh-at-start` class while
+ * scrolled to its origin, and the `cw-PullToRefresh-disabled` class while disabled.
+ *
+ * @param props - component properties
+ * @returns rendered region
+ */
+export declare const PullToRefresh: DomComponent<PullToRefreshProps>;

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

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

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

@@ -0,0 +1,29 @@
+/**
+ * Material 3 and Material 3 Expressive surfaces, content containers, overlays, sheets, layout
+ * scaffolds, and gesture primitives.
+ *
+ * @packageDocumentation
+ */
+import "./surface.css";
+export type { SurfaceBaseProps, SurfaceColor, SurfaceProps } from "./surface";
+export { Surface, SurfaceController } from "./surface";
+export type { DividerOrientation, DividerProps } from "./divider";
+export { Divider, DividerController } from "./divider";
+export type { ListItemBaseProps, ListItemLeadingType, ListItemProps, ListProps, ListSelectionMode } from "./list";
+export { List, ListController, ListItem, ListItemController } from "./list";
+export type { ExpandedListItemProps, RevealListItemProps, ReorderableListProps, ReorderHandleProps } from "./list-patterns";
+export { ExpandedListItem, ExpandedListItemController, RevealListItem, RevealListItemController, ReorderableList, ReorderableListController, ReorderHandle } from "./list-patterns";
+export type { AlertDialogProps, DialogCloseReason, DialogOpenChangeHandler, DialogProps, FullScreenDialogProps } from "./dialog";
+export { AlertDialog, AlertDialogController, Dialog, DialogController, FullScreenDialog, FullScreenDialogController } from "./dialog";
+export type { MenuCheckboxItemProps, MenuGroupProps, MenuItemBaseProps, MenuItemProps, MenuPlacement, MenuProps, MenuRadioItemProps, MenuTriggerRenderProps, SubMenuProps } from "./menu";
+export { Menu, MenuCheckboxItem, MenuCheckboxItemController, MenuController, MenuGroup, MenuGroupController, MenuItem, MenuItemController, MenuRadioItem, MenuRadioItemController, SubMenu } from "./menu";
+export type { BottomSheetBaseProps, BottomSheetExpansionHandler, BottomSheetProps, ModalBottomSheetProps } from "./sheet";
+export { BottomSheet, BottomSheetController, ModalBottomSheet, ModalBottomSheetController } from "./sheet";
+export type { BottomSheetScaffoldProps, FabPosition, ListDetailPaneScaffoldProps, ScaffoldProps, SupportingPaneScaffoldProps, WindowSizeClass } from "./scaffold";
+export { BottomSheetScaffold, ListDetailPaneScaffold, ListDetailPaneScaffoldController, Scaffold, ScaffoldController, SupportingPaneScaffold, SupportingPaneScaffoldController, createWindowSizeClass, windowSizeClassOf } from "./scaffold";
+export type { SideSheetProps } from "./side-sheet";
+export { ModalSideSheet, SideSheetController, StandardSideSheet } from "./side-sheet";
+export type { CarouselItemProps, CarouselLayout, CarouselProps } from "./carousel";
+export { Carousel, CarouselController, CarouselItem, CarouselSlide } from "./carousel";
+export type { PullToRefreshProps, SwipeAxis, SwipeDirection, SwipeToDismissProps } from "./gestures";
+export { PullToRefresh, PullToRefreshController, SwipeToDismiss, SwipeToDismissController } from "./gestures";

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

@@ -0,0 +1,22 @@
+/**
+ * Test whether an event target is an element, without relying on the constructors of the current
+ * realm.
+ *
+ * @param value - event target to test
+ * @returns `true` if, and only if, `value` is an element node
+ */
+export declare function isElementNode(value: EventTarget | null | undefined): value is Element;
+/**
+ * Test whether an event target lies within an interactive descendant of a component root.
+ *
+ * The composed path, when supplied, is inspected first so that targets retargeted out of a shadow
+ * tree are attributed to the interactive element inside it. The ancestors of `target` up to, but
+ * excluding, `root` are inspected next. The root itself never counts as nested.
+ *
+ * @param target - event target element
+ * @param root - component root element
+ * @param path - composed path of the event, if available
+ * @returns `true` if, and only if, `target` is, or is contained by, an interactive descendant of
+ * `root`
+ */
+export declare function hasNestedInteractive(target: Element, root: Element, path?: readonly EventTarget[]): boolean;