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

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

@@ -0,0 +1,384 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps, StyleElement } from "..";
+import type { DialogCloseReason, DialogProps } from "./dialog";
+import { DomController } from "../dom/client";
+import { DialogController } from "./dialog";
+import "../container/elevation-shadow.css";
+import "./surface.css";
+/**
+ * Bottom-sheet expansion request callback.
+ *
+ * @param expanded - requested expansion state
+ * @param event - originating event, if any
+ */
+export type BottomSheetExpansionHandler = (expanded: boolean, event?: Event) => void;
+/**
+ * Properties shared by {@link ModalBottomSheet} and {@link BottomSheet}.
+ */
+export type BottomSheetBaseProps = {
+    /**
+     * Accessible name used when no `aria-label` is supplied.
+     *
+     * @defaultValue `"Bottom sheet"`
+     */
+    label?: string | undefined;
+    /**
+     * Sheet can be dismissed by the user.
+     *
+     * A dismissible sheet can be dragged out of view; a modal sheet is also dismissed by Escape,
+     * the scrim, and its drag handle. Programmatic closure is always possible.
+     */
+    dismissible?: boolean | undefined;
+    /**
+     * Show the drag handle.
+     *
+     * The handle is a button which changes the sheet's detent; it can also be dragged.
+     *
+     * @defaultValue `true`
+     */
+    dragHandle?: boolean | undefined;
+    /**
+     * Custom drag handle content, which replaces the handle bar.
+     */
+    dragHandleContent?: JSX.Element;
+    /**
+     * Handle a user dismissal *before* closure is requested.
+     *
+     * Call `event.preventDefault()`, when an event is supplied, to keep the sheet open.
+     *
+     * @remarks
+     * This is **not** reactive.
+     *
+     * @param event - originating event, if any
+     */
+    onDismiss?: ((event?: Event) => void) | undefined;
+};
+/**
+ * Properties accepted by {@link ModalBottomSheet}.
+ */
+export type ModalBottomSheetProps = Omit<DialogProps, "modal" | "role"> & BottomSheetBaseProps & {
+    /**
+     * Accessible name of the drag handle while it dismisses the sheet.
+     *
+     * @defaultValue `"Close bottom sheet"`
+     */
+    closeLabel?: string | undefined;
+    /**
+     * Accessible name of the drag handle while it expands a partially expanded sheet.
+     *
+     * @defaultValue `"Expand bottom sheet"`
+     */
+    expandLabel?: string | undefined;
+    /**
+     * Skip the partially expanded detent.
+     *
+     * Without this, a sheet taller than half the viewport opens partially expanded, showing half
+     * the viewport, as Compose `ModalBottomSheet`; dragging it up, or activating its drag handle,
+     * expands it.
+     *
+     * @defaultValue `false`
+     */
+    skipPartiallyExpanded?: boolean | undefined;
+};
+/**
+ * Properties accepted by {@link BottomSheet}.
+ */
+export type BottomSheetProps = DomProps<HTMLDivElement, Omit<JSX.HTMLAttributes<HTMLDivElement>, "role" | "aria-expanded" | "aria-hidden">> & BottomSheetBaseProps & {
+    /**
+     * Controlled open state.
+     *
+     * Supplying this property, even as `undefined`, makes the open state controlled.
+     */
+    open?: boolean | undefined;
+    /**
+     * Initial open state of an uncontrolled sheet.
+     *
+     * @remarks
+     * This is **not** reactive.
+     *
+     * @defaultValue `false`
+     */
+    defaultOpen?: boolean | undefined;
+    /**
+     * Height of the collapsed sheet, in CSS pixels or as a CSS length.
+     *
+     * When omitted, an enclosing scaffold's `sheetPeekHeight` or the `sheetPeekHeight` role
+     * applies.
+     */
+    peekHeight?: number | string | undefined;
+    /**
+     * Controlled expansion state.
+     *
+     * Supplying this property, even as `undefined`, makes expansion controlled.
+     */
+    expanded?: boolean | undefined;
+    /**
+     * Initial expansion state of a sheet with uncontrolled expansion.
+     *
+     * @remarks
+     * This is **not** reactive.
+     *
+     * @defaultValue `false`
+     */
+    defaultExpanded?: boolean | undefined;
+    /**
+     * Accessible name of the drag handle while the sheet is collapsed.
+     *
+     * @defaultValue `"Expand bottom sheet"`
+     */
+    expandLabel?: string | undefined;
+    /**
+     * Accessible name of the drag handle while the sheet is expanded.
+     *
+     * @defaultValue `"Collapse bottom sheet"`
+     */
+    collapseLabel?: string | undefined;
+    /**
+     * Handle a request to change the open state.
+     *
+     * @remarks
+     * This is **not** reactive.
+     *
+     * @param open - requested open state
+     * @param event - originating event, if any
+     */
+    onOpenChange?: ((open: boolean, event?: Event) => void) | undefined;
+    /**
+     * Handle a request to change the expansion state.
+     *
+     * @remarks
+     * This is **not** reactive.
+     */
+    onExpandedChange?: BottomSheetExpansionHandler | undefined;
+};
+/**
+ * Client controller of a {@link ModalBottomSheet}.
+ *
+ * The native dialog lifecycle is that of {@link DialogController}; this controller adds the
+ * partially expanded and expanded detents, the drag gesture and its settling spring, and the drag
+ * handle.
+ */
+export declare class ModalBottomSheetController extends DialogController<ModalBottomSheetProps> {
+    #private;
+    /**
+     * Construct a new `ModalBottomSheetController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: ModalBottomSheetProps);
+    /**
+     * Default accessible name, used when no `aria-label` is supplied.
+     *
+     * @returns accessible name
+     */
+    protected defaultLabel(): string | undefined;
+    /**
+     * Test whether a user dismissal may close the sheet.
+     *
+     * A sheet which is not {@link BottomSheetBaseProps.dismissible | dismissible} vetoes every
+     * user dismissal; otherwise `onDismiss` may veto it.
+     *
+     * @param _reason - dismissal reason
+     * @param event - originating event, if any
+     * @returns `true` if, and only if, the dismissal is allowed
+     */
+    protected allowDismiss(_reason: DialogCloseReason, event: Event | undefined): boolean;
+    /**
+     * Request closure for a user dismissal.
+     *
+     * A close request, such as Escape, first collapses an expanded sheet to its partially expanded
+     * detent, as Compose `ModalBottomSheet` does for back navigation.
+     *
+     * @param reason - dismissal reason
+     * @param event - originating event, if any
+     */
+    protected requestDismiss(reason: DialogCloseReason, event: Event | undefined): void;
+    /**
+     * Reset the detent and prepare the entry when the sheet opens, and stop tracking it when it
+     * closes.
+     *
+     * @param open - applied open state
+     */
+    protected onOpenStateChanged(open: boolean): void;
+    /**
+     * Slide an opening sheet in on the settling spring, from out of view or from where its closing
+     * left it.
+     *
+     * As Compose's `SheetState.show()`, the entry runs through the sheet's offset, so that a drag
+     * interrupts it and its overshoot is covered as that of a settle.
+     */
+    protected onShown(): 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.
+     *
+     * The drag handle content is a reactive slot.
+     *
+     * @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 the gesture, observer, and handle listener when the controller is disposed.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+}
+/**
+ * Material modal bottom sheet.
+ *
+ * A modal bottom sheet is a native modal dialog anchored to the bottom edge, at most the
+ * `sheetMaxWidth` role wide, above a scrim. A sheet taller than half the viewport opens partially
+ * expanded, showing half of the viewport. The drag handle expands a partially expanded sheet and
+ * otherwise dismisses it. The sheet can be dragged by its handle with any pointer and by its
+ * surface with touch, and a downward wheel scroll over a partially expanded sheet expands it.
+ * Escape collapses an expanded sheet which has a partially expanded detent, and otherwise
+ * dismisses it, as Compose's back handling; the scrim dismisses it.
+ *
+ * A released drag settles as Compose sheets do: a fling of at least 125 pixels per second moves on
+ * to the next detent in its direction, and a slower release moves on only after 56 pixels of
+ * travel; settling below the lowest detent dismisses the sheet unless it is not {@link
+ * BottomSheetBaseProps.dismissible | dismissible} or `onDismiss` vetoes it.
+ *
+ * # Motion
+ *
+ * The sheet slides in, between detents, and after a drag on a runtime default spatial spring, as
+ * Compose `SheetState` animates its offset: a settle continues the release velocity, a new drag
+ * interrupts the spring where it is, and an overshoot above the expanded position stretches the
+ * sheet instead of opening a gap below it. The sheet slides out on the fast effects spring, as
+ * Compose `BottomSheet`'s hide motion, and the scrim fades on the default effects spring, as
+ * Compose `ModalBottomSheet`.
+ *
+ * # Design
+ *
+ * Sheet design is controlled through the `sheet*`, `dragHandle*`, and `dialogScrim*` roles of the
+ * [`cw-Surface`](./surface.yaml) design attribute. The `cw-ModalBottomSheet-open` and
+ * `cw-ModalBottomSheet-expanded` classes reflect the sheet state, and `cw-BottomSheet-dragging` is
+ * applied while it is dragged.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const ModalBottomSheet: DomComponent<ModalBottomSheetProps>;
+/**
+ * Client controller of a {@link BottomSheet}.
+ */
+export declare class BottomSheetController extends DomController<BottomSheetProps> {
+    #private;
+    /**
+     * Construct a new `BottomSheetController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: BottomSheetProps);
+    /**
+     * Request that the sheet open.
+     *
+     * A controlled sheet requests the change through `onOpenChange` and waits for the parent to
+     * update `open`.
+     */
+    open(): void;
+    /**
+     * Request that the sheet close.
+     *
+     * Programmatic closure is never vetoed by {@link BottomSheetBaseProps.dismissible |
+     * `dismissible`} or `onDismiss`. A controlled sheet requests the change through `onOpenChange`
+     * and stays open until the parent updates `open`.
+     *
+     * @param event - originating event, if any
+     */
+    close(event?: Event): void;
+    /**
+     * Request the expanded detent.
+     *
+     * When `expanded` is controlled, the change is requested through `onExpandedChange`.
+     *
+     * @param event - originating event, if any
+     */
+    expand(event?: Event): void;
+    /**
+     * Request the collapsed (peek) detent.
+     *
+     * When `expanded` is controlled, the change is requested through `onExpandedChange`.
+     *
+     * @param event - originating event, if any
+     */
+    collapse(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.
+     *
+     * The drag handle content is a reactive slot.
+     *
+     * @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 the gesture and listeners when the controller is disposed.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+}
+/**
+ * Material standard bottom sheet.
+ *
+ * A standard bottom sheet is a nonmodal region which peeks from the bottom edge, at most the
+ * `sheetMaxWidth` role wide, and expands over the content. On its own it is fixed to the
+ * viewport; in a {@link ./scaffold#Scaffold | scaffold} it sits above the bottom bar. The drag
+ * handle toggles between the peek and expanded detents. The sheet can be dragged by its handle
+ * with any pointer and by its surface with touch, and settles as a {@link ModalBottomSheet} does;
+ * as Compose's standard sheet, it cannot be dragged out of view unless it is {@link
+ * BottomSheetBaseProps.dismissible | dismissible}. Keyboard focus entering the collapsed content
+ * expands the sheet; collapsing moves focus from the content to the drag handle, and closing
+ * moves focus out of the sheet.
+ *
+ * # Motion
+ *
+ * The sheet slides in, between detents, and after a drag on a runtime default spatial spring, as
+ * Compose `SheetState` animates its offset, and slides out on the fast effects spring, as Compose
+ * `BottomSheet`'s hide motion; see {@link ModalBottomSheet}.
+ *
+ * # Design
+ *
+ * Sheet design is controlled through the `sheet*` and `dragHandle*` roles of the
+ * [`cw-Surface`](./surface.yaml) design attribute. The `cw-BottomSheet-open` and
+ * `cw-BottomSheet-expanded` classes reflect the sheet state, and `cw-BottomSheet-dragging` is
+ * applied while it is dragged.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const BottomSheet: DomComponent<BottomSheetProps>;

package/target/tsc/surface/side-sheet.d.ts

@@ -0,0 +1,183 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, StyleElement } from "..";
+import type { DialogCloseReason, DialogProps } from "./dialog";
+import { DialogController } from "./dialog";
+import "../container/elevation-shadow.css";
+import "./surface.css";
+/**
+ * Properties accepted by {@link StandardSideSheet} and {@link ModalSideSheet}.
+ */
+export type SideSheetProps = Omit<DialogProps, "modal"> & {
+    /**
+     * Logical edge the sheet is attached to.
+     *
+     * @defaultValue `"end"`
+     */
+    edge?: "start" | "end" | undefined;
+    /**
+     * Detach the sheet from the viewport edges, with rounded corners.
+     *
+     * @defaultValue `false`
+     */
+    detached?: boolean | undefined;
+    /**
+     * Headline, which also names the sheet when no `aria-label`, `aria-labelledby`, or `label` is
+     * supplied.
+     */
+    header?: JSX.Element;
+    /**
+     * Leading header content, such as a back icon button.
+     */
+    leadingIcon?: JSX.Element;
+    /**
+     * Scrolling body. Children are used when omitted.
+     */
+    body?: JSX.Element;
+    /**
+     * Actions, below a divider at the bottom of the sheet.
+     */
+    actions?: JSX.Element;
+    /**
+     * Sheet can be dismissed by the user.
+     *
+     * A dismissible sheet shows a close icon button; a modal one is also dismissed by Escape and
+     * the scrim. Programmatic closure is always possible.
+     *
+     * @defaultValue `true`
+     */
+    dismissible?: boolean | undefined;
+    /**
+     * Accessible name of the close icon button.
+     *
+     * @defaultValue `"Close side sheet"`
+     */
+    dismissLabel?: string | undefined;
+};
+/**
+ * Properties of the side sheet implementation, which presents a standard or a modal sheet.
+ */
+type SideSheetBaseProps = SideSheetProps & {
+    /**
+     * Sheet is modal.
+     */
+    modal: boolean;
+};
+/**
+ * Client controller of a {@link StandardSideSheet} or {@link ModalSideSheet}.
+ *
+ * The native dialog lifecycle is that of {@link DialogController}: a standard sheet is shown
+ * nonmodally and a modal sheet modally. This controller adds the header naming, the close icon
+ * button, and the edge and detachment classes.
+ */
+export declare class SideSheetController extends DialogController<SideSheetBaseProps> {
+    #private;
+    /**
+     * Construct a new `SideSheetController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: SideSheetBaseProps);
+    /**
+     * Default accessible name, used when no naming attribute applies.
+     *
+     * A `label` takes precedence over the headline.
+     *
+     * @returns accessible name, or `undefined` when the headline names the sheet
+     */
+    protected defaultLabel(): string | undefined;
+    /**
+     * Identifier of the headline, which names the sheet unless a `label` is supplied.
+     *
+     * @returns headline identifier, or `undefined` without a headline or with a `label`
+     */
+    protected defaultLabelledBy(): string | undefined;
+    /**
+     * Test whether a user dismissal may close the sheet.
+     *
+     * @param _reason - dismissal reason
+     * @param _event - originating event, if any
+     * @returns `true` if, and only if, the sheet is {@link SideSheetProps.dismissible |
+     * dismissible}
+     */
+    protected allowDismiss(_reason: DialogCloseReason, _event: Event | undefined): boolean;
+    /**
+     * 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.
+     *
+     * The headline, leading icon, body, and actions are reactive slots.
+     *
+     * @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 the action listener when the controller is disposed.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+}
+/**
+ * Material standard side sheet.
+ *
+ * A standard side sheet shows content which complements the main content without blocking it:
+ * a nonmodal dialog attached to the {@link SideSheetProps.edge | edge} of the viewport, or placed
+ * in a {@link ./scaffold#SupportingPaneScaffold | pane}, which it then fills, docked beside the
+ * main pane. Its header holds an optional leading icon, the headline, which names the sheet, and
+ * a close icon button; actions sit below a divider at the bottom. Closing it returns focus to its
+ * opener only while focus is within the sheet.
+ *
+ * # Motion
+ *
+ * Opening slides the sheet in from its edge on the default spatial spring; closing slides it out
+ * on the fast effects spring, as the bottom sheets.
+ *
+ * # Design
+ *
+ * Side sheet design is controlled through the `sideSheet*` roles of the
+ * [`cw-Surface`](./surface.yaml) design attribute, after `md.comp.sheet.side`: the docked
+ * container is 256 pixels wide, on the surface color without elevation, and a detached sheet is
+ * inset by a margin and fully rounded. The `cw-SideSheet-open` class is applied while the sheet is
+ * open.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const StandardSideSheet: DomComponent<SideSheetProps>;
+/**
+ * Material modal side sheet.
+ *
+ * A modal side sheet is a {@link StandardSideSheet} presented as a native modal dialog above a
+ * scrim: the rest of the document is inert, Escape and the scrim dismiss it, and focus returns to
+ * its opener when it closes.
+ *
+ * # Motion
+ *
+ * The sheet slides as a {@link StandardSideSheet} does, and the scrim fades on the default effects
+ * spring.
+ *
+ * # Design
+ *
+ * The modal container takes the `sideSheetModalColor` and `sideSheetModalElevation` roles, and its
+ * inner corners the `sideSheetShape` role.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const ModalSideSheet: DomComponent<SideSheetProps>;
+export {};

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

@@ -0,0 +1,21 @@
+/**
+ * Resolve JSX slot properties in author order before the containing component claims its
+ * hydration key.
+ *
+ * Server rendering evaluates slot properties when the renderer reads them, while a client
+ * controller may read them in a different order, or not at all until an effect runs. Resolving
+ * every slot named in `names` up front, in the order the author wrote the properties, makes slot
+ * components consume hydration keys and unique identifiers in the same order on the server and the
+ * client, whatever order the renderers read them in. Each resolved slot is cached, so reading it
+ * again neither re-creates its elements nor moves them.
+ *
+ * Slots named in `factories` are cached as values instead of being resolved as children, so a
+ * function value, such as a render-prop factory, remains callable.
+ *
+ * @typeParam P - component properties type
+ * @param props - component properties
+ * @param names - JSX slot properties to resolve
+ * @param factories - slot properties whose function values must remain callable
+ * @returns properties with reactive, cached slot values
+ */
+export declare function resolveSurfaceSlots<P extends object>(props: P, names: readonly string[], factories?: readonly string[]): P;

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

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