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

package/target/tsc/navigation/scroll.d.ts

@@ -0,0 +1,218 @@
+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";
+/**
+ * {@link Scrollbar} component properties.
+ */
+export type ScrollbarProps = NavigationElementProps<HTMLDivElement> & {
+    /**
+     * Id of the scrollable element controlled by this scrollbar.
+     *
+     * The element is resolved in the scrollbar's document or shadow root, including when it is
+     * inserted after the scrollbar.
+     */
+    controls: string;
+    /**
+     * Accessible scrollbar label.
+     *
+     * @defaultValue `"Scroll position"`
+     */
+    label?: string | undefined;
+    /**
+     * Scrollbar orientation.
+     *
+     * @defaultValue `"vertical"`
+     */
+    orientation?: NavigationOrientation | undefined;
+    /**
+     * Controlled scroll position, within `min` and `max`.
+     */
+    value?: number | undefined;
+    /**
+     * Initial scroll position of an uncontrolled scrollbar.
+     *
+     * @defaultValue `0`
+     */
+    defaultValue?: number | undefined;
+    /**
+     * Value mapped to the start of the scrollable range.
+     *
+     * @defaultValue `0`
+     */
+    min?: number | undefined;
+    /**
+     * Value mapped to the end of the scrollable range.
+     *
+     * @defaultValue `100`
+     */
+    max?: number | undefined;
+    /**
+     * Arrow-key increment, in value units.
+     *
+     * @defaultValue `10`
+     */
+    step?: number | undefined;
+    /**
+     * Disable scrollbar interaction.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Handle a changed scroll value from interaction or from the associated scroll target.
+     *
+     * Runs before a distinct `onChange` callback; identical references run once. Uncontrolled
+     * state is updated first. A native scroll of the target is never reverted: with a controlled
+     * `value`, update the property to keep the thumb in step with the content. Cancelling this
+     * callback does not roll back uncontrolled state.
+     *
+     * @param value - requested value clamped to the scrollbar range
+     * @param event - originating keyboard, pointer, or native scroll event
+     */
+    onValueChange?: (value: number, event: Event) => void;
+    /**
+     * Alias for {@link ScrollbarProps.onValueChange}.
+     */
+    onChange?: (value: number, event: Event) => void;
+};
+/**
+ * {@link ScrollField} component properties.
+ */
+export type ScrollFieldProps = NavigationElementProps<HTMLDivElement> & {
+    /**
+     * Scroll axis of the field.
+     *
+     * @defaultValue `"vertical"`
+     */
+    orientation?: NavigationOrientation | undefined;
+};
+/**
+ * Client controller of a semantic scrollbar bound to a scrollable element.
+ *
+ * The controller follows the target's native scrolling, maps keyboard and pointer input onto the
+ * target, and positions the thumb without replacing the native scroll container. Horizontal
+ * scrollbars follow the target's text direction: in right-to-left content, the start of the
+ * range is at the right edge and the arrow keys move the thumb in their visual direction.
+ *
+ * # Elements
+ *
+ * | Element | Description |
+ * | ------- | ----------- |
+ * | `div.cw-Scrollbar[role=scrollbar]` | Focusable track; its `::after` element is the thumb. |
+ *
+ * The thumb is positioned with the `--cw-Scrollbar-thumb-size` and `--cw-Scrollbar-thumb-offset`
+ * inline properties, in CSS pixels from the track's left or top edge.
+ */
+export declare class ScrollbarController extends DomController<ScrollbarProps> {
+    #private;
+    /**
+     * Construct a new `ScrollbarController`.
+     *
+     * Range, step, orientation, and the initial value are read without tracking; later changes are
+     * applied by {@link ScrollbarController.applyComponentProps}.
+     *
+     * @param props - component properties
+     */
+    constructor(props: ScrollbarProps);
+    /**
+     * 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 scrollbar renders a static track, so this binds its listeners once. The target is
+     * resolved again in a microtask, after the track is inserted into its document.
+     *
+     * @param curr - new style element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onStyleElementChanged}
+     */
+    protected onStyleElementChanged(curr: StyleElement | null): void;
+    /**
+     * Release the target binding and root observation when the controller is disposed.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+    /**
+     * Render the static scrollbar track.
+     *
+     * @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;
+}
+/**
+ * Semantic scrollbar bound to a scrollable element.
+ *
+ * The scrollbar is a focusable `role="scrollbar"` track linked to its target through
+ * `aria-controls`. Arrow keys move by {@link ScrollbarProps.step | step}, Page Up and Page Down by
+ * one viewport, and Home and End to the range limits; pointer presses jump the thumb, and the thumb
+ * can be dragged. The target's own scrolling, by wheel, touch, or keyboard, moves the thumb.
+ *
+ * Material 3 does not define a scrollbar component; this is a web control styled with Material
+ * color and shape roles. Native scrollbars remain appropriate for most scroll containers.
+ *
+ * # Design
+ *
+ * Scrollbar design is controlled through the [`cw-Scrollbar`](./scroll.yaml) component design
+ * attribute. A disabled scrollbar has the `cw-Scrollbar-disabled` class.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const Scrollbar: DomComponent<ScrollbarProps>;
+/**
+ * Client controller of a scroll field.
+ */
+export declare class ScrollFieldController extends DomController<ScrollFieldProps> {
+    /**
+     * Construct a new `ScrollFieldController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: ScrollFieldProps);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Render the static scroll container.
+     *
+     * @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;
+}
+/**
+ * Scroll container which can be paired with a {@link Scrollbar}.
+ *
+ * The field scrolls along its {@link ScrollFieldProps.orientation | orientation} with native
+ * scrolling; give it an `attr:id` and pass that id to the scrollbar's `controls`.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const ScrollField: DomComponent<ScrollFieldProps>;
+/**
+ * Vertical {@link Scrollbar}, which is the scrollbar's default orientation.
+ */
+export declare const VerticalScrollbar: typeof Scrollbar;
+/**
+ * Horizontal {@link Scrollbar}.
+ *
+ * The orientation remains overridable for callers which use the alias as a convenience rather
+ * than as a strict horizontal variant.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const HorizontalScrollbar: typeof Scrollbar;

package/target/tsc/navigation/search.d.ts

@@ -0,0 +1,332 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, StyleElement } from "..";
+import type { NavigationElementProps, NavigationOpenChangeHandler } from "./base";
+import { DomController } from "../dom/client";
+import "../container/elevation-shadow.css";
+import "./navigation.css";
+/**
+ * Properties of search bars and search views.
+ */
+export type SearchBarProps = NavigationElementProps<HTMLElement> & {
+    /**
+     * Style of the expanded search view.
+     *
+     * | Design      | Docked view                          | Full-screen view                  |
+     * | ----------- | ------------------------------------ | --------------------------------- |
+     * | `contained` | Results in a container below the bar | The bar keeps its shape           |
+     * | `divided`   | Bar and results in one container     | A 72px header above a divider     |
+     *
+     * The contained style is the Material 3 Expressive one; the divided style is the baseline one.
+     *
+     * @defaultValue `"contained"`
+     */
+    design?: "contained" | "divided" | undefined;
+    /**
+     * Expanded presentation: results below the bar, or a full-screen search view.
+     *
+     * The full-screen view is a modal dialog in the browser top layer which retains the native
+     * input and result nodes; it expands from the bar with a container transform.
+     *
+     * @defaultValue `"docked"`; {@link SearchView} and {@link SearchAppBar} default to
+     * `"fullscreen"`.
+     */
+    expansion?: "docked" | "fullscreen" | undefined;
+    /**
+     * Accessible label of the full-screen view's back button.
+     *
+     * @defaultValue `"Close search"`
+     */
+    backLabel?: string | undefined;
+    /**
+     * Controlled query text.
+     */
+    query?: string | undefined;
+    /**
+     * Initial query text of an uncontrolled search bar.
+     */
+    defaultQuery?: string | undefined;
+    /**
+     * Controlled expanded state.
+     */
+    expanded?: boolean | undefined;
+    /**
+     * Initial expanded state of an uncontrolled search bar.
+     */
+    defaultExpanded?: boolean | undefined;
+    /**
+     * Supporting text shown while the query is empty.
+     */
+    placeholder?: string | undefined;
+    /**
+     * Center the placeholder and the query text of the collapsed bar.
+     *
+     * This is the `app:textCentered` search bar attribute of Material Components for Android, one
+     * of its Material 3 Expressive updates, added in version 1.13.0 (first released in
+     * 1.13.0-alpha12). The text is centered between the leading and trailing content of the bar.
+     * An expanded bar edits start-aligned text, as the Material Components search view does.
+     *
+     * @defaultValue `false`
+     */
+    textCentered?: boolean | undefined;
+    /**
+     * Accessible name of the search combobox and of the full-screen view.
+     *
+     * @defaultValue `"Search"`
+     */
+    inputLabel?: string | undefined;
+    /**
+     * Form field name of the search input.
+     */
+    inputName?: string | undefined;
+    /**
+     * Id of an external form the search input belongs to.
+     */
+    inputForm?: string | undefined;
+    /**
+     * Autocomplete hint of the search input.
+     */
+    inputAutoComplete?: string | undefined;
+    /**
+     * Require a query for form submission.
+     */
+    inputRequired?: boolean | undefined;
+    /**
+     * Accessible label of the results listbox.
+     *
+     * @defaultValue `"Search results"`
+     */
+    resultsLabel?: string | undefined;
+    /**
+     * Disable the input and expansion.
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Prevent query changes while keeping the input focusable.
+     */
+    readOnly?: boolean | undefined;
+    /**
+     * Expand when the input receives focus by any means.
+     *
+     * Otherwise, the bar expands when it is clicked or tapped, when text is entered, or when the
+     * arrow keys request results; keyboard focus alone does not open a view.
+     *
+     * @defaultValue `false`
+     */
+    openOnFocus?: boolean | undefined;
+    /**
+     * Stable id of the search input.
+     */
+    inputId?: string | undefined;
+    /**
+     * Stable id of the results listbox.
+     */
+    resultsId?: string | undefined;
+    /**
+     * Leading icon or icon button.
+     */
+    leadingIcon?: JSX.Element;
+    /**
+     * Trailing icon or icon button.
+     */
+    trailingIcon?: JSX.Element;
+    /**
+     * Trailing avatar image or element, sized to the avatar role in a 48px target.
+     */
+    avatar?: JSX.Element;
+    /**
+     * Results, made of `role="option"` elements; children are used when omitted.
+     *
+     * An option's `data-value`, or else its text, is the query selected with it.
+     */
+    results?: JSX.Element;
+    /**
+     * Handle a native query edit or an option selection.
+     *
+     * Runs before a distinct `onChange` callback; identical references run once. A controlled
+     * query is then restored from `query` unless the parent accepts the edit. Cancelling this
+     * callback does not restore an uncontrolled query.
+     *
+     * @param query - edited query or selected option value
+     * @param event - native input event or option activation event
+     */
+    onQueryChange?: ((query: string, event: Event) => void) | undefined;
+    /**
+     * Alias for {@link SearchBarProps.onQueryChange}.
+     */
+    onChange?: ((query: string, event: Event) => void) | undefined;
+    /**
+     * Handle a requested expanded state.
+     *
+     * With controlled `expanded`, the parent must update the property to accept the request.
+     */
+    onExpandedChange?: NavigationOpenChangeHandler | undefined;
+    /**
+     * Handle Enter submission or option selection.
+     *
+     * An option selection first invokes the query callbacks and requests collapse. Cancelling
+     * this callback does not undo that selection.
+     *
+     * @param query - submitted input text or selected option value
+     * @param event - submitting key event or option activation event
+     */
+    onSearch?: ((query: string, event: Event) => void) | undefined;
+};
+/**
+ * Properties of a {@link SearchAppBar}.
+ */
+export type SearchAppBarProps = SearchBarProps & {
+    /**
+     * Leading navigation icon button, outside the search bar.
+     */
+    navigationIcon?: JSX.Element;
+    /**
+     * Action icon buttons, inside or outside the search bar.
+     */
+    actions?: JSX.Element;
+    /**
+     * Placement of {@link SearchAppBarProps.actions | actions}: in the bar's trailing slot, or
+     * after the bar.
+     *
+     * @defaultValue `"outside"`
+     */
+    actionsPlacement?: "inside" | "outside" | undefined;
+    /**
+     * Apply the on-scroll container colors.
+     *
+     * When omitted, an app bar with a {@link SearchAppBarProps.scrollBehavior} applies them while
+     * its content is scrolled.
+     */
+    scrolled?: boolean | undefined;
+    /**
+     * Scroll behavior following the scroll container identified by
+     * {@link SearchAppBarProps.scrollTarget}, as Compose's `AppBarWithSearch`: `pinned` keeps the
+     * bar in place, and `enterAlways` moves it off the top while content scrolls forward and back
+     * as soon as content scrolls back.
+     */
+    scrollBehavior?: "pinned" | "enterAlways" | undefined;
+    /**
+     * Id of the scroll container followed by {@link SearchAppBarProps.scrollBehavior}.
+     *
+     * @defaultValue The document scrolling element
+     */
+    scrollTarget?: string | undefined;
+};
+/**
+ * Root class selecting a search presentation.
+ */
+type SearchBarClass = "cw-SearchBar" | "cw-DockedSearchBar" | "cw-SearchAppBar";
+/**
+ * Client controller of search bars, search views, and search app bars.
+ *
+ * The input is a native `type="search"` combobox controlling a results listbox: arrow keys move
+ * an active descendant through visible, enabled options, Enter selects the active option or
+ * submits the query, and Escape collapses the results. Input-method composition keeps its keys.
+ * Docked results collapse when focus or a pointer press leaves the search bar. The full-screen
+ * view is a labelled modal dialog in the browser top layer which traps focus, returns focus when
+ * closed, and expands from and collapses into the bar with a container transform.
+ */
+export declare class SearchBarController extends DomController<SearchAppBarProps> {
+    #private;
+    /**
+     * Construct a new `SearchBarController`.
+     *
+     * @param props - component properties
+     * @param baseClass - root class selecting the presentation
+     * @param defaultExpansion - expansion used when {@link SearchBarProps.expansion} is omitted
+     */
+    constructor(props: SearchAppBarProps, baseClass: SearchBarClass, defaultExpansion: "docked" | "fullscreen");
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Bind listeners and observers to the rendered elements.
+     *
+     * Search 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;
+    /**
+     * Close the view and release listeners and observers when the controller is disposed.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+    /**
+     * Render the static search 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 search bar.
+ *
+ * The search bar is a `search` landmark holding a native search input with combobox semantics and
+ * a results listbox of `role="option"` elements; see {@link SearchBarController} for keyboard
+ * behavior. It expands to docked results below the bar, or, with
+ * {@link SearchBarProps.expansion | `expansion="fullscreen"`}, to a full-screen search view. Label
+ * the landmark with `attr:aria-label` and the input with {@link SearchBarProps.inputLabel}.
+ *
+ * # States
+ *
+ * The bar expands when clicked or tapped, when a query is typed, or when an arrow key requests
+ * results. Expanded bars have the `cw-SearchBar-expanded` class and
+ * `data-cw-search-expanded="true"`; the full-screen view is open while `data-cw-search-view` is
+ * set. Docked results are revealed with spatial and effects springs; the full-screen view expands
+ * from the bar with a container transform.
+ *
+ * # Design
+ *
+ * Search design is controlled through the [`cw-SearchBar`](./search.yaml) component design
+ * attribute. The {@link SearchBarProps.design | design} selects the contained or divided view.
+ *
+ * # Elements
+ *
+ * | Element | Description |
+ * | ------- | ----------- |
+ * | `.cw-SearchBar-container` | Bar and results; the full-screen view while it is open. |
+ * | `.cw-SearchBar-header` | Bar row: back button, leading icon, input, trailing icon, avatar. |
+ * | `.cw-SearchBar-results` | Results listbox. |
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const SearchBar: DomComponent<SearchBarProps>;
+/**
+ * {@link SearchBar} expanding to docked results, with the additional `cw-DockedSearchBar` class.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const DockedSearchBar: DomComponent<SearchBarProps>;
+/**
+ * {@link SearchBar} expanding to a full-screen search view.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const SearchView: DomComponent<SearchBarProps>;
+/**
+ * Material 3 Expressive app bar with search.
+ *
+ * The app bar is a `search` landmark: an optional navigation icon, a search bar expanding to a
+ * full-screen search view by default, and actions inside or after the bar. Its container and the
+ * search field take their on-scroll colors while {@link SearchAppBarProps.scrolled} is set, or
+ * while content scrolls under a bar with a {@link SearchAppBarProps.scrollBehavior}; the colors
+ * change with the default effects spring (Compose `AppBarWithSearch`).
+ *
+ * The app bar has the `cw-SearchBar` and `cw-SearchAppBar` classes; the enter-always offset is the
+ * unitless `--cw-SearchAppBar-scroll-progress` property.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const SearchAppBar: DomComponent<SearchAppBarProps>;
+export {};