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

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

@@ -0,0 +1,582 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps, StyleElement } from "..";
+import { DomController } from "../dom/client";
+import "../container/elevation-shadow.css";
+import "./surface.css";
+/**
+ * Reason a dialog was requested to open or close.
+ *
+ * | Reason           | Request                                                              |
+ * | ---------------- | -------------------------------------------------------------------- |
+ * | `"backdrop"`     | the modal backdrop (scrim) was activated                             |
+ * | `"cancel"`       | a close request, such as Escape, was not cancelled by `onCancel`     |
+ * | `"close"`        | the native dialog closed itself, e.g. `<form method="dialog">`       |
+ * | `"confirm"`      | the confirming action was activated                                  |
+ * | `"dismiss"`      | a dismissing control or gesture, e.g. a cancel action or drag handle |
+ * | `"programmatic"` | a controller method or a controlled `open` change                    |
+ */
+export type DialogCloseReason = "backdrop" | "cancel" | "close" | "confirm" | "dismiss" | "programmatic";
+/**
+ * Notify the parent that a dialog open-state change was requested.
+ *
+ * @param open - requested open state
+ * @param event - originating event, if any
+ * @param reason - reason for the request, when available
+ */
+export type DialogOpenChangeHandler = (open: boolean, event?: Event, reason?: DialogCloseReason) => void;
+/**
+ * Properties accepted by {@link Dialog}.
+ */
+export type DialogProps = DomProps<HTMLDialogElement, Omit<JSX.HTMLAttributes<HTMLDialogElement>, "open" | "role" | "aria-modal" | "tabindex" | "tabIndex">> & {
+    /**
+     * Controlled open state.
+     *
+     * Supplying this property, even as `undefined`, makes the open state controlled: user and
+     * programmatic requests invoke {@link DialogProps.onOpenChange | `onOpenChange`}, and the
+     * dialog changes only when the parent updates this property.
+     */
+    open?: boolean | undefined;
+    /**
+     * Initial open state of an uncontrolled dialog.
+     *
+     * @remarks
+     * This is **not** reactive.
+     *
+     * @defaultValue `false`
+     */
+    defaultOpen?: boolean | undefined;
+    /**
+     * Dialog is modal.
+     *
+     * A modal dialog opens with `showModal()`: it is placed in the top layer above a scrim, the
+     * rest of the document is inert, and Tab wraps within the dialog. A nonmodal dialog opens with
+     * `show()`.
+     *
+     * @defaultValue `true`
+     */
+    modal?: boolean | undefined;
+    /**
+     * Accessible dialog role.
+     *
+     * @defaultValue `"dialog"`
+     */
+    role?: "dialog" | "alertdialog" | undefined;
+    /**
+     * Accessible name used when neither `aria-label` nor `aria-labelledby` is supplied.
+     *
+     * @defaultValue `"Dialog"`
+     */
+    label?: string | undefined;
+    /**
+     * Restore focus to the element which was focused before the dialog opened.
+     *
+     * Focus is restored when the dialog closes while it, or nothing, has focus; focus which the
+     * user moved elsewhere stays where it is. For a modal dialog, the value is read when the dialog
+     * opens, since the browser's own modal close steps restore focus: `false` then opens the dialog
+     * without a previously focused element to return to.
+     *
+     * @defaultValue `true`
+     */
+    returnFocus?: boolean | undefined;
+    /**
+     * CSS selector or element to focus after opening.
+     *
+     * When omitted, or when the target cannot be focused, the first `autofocus` element, the first
+     * focusable element, or the dialog itself is focused.
+     */
+    initialFocus?: string | HTMLElement | undefined;
+    /**
+     * Close when the backdrop (scrim) of a modal dialog is activated.
+     *
+     * The backdrop counts as activated only when the pointer is both pressed and released on it,
+     * so a text selection which ends on the backdrop does not close the dialog.
+     *
+     * @defaultValue `true`
+     */
+    closeOnBackdrop?: boolean | undefined;
+    /**
+     * Sequential focus index of the dialog element itself.
+     */
+    tabIndex?: number | undefined;
+    /**
+     * Handle a user or programmatic request to change the open state.
+     *
+     * Invoked for controlled and uncontrolled dialogs; an uncontrolled dialog has already applied
+     * the change when this is invoked.
+     */
+    onOpenChange?: DialogOpenChangeHandler | undefined;
+    /**
+     * Handle the native dialog `close` event.
+     *
+     * Close events caused by the dialog switching between modal and nonmodal presentation are not
+     * reported.
+     *
+     * @param event - native close event
+     */
+    onClose?: ((event: Event) => void) | undefined;
+    /**
+     * Handle a close request, such as Escape.
+     *
+     * Call `event.preventDefault()` to keep the dialog open; otherwise, closure is requested with
+     * the `"cancel"` reason.
+     *
+     * @param event - cancel event
+     */
+    onCancel?: ((event: Event) => void) | undefined;
+};
+/**
+ * Properties accepted by {@link AlertDialog}.
+ */
+export type AlertDialogProps = DialogProps & {
+    /**
+     * Hero icon shown above the headline, which is then centered.
+     */
+    icon?: JSX.Element;
+    /**
+     * Headline, which also names the dialog when no `aria-label`, `aria-labelledby`, or `label`
+     * is supplied.
+     */
+    title?: JSX.Element;
+    /**
+     * Supporting text, which describes the dialog. Children are used when omitted.
+     */
+    text?: JSX.Element;
+    /**
+     * Alias for {@link AlertDialogProps.text | `text`}.
+     */
+    supportingText?: JSX.Element;
+    /**
+     * Content of the confirming action.
+     *
+     * @defaultValue `"OK"`
+     */
+    confirmLabel?: JSX.Element;
+    /**
+     * Content of the dismissing action.
+     *
+     * @defaultValue `"Cancel"`
+     */
+    dismissLabel?: JSX.Element;
+    /**
+     * Show the dismissing action.
+     *
+     * @defaultValue `true`
+     */
+    showDismiss?: boolean | undefined;
+    /**
+     * Handle activation of the confirming action before closure is requested.
+     *
+     * Call `event.preventDefault()` to keep the dialog open.
+     *
+     * @param event - click event
+     */
+    onConfirm?: ((event: Event) => void) | undefined;
+    /**
+     * Handle activation of the dismissing action before closure is requested.
+     *
+     * Call `event.preventDefault()` to keep the dialog open.
+     *
+     * @param event - click event
+     */
+    onDismiss?: ((event: Event) => void) | undefined;
+};
+/**
+ * Properties accepted by {@link FullScreenDialog}.
+ */
+export type FullScreenDialogProps = Omit<DialogProps, "closeOnBackdrop" | "modal" | "role"> & {
+    /**
+     * Headline, which also names the dialog when no `aria-label`, `aria-labelledby`, or `label`
+     * is supplied.
+     */
+    title?: JSX.Element;
+    /**
+     * Content of the confirming header action. The action is omitted when this is omitted.
+     */
+    confirmLabel?: JSX.Element;
+    /**
+     * Accessible name of the close action.
+     *
+     * @defaultValue `"Close"`
+     */
+    closeLabel?: string | undefined;
+    /**
+     * Icon of the close action. A close glyph is used when omitted.
+     */
+    closeIcon?: JSX.Element;
+    /**
+     * Handle activation of the confirming action before closure is requested.
+     *
+     * Call `event.preventDefault()` to keep the dialog open.
+     *
+     * @param event - click event
+     */
+    onConfirm?: ((event: Event) => void) | undefined;
+    /**
+     * Handle activation of the close action before closure is requested.
+     *
+     * Call `event.preventDefault()` to keep the dialog open.
+     *
+     * @param event - click event
+     */
+    onDismiss?: ((event: Event) => void) | undefined;
+};
+/**
+ * Determine the focused element of the document or shadow root containing a node.
+ *
+ * @param node - node in the document or shadow root
+ * @returns focused element, or `null` when no element has focus
+ */
+export declare function activeElementOf(node: Node): HTMLElement | null;
+/**
+ * Client controller of a native `<dialog>`.
+ *
+ * The controller owns the open state, the native modal or nonmodal presentation, focus placement
+ * and restoration, close requests, and the accessible naming of the dialog element. It uses
+ * element-local listeners and native dialog events, so multiple dialogs can coexist without
+ * document-level listeners. Subclasses render their own anatomy and may veto or reinterpret user
+ * dismissal through {@link DialogController.allowDismiss | `allowDismiss`} and {@link
+ * DialogController.requestDismiss | `requestDismiss`}.
+ *
+ * # States
+ *
+ * | Method                                   | Uncontrolled          | Controlled          |
+ * | ---------------------------------------- | --------------------- | ------------------- |
+ * | {@link DialogController.open | `open`}   | opens, then notifies  | asks `onOpenChange` |
+ * | {@link DialogController.close | `close`} | closes, then notifies | asks `onOpenChange` |
+ *
+ * While the dialog is open, the `<css>-open` class is applied, where `<css>` is the public CSS
+ * class name the controller is constructed with. In an engine which does not {@link
+ * supportsOverlay | support `overlay`}, the private `_<css>-closing` class is applied while a
+ * closed dialog exits with its native dialog still open.
+ *
+ * @typeParam P - component properties type
+ */
+export declare class DialogController<P extends DialogProps = DialogProps> extends DomController<P> {
+    #private;
+    /**
+     * Construct a new `DialogController`.
+     *
+     * @param props - component properties
+     * @param cssClassName - public CSS class name of the component
+     */
+    constructor(props: P, cssClassName?: string);
+    /**
+     * Default ARIA role, used when no role is supplied.
+     *
+     * @returns default role
+     */
+    protected defaultRole(): "dialog" | "alertdialog";
+    /**
+     * Default accessible name, used when no naming attribute or labelling element applies.
+     *
+     * @returns accessible name, or `undefined` for none
+     */
+    protected defaultLabel(): string | undefined;
+    /**
+     * Identifier of the element which names the dialog by default.
+     *
+     * An authored `aria-label` or `aria-labelledby` takes precedence.
+     *
+     * @returns element identifier, or `undefined` for none
+     */
+    protected defaultLabelledBy(): string | undefined;
+    /**
+     * Identifier of the element which describes the dialog by default.
+     *
+     * An authored `aria-describedby` takes precedence.
+     *
+     * @returns element identifier, or `undefined` for none
+     */
+    protected defaultDescribedBy(): string | undefined;
+    /**
+     * Test whether a user dismissal may close the dialog.
+     *
+     * Programmatic closure through {@link DialogController.close | `close`} is never vetoed.
+     *
+     * @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, such as Escape or a backdrop activation.
+     *
+     * The base implementation closes the dialog when {@link DialogController.allowDismiss |
+     * `allowDismiss`} allows it.
+     *
+     * @param reason - dismissal reason
+     * @param event - originating event, if any
+     */
+    protected requestDismiss(reason: DialogCloseReason, event: Event | undefined): void;
+    /**
+     * Handle a change of the applied open state, *before* the native dialog is shown or closed.
+     *
+     * @param _open - applied open state
+     */
+    protected onOpenStateChanged(_open: boolean): void;
+    /**
+     * Handle the presentation of the native dialog, once it was shown with its current modality.
+     *
+     * This is invoked whenever the dialog is presented: after it opens, after its modality
+     * changes, and when it is presented once hydrated or connected.
+     */
+    protected onShown(): void;
+    /**
+     * Test whether the dialog is open.
+     *
+     * @returns `true` if, and only if, the dialog is open
+     */
+    isOpen(): boolean;
+    /**
+     * Request that the dialog open.
+     *
+     * A controlled dialog requests the change through `onOpenChange` and waits for the parent to
+     * update `open`; an uncontrolled dialog opens, then notifies `onOpenChange`.
+     */
+    open(): void;
+    /**
+     * Request that the dialog close.
+     *
+     * A controlled dialog requests the change through `onOpenChange` and stays open until the
+     * parent updates `open`; an uncontrolled dialog closes, then notifies `onOpenChange`.
+     *
+     * @param reason - close reason
+     * @param event - originating event, if any
+     */
+    close(reason?: DialogCloseReason, event?: Event): void;
+    /**
+     * Request the opposite of the current open state.
+     *
+     * @see {@link DialogController.open}
+     * @see {@link DialogController.close}
+     */
+    toggle(): 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.
+     *
+     * @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;
+    /**
+     * Close the dialog and release its listeners when the controller is disposed.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+}
+/**
+ * Native modal or nonmodal dialog container.
+ *
+ * A dialog places its children on a Material dialog container: the `dialogColor`, `dialogShape`,
+ * `dialogElevation`, and `dialogPadding` roles, between the minimum and maximum dialog widths, and
+ * within the viewport margin. A modal dialog uses the browser top layer above a scrim; Escape and
+ * backdrop activation request closure, and focus returns to its opener. For the Material basic
+ * dialog anatomy, use {@link AlertDialog}; for a full-screen dialog, use {@link FullScreenDialog}.
+ *
+ * # Motion
+ *
+ * Opening fades the container in on the default effects spring and scales it up from 80% on the
+ * default spatial spring, as MDC's `m3_motion_fade_enter`; closing fades it out on the fast
+ * effects spring, as `m3_motion_fade_exit`. The scrim fades on the same effects springs.
+ *
+ * # Design
+ *
+ * Dialog design is controlled through the `dialog*` roles of the [`cw-Surface`](./surface.yaml)
+ * design attribute. The `cw-Dialog-open` class is applied while the dialog is open.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const Dialog: DomComponent<DialogProps>;
+/**
+ * Client controller of an {@link AlertDialog}.
+ */
+export declare class AlertDialogController extends DialogController<AlertDialogProps> {
+    #private;
+    /**
+     * Construct a new `AlertDialogController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: AlertDialogProps);
+    /**
+     * Default ARIA role, used when no role is supplied.
+     *
+     * @returns `"alertdialog"`
+     */
+    protected defaultRole(): "dialog" | "alertdialog";
+    /**
+     * 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 dialog
+     */
+    protected defaultLabel(): string | undefined;
+    /**
+     * Identifier of the headline, which names the dialog unless a `label` is supplied.
+     *
+     * @returns headline identifier, or `undefined` without a headline or with a `label`
+     */
+    protected defaultLabelledBy(): string | undefined;
+    /**
+     * Identifier of the supporting text, which describes the dialog.
+     *
+     * @returns supporting text identifier
+     */
+    protected defaultDescribedBy(): string | undefined;
+    /**
+     * 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 icon, headline, supporting text, and action labels 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 basic dialog.
+ *
+ * An alert dialog presents an optional hero icon, a headline, supporting text, and dismissing and
+ * confirming text buttons on the {@link Dialog} container. The headline names the dialog and the
+ * supporting text describes it. The anatomy and spacing follow Compose `AlertDialog`: with an
+ * icon, the headline is centered below it. Supporting text which does not fit scrolls between the
+ * fixed headline and actions, and dividers mark scrolled-away content, as material-web dialogs.
+ *
+ * Activating an action invokes `onConfirm` or `onDismiss`, then requests closure with the
+ * `"confirm"` or `"dismiss"` reason unless the callback called `event.preventDefault()`. Initial
+ * focus goes to the dismissing action, the least destructive choice.
+ *
+ * # Design
+ *
+ * Alert dialog design is controlled through the `dialog*` roles of the
+ * [`cw-Surface`](./surface.yaml) design attribute; the headline uses the headline-small
+ * typescale, the supporting text body-medium, and the actions are `text` buttons. The
+ * `cw-AlertDialog-noDismiss` class is applied while the dismissing action is hidden.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const AlertDialog: DomComponent<AlertDialogProps>;
+/**
+ * Client controller of a {@link FullScreenDialog}.
+ */
+export declare class FullScreenDialogController extends DialogController<FullScreenDialogProps> {
+    #private;
+    /**
+     * Construct a new `FullScreenDialogController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: FullScreenDialogProps);
+    /**
+     * 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 dialog
+     */
+    protected defaultLabel(): string | undefined;
+    /**
+     * Identifier of the headline, which names the dialog unless a `label` is supplied.
+     *
+     * @returns headline identifier, or `undefined` without a headline or with a `label`
+     */
+    protected defaultLabelledBy(): string | undefined;
+    /**
+     * 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, close icon, and action label 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 and scroll listeners when the controller is disposed.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+}
+/**
+ * Material full-screen dialog.
+ *
+ * A full-screen dialog covers the viewport with a header, which holds a close icon button, the
+ * headline, and an optional confirming text button, above scrolling content. Material recommends
+ * full-screen dialogs for compact windows; {@link ./scaffold#createWindowSizeClass} tells them
+ * apart. The dialog is always modal; Escape and the close action request closure.
+ *
+ * # Motion
+ *
+ * Opening slides the dialog up from the bottom edge on the slow spatial spring, the full-screen
+ * speed; closing slides it down on the fast effects spring, which does not overshoot.
+ *
+ * # Design
+ *
+ * Full-screen dialog design is controlled through the `fullScreenDialog*` roles of the
+ * [`cw-Surface`](./surface.yaml) design attribute, after `md.comp.full-screen-dialog`: a surface
+ * container without corner rounding, a 56px header with a title-large headline, and a header which
+ * takes the scrolled color and elevation while the content is scrolled. The
+ * `cw-FullScreenDialog-scrolled` class is applied while the content is scrolled.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const FullScreenDialog: DomComponent<FullScreenDialogProps>;

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

@@ -0,0 +1,92 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps } from "..";
+import { DomController } from "../dom/client";
+import "./surface.css";
+/**
+ * Divider orientation.
+ */
+export type DividerOrientation = "horizontal" | "vertical";
+/**
+ * Properties accepted by {@link Divider}.
+ */
+export type DividerProps = DomProps<HTMLDivElement, Omit<JSX.HTMLAttributes<HTMLDivElement>, "role" | "aria-orientation">> & {
+    /**
+     * Divider orientation.
+     *
+     * @defaultValue `"horizontal"`
+     */
+    orientation?: DividerOrientation | undefined;
+    /**
+     * Alias for `orientation="vertical"`, which takes precedence when `true`.
+     *
+     * @defaultValue `false`
+     */
+    vertical?: boolean | undefined;
+    /**
+     * Logical edges the divider is inset from.
+     *
+     * Material's full-width divider is `"none"`, its inset divider is `"start"`, and its
+     * middle-inset divider is `"both"`. A horizontal divider is inset along the inline axis and a
+     * vertical divider along the block axis, each by the `dividerInset` role.
+     *
+     * @defaultValue `"none"`
+     */
+    inset?: "none" | "start" | "end" | "both" | undefined;
+    /**
+     * Divider separates content semantically.
+     *
+     * When `true`, the divider has the `separator` role, with `aria-orientation` when vertical;
+     * otherwise, it is decorative and hidden from assistive technology semantics.
+     *
+     * @defaultValue `true`
+     */
+    semantic?: boolean | undefined;
+    /**
+     * Divider thickness, in CSS pixels or as a CSS length.
+     *
+     * When omitted, the `dividerThickness` role applies.
+     */
+    thickness?: number | string | undefined;
+};
+/**
+ * Client controller of a {@link Divider}.
+ */
+export declare class DividerController extends DomController<DividerProps> {
+    #private;
+    /**
+     * Construct a new `DividerController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: DividerProps);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): 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 divider.
+ *
+ * A divider is a thin line which groups content in lists and containers. It draws a single
+ * logical border, so it remains visible in forced-colors mode, and it follows the writing
+ * direction for its inset edges.
+ *
+ * # Design
+ *
+ * Divider design is controlled through the `dividerColor`, `dividerThickness`, and `dividerInset`
+ * roles of the [`cw-Surface`](./surface.yaml) design attribute.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const Divider: DomComponent<DividerProps>;