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

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

@@ -0,0 +1,129 @@
+/**
+ * Primary pointing device is hovering over style element.
+ *
+ * A component enters into the hover state while the non-touch pointing device is hovering over
+ * the *style* element of the component. This state is **never** entered into when the pointing
+ * device is a touch device.
+ *
+ * @see {@link InteractionState}
+ */
+export declare const HoverState = 1;
+/**
+ * User-agent focus is on function element.
+ *
+ * A component enters into the focus state while the user-agent has focus on the function element
+ * of the component.
+ *
+ * @see {@link InteractionState}
+ */
+export declare const FocusState = 2;
+/**
+ * Style or function element is being pressed.
+ *
+ * A component enters into the press state when the primary pointing device, or synthetic click,
+ * occurs on the style or function element.
+ *
+ * @see {@link InteractionState}
+ */
+export declare const PressState = 4;
+/**
+ * Style or function element is being dragged.
+ *
+ * A component enters into the drag state when the primary pointing device presses down on the
+ * style or function element, of the respective component, *and* the primary pointing device is
+ * moved. After the first press and move combination, this state is active for as long as the
+ * pointing device is being pressed down on the element.
+ *
+ * @see {@link InteractionState}
+ */
+export declare const DragState = 8;
+/**
+ * Union of interaction states.
+ *
+ * Interaction states are entered into and exited from based on user input. These states apply
+ * styling based on their precedence, determined by the numerical value of the respective state.
+ *
+ * Styling applied for states is exclusive, based on precedence. For example, if a component
+ * enters into the {@link FocusState | focus} state, followed by entry into {@link DragState |
+ * drag} state, while both focus and drag states are active for the component, only styling for
+ * the drag state is applied to the component. The press state is the exception: a press is shown
+ * by a ripple painted above the state layer, so while the press state has the highest precedence,
+ * styling for the highest-precedence state below it, such as the hover state, remains applied.
+ *
+ * | State              | Precedence |
+ * | ------------------ | ---------- |
+ * | {@link HoverState} | `0`        |
+ * | {@link FocusState} | `1`        |
+ * | {@link PressState} | `2`        |
+ * | {@link DragState}  | `3`        |
+ *
+ * @remarks
+ * State values are numerical values that may be bitwise OR'ed together to form a *set* of states.
+ */
+export type InteractionState = typeof DragState | typeof FocusState | typeof HoverState | typeof PressState;
+/**
+ * Union of interaction {@link InteractionState | state} names.
+ *
+ * @see {@link nameOfInteractionState}
+ */
+export type InteractionStateName = "drag" | "focus" | "hover" | "press";
+/**
+ * Test whether a `number` is an interaction {@link InteractionState | state}.
+ *
+ * @param val - `number` to test
+ * @returns `true` if, and only if, `val` is an interaction state
+ * @see {@link isInteractionStateMask}
+ */
+export declare function isInteractionState(val: number): val is InteractionState;
+/**
+ * Test whether a `number` is a mask of interaction {@link InteractionState | states}.
+ *
+ * @param mask - `number` to test
+ * @returns `true` if, and only if, `mask` is `0` or a mask of interaction states
+ * @see {@link isInteractionState}
+ */
+export declare function isInteractionStateMask(mask: number): boolean;
+/**
+ * Retrieve {@link InteractionStateName | name} of an interaction {@link InteractionState | state}.
+ *
+ * @param state - state to retrieve name of
+ * @returns name of `state`
+ */
+export declare function nameOfInteractionState(state: InteractionState): InteractionStateName;
+/**
+ * Retrieve lowest, in terms of precedence, interaction {@link InteractionState | state} set in a
+ * mask.
+ *
+ * @param mask - mask to retrieve lowest state of
+ * @returns lowest state set in `mask` or `undefined` if `mask` is `0`
+ */
+export declare function lowestInteractionStateOf(mask: number): InteractionState | undefined;
+/**
+ * Retrieve highest, in terms of precedence, interaction {@link InteractionState | state} set in a
+ * mask.
+ *
+ * @param mask - mask to retrieve highest state of
+ * @returns highest state set in `mask` or `undefined` if `mask` is `0`
+ */
+export declare function highestInteractionStateOf(mask: number): InteractionState | undefined;
+/**
+ * Retrieve next higher, in terms of precedence, interaction {@link InteractionState | state} set
+ * in a mask, from another state.
+ *
+ * @param mask - state mask
+ * @param from - state to retrieve next higher state from
+ * @returns next state, within `mask`, with precedence greater than `from` or `undefined` if there
+ * is no state within `mask` with a precedence greater than `from`
+ */
+export declare function nextInteractionStateOf(mask: number, from: InteractionState): InteractionState | undefined;
+/**
+ * Stream interaction {@link InteractionState | states} set within a mask, in order of precedence.
+ *
+ * This yields each state set in `mask`, in order of precedence. For example, if `mask` has both
+ * {@link FocusState | focus} and {@link HoverState | hover} set, this will yield hover before
+ * focus.
+ *
+ * @param mask - mask to stream states of
+ * @returns state generator
+ */
+export declare function streamInteractionStates(mask: number): Generator<InteractionState, undefined, boolean | undefined>;

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

@@ -0,0 +1,22 @@
+/**
+ * Pseudo-element, of style element, in which the state-layer is rendered.
+ */
+export declare const STATE_LAYER_PSEUDO_ELEMENT = "::before";
+/**
+ * Class applied to style element of an interactable component.
+ */
+export declare const CSS_CLASS_INTERACTABLE = "cw-interactable";
+/**
+ * Class which renders state-layer within a style element.
+ */
+export declare const CSS_CLASS_STATE_LAYER = "_cw-interactable-stateLayer";
+/**
+ * Class which renders a focus indicator within state-layer.
+ */
+export declare const CSS_CLASS_FOCUS_INDICATOR = "_cw-interactable-focusIndicator";
+/**
+ * Class which paints the press ripples of a state-layer, while a ripple is painted.
+ *
+ * @see {@link ./ripple#applyRipple}
+ */
+export declare const CSS_CLASS_RIPPLE = "_cw-interactable-ripple";

package/target/tsc/surface/carousel-layout.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Material carousel arrangement.
+ *
+ * | Arrangement                        | Items                                               |
+ * | ---------------------------------- | --------------------------------------------------- |
+ * | `"multi-browse"`                   | Large items, followed by a medium and a small item. |
+ * | `"hero"`                           | One large item, followed by a small item.           |
+ * | `"center-aligned-hero"`            | One large item, between two small items.            |
+ * | `"uncontained"`                    | Items of the preferred size, the last one cut off.  |
+ * | `"uncontained-multi-aspect-ratio"` | Items of their own aspect ratios, without keylines. |
+ * | `"full-screen"`                    | One item filling the container, without keylines.   |
+ */
+export type CarouselLayout = "multi-browse" | "hero" | "center-aligned-hero" | "uncontained" | "uncontained-multi-aspect-ratio" | "full-screen";
+/**
+ * Keyline of a carousel.
+ *
+ * This is a position along the scrolling axis, and the size an item centered on it shows.
+ */
+export interface CarouselKeyline {
+    /**
+     * Size, in pixels, of item centered on keyline.
+     */
+    readonly size: number;
+    /**
+     * Drawn position, in pixels, of item center.
+     */
+    readonly offset: number;
+    /**
+     * Position of keyline in unmasked layout.
+     *
+     * In the unmasked layout, consecutive keylines are one focal item size and one item spacing
+     * apart. Item centers of that layout are compared against this.
+     */
+    readonly unadjustedOffset: number;
+    /**
+     * Keyline belongs to focal run.
+     *
+     * The focal run is the run of largest keylines, where items are not masked.
+     */
+    readonly focal: boolean;
+    /**
+     * Keyline is an anchor.
+     *
+     * Anchors are the two outermost keylines, where items leave the container.
+     */
+    readonly anchor: boolean;
+    /**
+     * Keyline is pivot of its list.
+     *
+     * The pivot is the keyline from whose position its list is laid out.
+     */
+    readonly pivot: boolean;
+    /**
+     * Overhang, in pixels, of item past container edge.
+     *
+     * This is the distance by which an item centered on the keyline extends past one container
+     * edge, or `0`. An item past both edges reports its overhang at the start.
+     */
+    readonly cutoff: number;
+}
+/**
+ * List of keylines, in order along scrolling axis.
+ */
+type KeylineList = readonly CarouselKeyline[];
+/**
+ * Keylines of an arrangement in a container.
+ */
+export interface CarouselStrategy {
+    /**
+     * Container size, in pixels.
+     */
+    readonly availableSpace: number;
+    /**
+     * Focal item size, in pixels.
+     */
+    readonly itemSize: number;
+    /**
+     * Space between items, in pixels.
+     */
+    readonly itemSpacing: number;
+    /**
+     * Keylines while scrolled away from both ends.
+     */
+    readonly defaultKeylines: KeylineList;
+    /**
+     * Keyline steps towards container start.
+     *
+     * This lists the keylines from {@link CarouselStrategy.defaultKeylines | `defaultKeylines`}
+     * itself to the keylines at the scroll start, each step moving the focal keylines further
+     * towards the container start.
+     */
+    readonly startSteps: readonly KeylineList[];
+    /**
+     * Keyline steps towards container end.
+     *
+     * This lists the keylines from {@link CarouselStrategy.defaultKeylines | `defaultKeylines`}
+     * itself to the keylines at the scroll end, each step moving the focal keylines further
+     * towards the container end.
+     */
+    readonly endSteps: readonly KeylineList[];
+    /**
+     * Scroll distance, in pixels, of start steps.
+     */
+    readonly startShiftDistance: number;
+    /**
+     * Scroll distance, in pixels, of end steps.
+     */
+    readonly endShiftDistance: number;
+    /**
+     * Progress at which each start step applies.
+     *
+     * Each point is a fraction, from `0` to `1`, of {@link CarouselStrategy.startShiftDistance |
+     * `startShiftDistance`}. This is `[0]` if that distance is `0`.
+     */
+    readonly startShiftPoints: readonly number[];
+    /**
+     * Progress at which each end step applies.
+     *
+     * Each point is a fraction, from `0` to `1`, of {@link CarouselStrategy.endShiftDistance |
+     * `endShiftDistance`}. This is `[0]` if that distance is `0`.
+     */
+    readonly endShiftPoints: readonly number[];
+}
+/**
+ * Translation and mask of an item.
+ */
+export interface CarouselItemPlacement {
+    /**
+     * Translation, in pixels, of item.
+     *
+     * This is the distance by which the item moves towards the container end from its place in the
+     * end-to-end layout.
+     */
+    readonly translation: number;
+    /**
+     * Size, in pixels, of unmasked part of item.
+     */
+    readonly maskSize: number;
+    /**
+     * Masked item intersects container.
+     */
+    readonly visible: boolean;
+}
+/**
+ * Compute keyline strategy of an arrangement.
+ *
+ * @param layout - carousel arrangement
+ * @param availableSpace - container size along scrolling axis, in pixels
+ * @param preferredItemSize - preferred size of large items, in pixels, which hero arrangements
+ * ignore
+ * @param itemSpacing - space between items, in pixels
+ * @param itemCount - number of items
+ * @returns new strategy, or `undefined` if the arrangement has no keylines, no item fits, or there
+ * is no item
+ * @throws {@link RangeError} arrangement holds `2 ** 32` items or more
+ */
+export declare function carouselStrategy(layout: CarouselLayout, availableSpace: number, preferredItemSize: number, itemSpacing: number, itemCount: number): CarouselStrategy | undefined;
+/**
+ * Compute largest scroll offset of a carousel.
+ *
+ * Every item is taken at the focal size.
+ *
+ * @param strategy - keyline strategy
+ * @param itemCount - number of items
+ * @returns largest scroll offset, in pixels, at least `0`
+ */
+export declare function carouselMaxScroll(strategy: CarouselStrategy, itemCount: number): number;
+/**
+ * Resolve keylines at a scroll offset.
+ *
+ * Away from both ends, this is the default list of the strategy itself. Within the start or end
+ * shift distance, this interpolates the two steps around the progress through that distance.
+ *
+ * @param strategy - keyline strategy
+ * @param scrollOffset - scroll offset, in pixels from the start
+ * @param maxScrollOffset - largest scroll offset
+ * @returns keyline list, either of `strategy` or new
+ */
+export declare function carouselKeylinesAt(strategy: CarouselStrategy, scrollOffset: number, maxScrollOffset: number): KeylineList;
+/**
+ * Place an item along keylines.
+ *
+ * The item's center in the end-to-end layout is located between the two keylines around it, by
+ * their unadjusted offsets, and the item takes the size and position interpolated between them.
+ * An item before the first or past the last keyline takes that keyline's size and position,
+ * moved by its distance from the keyline relative to that size.
+ *
+ * @param strategy - keyline strategy
+ * @param keylines - keylines at `scrollOffset`
+ * @param index - item index
+ * @param scrollOffset - scroll offset, in pixels from the start
+ * @returns new placement
+ * @throws {@link TypeError} `keylines` is empty
+ */
+export declare function placeCarouselItem(strategy: CarouselStrategy, keylines: KeylineList, index: number, scrollOffset: number): CarouselItemPlacement;
+/**
+ * Compute rest position of an item.
+ *
+ * This is where the item's start rests when the carousel is snapped to it. The first items rest
+ * where the start steps, in reverse order, put the first focal keyline. The last items, unless
+ * every item fits in the focal run, rest where the end steps put the last focal keyline. Every
+ * other item rests at the first focal keyline of the default list.
+ *
+ * @param strategy - keyline strategy
+ * @param index - item index
+ * @param itemCount - number of items
+ * @returns position, in whole pixels from the container start
+ * @throws {@link TypeError} `index` or `itemCount` is fractional where it selects one of several
+ * steps, or both are infinite
+ */
+export declare function carouselSnapOffset(strategy: CarouselStrategy, index: number, itemCount: number): number;
+export {};

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

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

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

@@ -0,0 +1,231 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps, StyleElement } from "..";
+import type { CarouselLayout } from "./carousel-layout";
+import { DomController } from "../dom/client";
+import "./carousel.css";
+export type { CarouselLayout } from "./carousel-layout";
+/**
+ * Properties accepted by {@link Carousel}.
+ */
+export type CarouselProps = DomProps<HTMLDivElement, Omit<JSX.HTMLAttributes<HTMLDivElement>, "role" | "aria-roledescription">> & {
+    /**
+     * Controlled active item index.
+     *
+     * When supplied, the carousel requests index changes through {@link
+     * CarouselProps.onIndexChange | `onIndexChange`} and waits for the parent to update this
+     * property.
+     */
+    index?: number | undefined;
+    /**
+     * Alias for {@link CarouselProps.index | `index`}.
+     */
+    activeIndex?: number | undefined;
+    /**
+     * Initial active item index of an uncontrolled carousel.
+     *
+     * @defaultValue `0`
+     */
+    defaultIndex?: number | undefined;
+    /**
+     * Material carousel arrangement.
+     *
+     * @defaultValue `"full-screen"`
+     */
+    layout?: CarouselLayout | undefined;
+    /**
+     * Preferred size, in pixels, of large items along the scrolling axis.
+     *
+     * Multi-browse carousels adjust large items toward this size to fit medium and small items.
+     * Uncontained carousels use it as the item size; multi-aspect-ratio carousels use it as the
+     * cross-axis item size. Hero carousels size their large item to the container.
+     *
+     * @defaultValue `240`
+     */
+    itemSize?: number | undefined;
+    /**
+     * Space between items, in pixels.
+     *
+     * @defaultValue `8`
+     */
+    itemGap?: number | undefined;
+    /**
+     * Scrolling axis.
+     *
+     * @defaultValue `"horizontal"`
+     */
+    orientation?: "horizontal" | "vertical" | undefined;
+    /**
+     * Snap items while scrolling an uncontained carousel.
+     *
+     * Other arrangements always snap, one item at a time.
+     *
+     * @defaultValue `false`
+     */
+    snap?: boolean | undefined;
+    /**
+     * Open an alternative view of the entire collection.
+     *
+     * Supplying this callback renders a Show all action, including when directional controls
+     * are hidden. Vertical carousels should provide this alternative browsing path.
+     *
+     * @param event - activating click event
+     */
+    onShowAll?: ((event: MouseEvent) => void) | undefined;
+    /**
+     * Label of the Show all action.
+     *
+     * @defaultValue `"Show all"`
+     */
+    showAllLabel?: string | undefined;
+    /**
+     * Wrap previous and next navigation around the ends.
+     *
+     * @defaultValue `false`
+     */
+    loop?: boolean | undefined;
+    /**
+     * Show the previous and next controls.
+     *
+     * @defaultValue `true`
+     */
+    showControls?: boolean | undefined;
+    /**
+     * Number of items, used to render exact labels and control states on the server.
+     *
+     * The client counts the rendered items.
+     */
+    itemCount?: number | undefined;
+    /**
+     * Accessible name of the carousel region.
+     *
+     * @defaultValue `"Carousel"`
+     */
+    label?: string | undefined;
+    /**
+     * Notify the parent of an active item change.
+     *
+     * Uncontrolled carousels notify after changing. Controlled carousels request the change and
+     * keep the controlled index until the parent accepts it.
+     *
+     * @param index - new or requested active index
+     * @param event - control or keyboard event, or `undefined` when scrolling changed the index
+     */
+    onIndexChange?: ((index: number, event?: Event) => void) | undefined;
+    /**
+     * Label of the previous control.
+     *
+     * @defaultValue `"Previous"`
+     */
+    previousLabel?: string | undefined;
+    /**
+     * Label of the next control.
+     *
+     * @defaultValue `"Next"`
+     */
+    nextLabel?: string | undefined;
+};
+/**
+ * Properties accepted by {@link CarouselItem}.
+ */
+export type CarouselItemProps = DomProps<HTMLDivElement, Omit<JSX.HTMLAttributes<HTMLDivElement>, "role" | "aria-roledescription">> & {
+    /**
+     * Accessible item label.
+     *
+     * @defaultValue `"Slide <n> of <count>"`
+     */
+    label?: string | undefined;
+    /**
+     * Width-to-height ratio of the item in a multi-aspect-ratio carousel.
+     *
+     * The ratio is clamped to 9:16–16:9. Horizontal carousels share a common item height;
+     * vertical carousels share a common item width.
+     *
+     * @defaultValue `1`
+     */
+    aspectRatio?: number | undefined;
+};
+/**
+ * Client controller of a {@link Carousel}.
+ *
+ * Items are laid out end-to-end in a native scroll container. User scrolling, including fling and
+ * snapping, is native; keyline arrangements snap one item at a time through CSS scroll snapping,
+ * with per-item snap margins derived from the keyline {@link ./carousel-layout#CarouselStrategy |
+ * strategy}. While scrolling, each animation frame reads the scroll offset once and writes the
+ * mask of the items near the viewport. Programmatic scrolling, from controls, keys, or a changed
+ * controlled index, is smooth unless the user prefers reduced motion.
+ */
+export declare class CarouselController extends DomController<CarouselProps> {
+    #private;
+    /**
+     * Construct a new `CarouselController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: CarouselProps);
+    /**
+     * 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.
+     *
+     * @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;
+}
+/**
+ * Material carousel of full-screen, multi-browse, hero, center-aligned hero, uncontained, and
+ * multi-aspect-ratio uncontained arrangements.
+ *
+ * Items are {@link CarouselItem}s. Keyline arrangements size and mask items following the Material
+ * 3 keyline model: items shrink and translate between large, medium, and small keylines while
+ * scrolling, and snap one item at a time. Scrolling is native; keyboard users navigate with the
+ * arrow, Home, and End keys of the scrolling axis while the viewport is focused, or with the
+ * previous and next controls.
+ *
+ * # States
+ *
+ * The active item has `aria-current="true"`. Omitting {@link CarouselProps.index | `index`}
+ * enables uncontrolled state initialized by {@link CarouselProps.defaultIndex | `defaultIndex`};
+ * supplying it requires the parent to accept index requests.
+ *
+ * # Design
+ *
+ * The carousel region has the `cw-Carousel` class and `data-cw-carousel-layout`,
+ * `data-cw-carousel-orientation`, and `data-cw-carousel-snap` attributes. Items have the
+ * `cw-Carousel-slide` class; their content is masked by the inner `cw-Carousel-mask` element.
+ *
+ * @param props - component properties
+ * @returns rendered carousel
+ */
+export declare const Carousel: DomComponent<CarouselProps>;
+/**
+ * One item of a {@link Carousel}.
+ *
+ * Items are `group`s with the `slide` role description. Unless labelled, an item is named after
+ * its position, such as "Slide 2 of 6".
+ *
+ * @param props - component properties
+ * @returns rendered item
+ */
+export declare const CarouselItem: DomComponent<CarouselItemProps>;
+/**
+ * Alias of {@link CarouselItem}.
+ *
+ * @param props - component properties
+ * @returns rendered item
+ */
+export declare const CarouselSlide: DomComponent<CarouselItemProps>;