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

package/target/tsc/navigation/app-bar.d.ts

@@ -0,0 +1,473 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, StyleElement } from "..";
+import type { NavigationElementProps, NavigationOrientation } from "./base";
+import { DomController } from "../dom/client";
+import "./navigation.css";
+/**
+ * Layout variant of a top app bar.
+ *
+ * Two-row variants show the navigation icon, a compact title, and the actions in a top row of the
+ * small bar's height, and an expanded title below it. Collapsing a two-row bar, by scrolling or
+ * through {@link TopAppBarProps.collapsed}, slides the expanded row under the top row while the
+ * compact title fades in, as Compose's `TwoRowsTopAppBar`.
+ *
+ * | Variant           | Rows | Expanded height        | Expanded title (subtitle)        |
+ * | ----------------- | ---- | ---------------------- | -------------------------------- |
+ * | `small`           | one  | 64px                   | title large (label medium)       |
+ * | `center`          | one  | 64px                   | title large, centered            |
+ * | `medium`          | two  | 112px                  | headline small (label large)     |
+ * | `large`           | two  | 152px                  | headline medium (title medium)   |
+ * | `medium-flexible` | two  | 112px, 136px subtitled | headline medium (label large)    |
+ * | `large-flexible`  | two  | 120px, 152px subtitled | display small (title medium)     |
+ */
+export type TopAppBarVariant = "small" | "center" | "medium" | "large" | "medium-flexible" | "large-flexible";
+/**
+ * Scroll behavior of a top app bar, as Compose's `TopAppBarDefaults` scroll behaviors.
+ *
+ * | Behavior             | Description                                                    |
+ * | -------------------- | -------------------------------------------------------------- |
+ * | `pinned`             | Keeps its size; scrolled content changes its container color.  |
+ * | `enterAlways`        | Collapses as content scrolls forward; expands as it scrolls back. |
+ * | `exitUntilCollapsed` | Collapses as content scrolls forward; expands near its start.  |
+ *
+ * Single-row bars collapse to zero height; two-row bars collapse to their top row.
+ */
+export type TopAppBarScrollBehavior = "pinned" | "enterAlways" | "exitUntilCollapsed";
+/**
+ * Properties of top app bars.
+ */
+export type TopAppBarProps = NavigationElementProps<HTMLDivElement> & {
+    /**
+     * Layout variant.
+     *
+     * @defaultValue The variant of the component, `"small"` for {@link TopAppBar}.
+     */
+    variant?: TopAppBarVariant | undefined;
+    /**
+     * Title; children are used when omitted.
+     *
+     * Two-row variants render the title, and the subtitle, twice: compact in the top row and
+     * expanded below it, exactly as Compose renders its `smallTitle`. Pass content which can be
+     * rendered twice, such as text or a JSX expression, rather than an existing DOM node. Heading
+     * elements in the title inherit the title typography.
+     */
+    title?: JSX.Element;
+    /**
+     * Subtitle shown below the title.
+     */
+    subtitle?: JSX.Element;
+    /**
+     * Horizontal alignment of the title and subtitle.
+     *
+     * A centered title is centered on the bar and moves aside only as far as needed to clear the
+     * navigation icon and actions.
+     *
+     * @defaultValue `"center"` for the `center` variant; otherwise `"start"`
+     */
+    titleAlignment?: "start" | "center" | undefined;
+    /**
+     * Leading navigation icon button.
+     */
+    navigationIcon?: JSX.Element;
+    /**
+     * Trailing action icon buttons, or an {@link AppBarRow} with an overflow menu.
+     */
+    actions?: JSX.Element;
+    /**
+     * Trailing avatar image or element, sized to the avatar role in a 48px target.
+     */
+    avatar?: JSX.Element;
+    /**
+     * Height of the expanded bar, as a CSS length or a number of pixels.
+     *
+     * For single-row bars this is the bar height; for two-row bars it is the height of both rows.
+     *
+     * @defaultValue The variant's container height
+     */
+    expandedHeight?: string | number | undefined;
+    /**
+     * Scroll behavior following the scroll container identified by
+     * {@link TopAppBarProps.scrollTarget}.
+     *
+     * The bar changes height as content scrolls, so lay it out over the scroll container, for
+     * example with fixed or sticky positioning and content padding, rather than above it.
+     * {@link TopAppBarProps.collapsed} and {@link TopAppBarProps.scrollProgress} take precedence.
+     */
+    scrollBehavior?: TopAppBarScrollBehavior | undefined;
+    /**
+     * Id of the scroll container followed by {@link TopAppBarProps.scrollBehavior}, resolved in the
+     * bar's document or shadow root.
+     *
+     * @defaultValue The document scrolling element
+     */
+    scrollTarget?: string | undefined;
+    /**
+     * Apply the on-scroll container color.
+     *
+     * When omitted, single-row bars with a {@link TopAppBarProps.scrollBehavior} apply it while
+     * their content is scrolled; two-row bars blend toward it as they collapse.
+     */
+    scrolled?: boolean | undefined;
+    /**
+     * Collapse the bar.
+     *
+     * A collapsed bar ignores {@link TopAppBarProps.scrollProgress}; an expanded one follows it, if
+     * given. Changes are animated with the snap spring of Compose's `TopAppBarDefaults`, after the
+     * initial render. Single-row bars collapse to zero height.
+     */
+    collapsed?: boolean | undefined;
+    /**
+     * Collapsed fraction, from expanded (`0`) to collapsed (`1`), applied without animation.
+     *
+     * Use this to drive the bar from an application-defined scroll model. It takes precedence over
+     * {@link TopAppBarProps.scrollBehavior}, and yields to a `true`
+     * {@link TopAppBarProps.collapsed}.
+     */
+    scrollProgress?: number | undefined;
+};
+/**
+ * Properties of a {@link BottomAppBar}.
+ */
+export type BottomAppBarProps = NavigationElementProps<HTMLDivElement> & {
+    /**
+     * Start-aligned action icon buttons; children are used when omitted.
+     */
+    actions?: JSX.Element;
+    /**
+     * Floating action button at the end of the bar.
+     */
+    floatingActionButton?: JSX.Element;
+    /**
+     * Hide the bar while content scrolls forward and show it as soon as content scrolls back, as
+     * Compose's `BottomAppBarDefaults.exitAlwaysScrollBehavior`.
+     */
+    scrollBehavior?: "exitAlways" | undefined;
+    /**
+     * Id of the scroll container followed by {@link BottomAppBarProps.scrollBehavior}.
+     *
+     * @defaultValue The document scrolling element
+     */
+    scrollTarget?: string | undefined;
+};
+/**
+ * Properties of {@link AppBarRow} and {@link AppBarColumn}.
+ */
+export type AppBarLayoutProps = NavigationElementProps<HTMLDivElement> & {
+    /**
+     * Accessible label of the overflow menu button.
+     *
+     * @defaultValue `"More options"`
+     */
+    overflowLabel?: string | undefined;
+    /**
+     * Maximum number of slots, including the overflow menu button when it is shown.
+     *
+     * @defaultValue Unlimited; items move into the overflow menu only when they do not fit.
+     */
+    maxItemCount?: number | undefined;
+};
+/**
+ * Properties of an {@link AppBarItem}.
+ */
+export type AppBarItemProps = {
+    /**
+     * Icon shown on the item's icon button and in the overflow menu.
+     *
+     * The icon is rendered again for the overflow menu; pass content which can be rendered twice.
+     */
+    icon: JSX.Element;
+    /**
+     * Accessible name of the icon button and label of the overflow menu item.
+     */
+    label: string;
+    /**
+     * Disable the item.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Handle activation of the item, from its icon button or from the overflow menu.
+     *
+     * @param event - activating click or keyboard event
+     */
+    onActivate?: ((event: Event) => void) | undefined;
+};
+/**
+ * Client controller of top app bars.
+ *
+ * The controller applies the variant, alignment, and on-scroll color, drives the collapsed
+ * fraction from {@link TopAppBarProps.scrollProgress}, {@link TopAppBarProps.collapsed}, or a
+ * {@link TopAppBarProps.scrollBehavior}, and exposes only the visible title of a two-row bar to
+ * assistive technology. The collapsible distance is measured with a `ResizeObserver`; scrolling
+ * itself causes no layout reads.
+ */
+export declare class TopAppBarController extends DomController<TopAppBarProps> {
+    #private;
+    /**
+     * Construct a new `TopAppBarController`.
+     *
+     * @param props - component properties
+     * @param defaultVariant - variant used when {@link TopAppBarProps.variant} is omitted
+     */
+    constructor(props: TopAppBarProps, defaultVariant?: TopAppBarVariant);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Create the collapsed fraction state for the bar element.
+     *
+     * Top app bars render a static element, so this runs once, when the bar is rendered.
+     *
+     * @param curr - new style element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onStyleElementChanged}
+     */
+    protected onStyleElementChanged(curr: StyleElement | null): void;
+    /**
+     * Stop following scrolling and observing sizes when the controller is disposed.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+    /**
+     * Render the static bar structure and insert its slots.
+     *
+     * The expanded row receives the second title rendering only while the variant has two rows.
+     *
+     * @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 top app bar.
+ *
+ * Top app bars display a title, a navigation icon, actions, and an avatar at the top of a
+ * screen. The {@link TopAppBarProps.variant | variant} selects the single-row small and
+ * center-aligned bars, or the two-row medium, large, and flexible bars; see
+ * {@link TopAppBarVariant}. Bars are neutral containers; add `attr:role="banner"` for a landmark.
+ *
+ * # States
+ *
+ * A {@link TopAppBarProps.scrollBehavior | scroll behavior}, {@link TopAppBarProps.collapsed}, or
+ * {@link TopAppBarProps.scrollProgress} collapses the bar. Two-row bars blend their container
+ * toward the on-scroll color as they collapse, and single-row bars apply it while content is
+ * scrolled under them; color changes use the default effects spring. Only the visible title of a
+ * two-row bar is exposed to assistive technology.
+ *
+ * # Design
+ *
+ * App-bar design is controlled through the [`cw-AppBar`](./app-bar.yaml) component design
+ * attribute. The bar has the `cw-TopAppBar` class and its variant in the
+ * `data-cw-top-app-bar-variant` attribute; the collapsed fraction is the unitless
+ * `--cw-TopAppBar-scroll-progress` property, and the on-scroll color applies while
+ * `data-cw-app-bar-scrolled="true"` is set.
+ *
+ * # Elements
+ *
+ * | Element | Description |
+ * | ------- | ----------- |
+ * | `.cw-TopAppBar-row` | Top row: navigation icon, compact title, actions, and avatar. |
+ * | `.cw-TopAppBar-expandedRow` | Expanded title row of two-row variants. |
+ * | `.cw-TopAppBar-title`, `.cw-TopAppBar-subtitle` | Title and subtitle of each row. |
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const TopAppBar: DomComponent<TopAppBarProps>;
+/**
+ * Small {@link TopAppBar}.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const SmallTopAppBar: DomComponent<TopAppBarProps>;
+/**
+ * Center-aligned {@link TopAppBar}: a small bar whose title is centered on the bar.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const CenterAlignedTopAppBar: DomComponent<TopAppBarProps>;
+/**
+ * Medium {@link TopAppBar} with a headline-small expanded title.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const MediumTopAppBar: DomComponent<TopAppBarProps>;
+/**
+ * Large {@link TopAppBar} with a headline-medium expanded title.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const LargeTopAppBar: DomComponent<TopAppBarProps>;
+/**
+ * Medium flexible {@link TopAppBar} with a headline-medium title and label-large subtitle.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const MediumFlexibleTopAppBar: DomComponent<TopAppBarProps>;
+/**
+ * Large flexible {@link TopAppBar} with a display-small title and title-medium subtitle.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const LargeFlexibleTopAppBar: DomComponent<TopAppBarProps>;
+/**
+ * Two-row {@link TopAppBar}, an alias of {@link LargeTopAppBar}.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const TwoRowsTopAppBar: DomComponent<TopAppBarProps>;
+/**
+ * Client controller of bottom app bars.
+ *
+ * The controller follows an exit-always {@link BottomAppBarProps.scrollBehavior | scroll behavior}
+ * and measures the bar height with a `ResizeObserver`. While the bar is moved, even partially, it
+ * is inert, so that keyboard focus cannot reach it off screen.
+ */
+export declare class BottomAppBarController extends DomController<BottomAppBarProps> {
+    #private;
+    /**
+     * Construct a new `BottomAppBarController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: BottomAppBarProps);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Create the hidden fraction state and observe the bar height.
+     *
+     * Bottom app bars render a static element, so this runs once, when the bar is rendered.
+     *
+     * @param curr - new style element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onStyleElementChanged}
+     */
+    protected onStyleElementChanged(curr: StyleElement | null): void;
+    /**
+     * Stop following scrolling and observing sizes when the controller is disposed.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+    /**
+     * Render the static bar structure and insert its 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;
+}
+/**
+ * Material bottom app bar.
+ *
+ * Bottom app bars place up to four start-aligned action icon buttons and an optional floating
+ * action button at the bottom of a screen. Material 3 Expressive replaces the bottom app bar with
+ * the {@link ./toolbar#DockedToolbar | docked toolbar}, which should be preferred in new designs;
+ * the bottom app bar remains part of the Material 3 baseline.
+ *
+ * # States
+ *
+ * With the `exitAlways` {@link BottomAppBarProps.scrollBehavior | scroll behavior}, the bar hides
+ * while content scrolls forward and returns as soon as it scrolls back; when scrolling stops
+ * between the two, the bar snaps with the fast spatial spring of Compose's `BottomAppBarDefaults`.
+ * The hidden fraction is the unitless `--cw-BottomAppBar-scroll-progress` property. Anchor the bar
+ * to the bottom edge, for example with fixed positioning.
+ *
+ * # Design
+ *
+ * Bottom app-bar design is controlled through the `bottom` roles of the
+ * [`cw-AppBar`](./app-bar.yaml) component design attribute. The bar has the `cw-BottomAppBar`
+ * class and is a neutral container; add `attr:role="contentinfo"` for a landmark.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const BottomAppBar: DomComponent<BottomAppBarProps>;
+/**
+ * Client controller of app-bar rows and columns.
+ *
+ * The controller measures the layout and its items along the layout axis, hides the items which
+ * do not fit, or exceed {@link AppBarLayoutProps.maxItemCount}, and lists them in the overflow
+ * menu, as Compose's `AppBarRow` and `AppBarColumn`. Only {@link AppBarItem}s overflow; other
+ * children always stay in the layout, and the items share the space they leave.
+ */
+export declare class AppBarLayoutController extends DomController<AppBarLayoutProps> {
+    #private;
+    /**
+     * Construct a new `AppBarLayoutController`.
+     *
+     * @param props - component properties
+     * @param orientation - layout axis selecting a row or a column
+     */
+    constructor(props: AppBarLayoutProps, orientation: NavigationOrientation);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Stop observing sizes and children when the controller is disposed.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+    /**
+     * Render the static layout, observe its children, and insert its items and overflow menu.
+     *
+     * @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;
+}
+/**
+ * Horizontal app-bar layout which moves items that do not fit into an overflow menu.
+ *
+ * Use it in the `actions` slot of a {@link TopAppBar}, or in a {@link BottomAppBar} or toolbar,
+ * with {@link AppBarItem} children. The row fills its container; {@link AppBarItem}s which do not
+ * fit, or exceed {@link AppBarLayoutProps.maxItemCount}, are hidden and listed, in order, in a
+ * menu opened by an overflow icon button at the end of the row. Other children, such as a button
+ * which must stay visible, never overflow, and the items fit in the space they leave.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const AppBarRow: DomComponent<AppBarLayoutProps>;
+/**
+ * Vertical app-bar layout which moves items that do not fit into an overflow menu.
+ *
+ * The column behaves as {@link AppBarRow} along the block axis, for vertical toolbars.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const AppBarColumn: DomComponent<AppBarLayoutProps>;
+/**
+ * Item of an {@link AppBarRow} or {@link AppBarColumn}.
+ *
+ * The item is a standard icon button labelled by {@link AppBarItemProps.label}. When its layout
+ * runs out of space, the item is hidden and listed in the overflow menu with the same icon and
+ * label; activating either calls {@link AppBarItemProps.onActivate}. Outside a row or column, the
+ * item never overflows.
+ *
+ * @param props - component properties
+ * @returns rendered item
+ */
+export declare function AppBarItem(props: AppBarItemProps): JSX.Element;