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

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

@@ -0,0 +1,337 @@
+import type { Accessor, JSX } from "solid-js";
+import type { DomComponent, DomProps, StyleElement } from "..";
+import { DomController } from "../dom/client";
+import "./surface.css";
+/**
+ * Position of a scaffold's floating action button.
+ *
+ * | Position       | Placement                                                         |
+ * | -------------- | ----------------------------------------------------------------- |
+ * | `"start"`      | at the start edge, above the bottom bar                           |
+ * | `"center"`     | centered, above the bottom bar                                    |
+ * | `"end"`        | at the end edge, above the bottom bar                             |
+ * | `"endOverlay"` | at the end edge, overlaying the bottom bar                        |
+ *
+ * @see Compose `FabPosition`
+ */
+export type FabPosition = "start" | "center" | "end" | "endOverlay";
+/**
+ * Material window size class of a window width.
+ *
+ * | Class          | Window width          |
+ * | -------------- | --------------------- |
+ * | `"compact"`    | below 600px           |
+ * | `"medium"`     | 600px to below 840px  |
+ * | `"expanded"`   | 840px to below 1200px |
+ * | `"large"`      | 1200px to below 1600px |
+ * | `"extraLarge"` | 1600px and wider      |
+ *
+ * @see androidx.window `WindowSizeClass` width breakpoints (`BREAKPOINTS_V2`)
+ */
+export type WindowSizeClass = "compact" | "medium" | "expanded" | "large" | "extraLarge";
+/**
+ * Properties accepted by {@link Scaffold}.
+ */
+export type ScaffoldProps = DomProps<HTMLDivElement, Omit<JSX.HTMLAttributes<HTMLDivElement>, "role">> & {
+    /**
+     * Top app bar.
+     */
+    topBar?: JSX.Element;
+    /**
+     * Main content, which scrolls between the bars. Children are used when omitted.
+     */
+    content?: JSX.Element;
+    /**
+     * Landmark role of the content; omit it when the scaffold is inside another landmark.
+     */
+    contentRole?: "main" | "region" | undefined;
+    /**
+     * Accessible name of a `region` content landmark.
+     */
+    contentLabel?: string | undefined;
+    /**
+     * Bottom app bar or navigation bar.
+     */
+    bottomBar?: JSX.Element;
+    /**
+     * Floating action button.
+     */
+    floatingActionButton?: JSX.Element;
+    /**
+     * Position of the floating action button.
+     *
+     * @defaultValue `"end"`
+     */
+    floatingActionButtonPosition?: FabPosition | undefined;
+    /**
+     * Snackbar host, placed above the floating action button, or above the bottom bar without one.
+     */
+    snackbarHost?: JSX.Element;
+    /**
+     * Standard {@link ./sheet#BottomSheet | bottom sheet}, which peeks above the bottom bar.
+     *
+     * The content and the floating elements end above the sheet's peek, whichever height sets it.
+     */
+    bottomSheet?: JSX.Element;
+    /**
+     * Pad the scaffold by the safe-area insets of the viewport.
+     *
+     * The bars take the top and bottom insets; without a bar, the content and the floating
+     * elements take them instead. The scaffold takes the left and right insets.
+     *
+     * @defaultValue `false`
+     */
+    safeArea?: boolean | undefined;
+};
+/**
+ * Properties accepted by {@link BottomSheetScaffold}.
+ */
+export type BottomSheetScaffoldProps = ScaffoldProps & {
+    /**
+     * Peek height of the {@link ScaffoldProps.bottomSheet | bottom sheet}, in CSS pixels or as a
+     * CSS length.
+     *
+     * A sheet's own `peekHeight` takes precedence. When omitted, the `sheetPeekHeight` role
+     * applies.
+     */
+    sheetPeekHeight?: number | string | undefined;
+};
+/**
+ * Properties accepted by {@link ListDetailPaneScaffold}.
+ */
+export type ListDetailPaneScaffoldProps = DomProps<HTMLDivElement, JSX.HTMLAttributes<HTMLDivElement>> & {
+    /**
+     * List pane, the secondary pane, shown first.
+     */
+    list?: JSX.Element;
+    /**
+     * Detail pane, the primary pane. Children are used when omitted.
+     */
+    detail?: JSX.Element;
+    /**
+     * Extra pane, the tertiary pane, shown last.
+     */
+    extra?: JSX.Element;
+    /**
+     * Pane the user navigated to, which remains visible when fewer panes fit.
+     *
+     * @defaultValue `"list"`
+     */
+    activePane?: "list" | "detail" | "extra" | undefined;
+};
+/**
+ * Properties accepted by {@link SupportingPaneScaffold}.
+ */
+export type SupportingPaneScaffoldProps = DomProps<HTMLDivElement, JSX.HTMLAttributes<HTMLDivElement>> & {
+    /**
+     * Main pane, the primary pane, shown first. Children are used when omitted.
+     */
+    main?: JSX.Element;
+    /**
+     * Supporting pane, the secondary pane.
+     */
+    supporting?: JSX.Element;
+    /**
+     * Extra pane, the tertiary pane, shown last.
+     */
+    extra?: JSX.Element;
+    /**
+     * Pane the user navigated to, which remains visible when fewer panes fit.
+     *
+     * @defaultValue `"main"`
+     */
+    activePane?: "main" | "supporting" | "extra" | undefined;
+};
+/**
+ * Determine the window size class of a window width.
+ *
+ * @param width - window width in CSS pixels
+ * @returns window size class
+ */
+export declare function windowSizeClassOf(width: number): WindowSizeClass;
+/**
+ * Create a signal tracking the window size class of a window.
+ *
+ * The class follows the same width breakpoints as the CSS of the pane scaffolds, through media
+ * queries, so it changes only when the window crosses a breakpoint. During server rendering, or
+ * without a window, the class is `"compact"`, the class to design for first.
+ *
+ * Within a Solid owner, the media query listeners are removed when the owner is disposed.
+ *
+ * @param view - window to track
+ * @returns accessor of the current window size class
+ */
+export declare function createWindowSizeClass(view?: Window | undefined): Accessor<WindowSizeClass>;
+/**
+ * Client controller of a {@link Scaffold} or {@link BottomSheetScaffold}.
+ *
+ * The client renders the server's element tree; slots without content are hidden by CSS, so the
+ * tree is static and hydrates node for node.
+ */
+export declare class ScaffoldController extends DomController<BottomSheetScaffoldProps> {
+    #private;
+    /**
+     * Construct a new `ScaffoldController`.
+     *
+     * @param props - component properties
+     * @param cssClassName - public CSS class name of the scaffold
+     */
+    constructor(props: BottomSheetScaffoldProps, cssClassName?: string);
+    /**
+     * 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.
+     *
+     * Every slot 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;
+}
+/**
+ * Material scaffold.
+ *
+ * A scaffold lays out a screen as Compose `Scaffold` does: the top bar, the content, which scrolls
+ * between the bars, and the bottom bar. The floating action button sits 16 pixels (`FabSpacing`)
+ * above the bottom bar, at its {@link ScaffoldProps.floatingActionButtonPosition | position}, and
+ * the snackbar host, a `SnackbarHost` included, sits above the floating action button, or above
+ * the bottom bar without one. A standard bottom sheet peeks above the bottom bar, and the content
+ * and the floating elements end above its peek, whichever height sets it; an `endOverlay`
+ * floating action button overlays the bottom bar only while no sheet peeks above it.
+ *
+ * The scaffold fills its container; give it a height, such as `100dvh`, for the bars to stay in
+ * view. It has no content padding: content uses the pane margins of its layout.
+ *
+ * # Design
+ *
+ * The scaffold uses the background color role. The floating action button spacing is controlled
+ * through the `scaffoldFabSpacing` role of the [`cw-Surface`](./surface.yaml) design attribute.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const Scaffold: DomComponent<ScaffoldProps>;
+/**
+ * Material scaffold for a standard bottom sheet.
+ *
+ * A bottom sheet scaffold is a {@link Scaffold} whose {@link
+ * BottomSheetScaffoldProps.sheetPeekHeight | sheet peek height} is set on the scaffold, as Compose
+ * `BottomSheetScaffold`: the sheet peeks by that height, and the content ends above it, so that
+ * the content can scroll clear of the collapsed sheet.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const BottomSheetScaffold: DomComponent<BottomSheetScaffoldProps>;
+/**
+ * Client controller of a {@link ListDetailPaneScaffold}.
+ */
+export declare class ListDetailPaneScaffoldController extends DomController<ListDetailPaneScaffoldProps> {
+    /**
+     * Construct a new `ListDetailPaneScaffoldController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: ListDetailPaneScaffoldProps);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Render the component's element tree.
+     *
+     * Every pane 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;
+}
+/**
+ * Material list-detail canonical layout.
+ *
+ * The scaffold places the list, detail and extra panes side by side, in that order, as many as
+ * the window size class fits, as Compose `ListDetailPaneScaffold` with its default directive: one
+ * pane in compact and medium windows, two in expanded windows, and three in large and wider
+ * windows. The {@link ListDetailPaneScaffoldProps.activePane | active pane} stays visible; with two
+ * panes, the detail pane, which has the highest priority, joins it, and with one, only the active
+ * pane is shown. Panes without content take no space.
+ *
+ * # Design
+ *
+ * Panes are separated by the `paneSpacing` role, and the list and extra panes take the
+ * `panePreferredWidth` role (`panePreferredWidthExtraLarge` in large and wider windows) while the
+ * detail pane fills the rest. The scaffold is inset by the `paneMarginCompact` role in compact
+ * windows and by `paneMargin` otherwise. These are roles of the [`cw-Surface`](./surface.yaml)
+ * design attribute.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ * @see Compose `calculatePaneScaffoldDirective` and `ListDetailPaneScaffoldDefaults.PaneOrder`
+ */
+export declare const ListDetailPaneScaffold: DomComponent<ListDetailPaneScaffoldProps>;
+/**
+ * Client controller of a {@link SupportingPaneScaffold}.
+ */
+export declare class SupportingPaneScaffoldController extends DomController<SupportingPaneScaffoldProps> {
+    /**
+     * Construct a new `SupportingPaneScaffoldController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: SupportingPaneScaffoldProps);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Render the component's element tree.
+     *
+     * Every pane 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;
+}
+/**
+ * Material supporting pane canonical layout.
+ *
+ * The scaffold places the main, supporting and extra panes side by side, in that order, as many
+ * as the window size class fits, as Compose `SupportingPaneScaffold` with its default directive:
+ * one pane in compact and medium windows, two in expanded windows, and three in large and wider
+ * windows. The {@link SupportingPaneScaffoldProps.activePane | active pane} stays visible; with two
+ * panes, the main pane, which has the highest priority, joins it, and with one, only the active
+ * pane is shown. Panes without content take no space. A standard side sheet placed in a pane fills
+ * it, docked beside the main pane.
+ *
+ * # Design
+ *
+ * Pane spacing, widths and margins follow the roles described for {@link ListDetailPaneScaffold}.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ * @see Compose `calculatePaneScaffoldDirective` and `SupportingPaneScaffoldDefaults.PaneOrder`
+ */
+export declare const SupportingPaneScaffold: DomComponent<SupportingPaneScaffoldProps>;