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

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

@@ -0,0 +1,340 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps, StyleElement } from "..";
+import type { InteractableComponent, InteractableProps } from "../state";
+import { DomController } from "../dom/client";
+import { InteractableController } from "../state/controller";
+import "./surface.css";
+import "./list.css";
+/**
+ * List selection behavior.
+ *
+ * | Mode       | Semantics                                              |
+ * | ---------- | ------------------------------------------------------ |
+ * | `none`     | Ordinary list of list items.                           |
+ * | `single`   | Listbox of options, at most one of which is selected.  |
+ * | `multiple` | Multi-selectable listbox of options.                   |
+ */
+export type ListSelectionMode = "none" | "single" | "multiple";
+/**
+ * Preset of the leading content of a list item.
+ *
+ * | Type     | Leading content                                                              |
+ * | -------- | ---------------------------------------------------------------------------- |
+ * | `icon`   | Icon, 24 pixels, or 20 pixels in standard and segmented lists.               |
+ * | `avatar` | 40-pixel circular avatar on the primary container color.                     |
+ * | `image`  | 56-pixel square image, with small corners in standard and segmented lists.   |
+ * | `video`  | Video thumbnail, 100 by 56 pixels, or 114 by 64 pixels in three-line items.  |
+ *
+ * Images and video thumbnails are cropped to cover their box.
+ *
+ * @see `ListTokens.kt` `ItemLeading*` tokens
+ */
+export type ListItemLeadingType = "icon" | "avatar" | "image" | "video";
+/**
+ * Properties accepted by {@link List}.
+ */
+export type ListProps = DomProps<HTMLUListElement, Omit<JSX.HTMLAttributes<HTMLUListElement>, "role" | "aria-multiselectable">> & {
+    /**
+     * List style, independent of {@link ListProps.selectionMode | selection behavior}.
+     *
+     * | Variant     | Style                                                              |
+     * | ----------- | ------------------------------------------------------------------ |
+     * | `baseline`  | Material 3 list of square items.                                   |
+     * | `standard`  | Material 3 Expressive list, whose rounded items morph their shape. |
+     * | `segmented` | Material 3 Expressive list of separate, connected item containers. |
+     *
+     * @defaultValue `"baseline"`
+     */
+    variant?: "baseline" | "standard" | "segmented" | undefined;
+    /**
+     * Selection behavior.
+     *
+     * A selecting list is a listbox: its items are options, which an option's activation selects.
+     * Options without a {@link ListItemBaseProps.value | value} are disabled.
+     *
+     * @defaultValue `"none"`
+     */
+    selectionMode?: ListSelectionMode | undefined;
+    /**
+     * Controlled selected value of a single-selection list.
+     */
+    selectedValue?: string | undefined;
+    /**
+     * Controlled selected values of a multiple-selection list.
+     */
+    selectedValues?: readonly string[] | undefined;
+    /**
+     * Initial selected value of an uncontrolled single-selection list.
+     *
+     * When omitted, the first item which is {@link ListItemBaseProps.selected | selected} or
+     * {@link ListItemBaseProps.defaultSelected | selected by default} is selected.
+     */
+    defaultSelectedValue?: string | undefined;
+    /**
+     * Notify the consumer of an option's selection, or request it when controlled.
+     *
+     * @param value - value of the option
+     * @param selected - new or requested selected state of the option
+     * @param event - activating event
+     */
+    onSelectionChange?: ((value: string, selected: boolean, event: Event) => void) | undefined;
+    /**
+     * Alias of {@link ListProps.onSelectionChange | `onSelectionChange`}.
+     *
+     * When both are the same function, it is called once.
+     *
+     * @param value - value of the option
+     * @param selected - new or requested selected state of the option
+     * @param event - activating event
+     */
+    onChange?: ((value: string, selected: boolean, event: Event) => void) | undefined;
+    /**
+     * Use the dense one-line item height.
+     *
+     * @defaultValue `false`
+     */
+    dense?: boolean | undefined;
+};
+/**
+ * Properties accepted by {@link ListItem}.
+ */
+export type ListItemBaseProps = DomProps<HTMLLIElement, Omit<JSX.LiHTMLAttributes<HTMLLIElement>, "role" | "aria-disabled" | "aria-selected" | "tabindex">> & {
+    /**
+     * Value identifying the item as an option of a selecting {@link List}.
+     */
+    value?: string | undefined;
+    /**
+     * Overline content, above the headline.
+     */
+    overline?: JSX.Element;
+    /**
+     * Headline content.
+     *
+     * When omitted, children are the headline.
+     */
+    headline?: JSX.Element;
+    /**
+     * Supporting content, below the headline.
+     */
+    supportingContent?: JSX.Element;
+    /**
+     * Alias of {@link ListItemBaseProps.supportingContent | `supportingContent`}.
+     */
+    supportingText?: JSX.Element;
+    /**
+     * Leading content, such as an icon, avatar, image, or control.
+     */
+    leading?: JSX.Element;
+    /**
+     * Alias of {@link ListItemBaseProps.leading | `leading`}.
+     */
+    leadingContent?: JSX.Element;
+    /**
+     * Preset sizing and styling of the leading content.
+     *
+     * When omitted, leading content is sized by itself.
+     */
+    leadingType?: ListItemLeadingType | undefined;
+    /**
+     * Trailing content, such as an icon, supporting text, or control.
+     */
+    trailing?: JSX.Element;
+    /**
+     * Alias of {@link ListItemBaseProps.trailing | `trailing`}.
+     */
+    trailingContent?: JSX.Element;
+    /**
+     * Number of text lines.
+     *
+     * When omitted, an item with an overline and supporting content has three lines, an item with
+     * either has two lines, and other items have one line. Set `3` for supporting content which
+     * wraps to two lines.
+     */
+    lines?: 1 | 2 | 3 | undefined;
+    /**
+     * Has no effect: an enclosing selecting {@link List} makes its items options.
+     */
+    selectable?: boolean | undefined;
+    /**
+     * Selected state, seeding the selection of an uncontrolled selecting {@link List}.
+     *
+     * The list owns the selection once it is rendered, so later changes have no effect.
+     */
+    selected?: boolean | undefined;
+    /**
+     * Initial selected state, seeding the selection of an uncontrolled selecting {@link List}.
+     */
+    defaultSelected?: boolean | undefined;
+    /**
+     * Disable activation and selection.
+     *
+     * A disabled option remains focusable, as the WAI-ARIA Authoring Practices recommend.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Sequential focus index of an item which is neither an option nor activatable.
+     */
+    tabIndex?: number | undefined;
+    /**
+     * Handle activation of the item.
+     *
+     * An activatable item outside a listbox renders its content as a native button. Cancelling
+     * the activating event prevents selection of an option.
+     *
+     * @param event - activating click or key event
+     */
+    onActivate?: ((event: MouseEvent | KeyboardEvent) => void) | undefined;
+    /**
+     * Notify the consumer of a selection change of the option, made by its {@link List}.
+     *
+     * @param selected - new or requested selected state
+     * @param event - activating event
+     */
+    onSelectedChange?: ((selected: boolean, event: Event) => void) | undefined;
+};
+/**
+ * Properties accepted by {@link ListItem}, including interaction callbacks.
+ */
+export type ListItemProps = InteractableProps<ListItemBaseProps>;
+/**
+ * Client controller of a {@link List}.
+ *
+ * The controller owns the list semantics of its rendered {@link ListItem | items}: in a selecting
+ * list, they are options, selected by activation, with one sequential focus stop roving between
+ * them as focus moves, including with the arrow, Home, and End keys. Disabled options remain
+ * focusable, but are not selectable. Items are found among the list's children, and observed for
+ * changes of their values, disabled states, and visibility, along with the visibility of the
+ * list's ancestors.
+ *
+ * Layout is read for as few items as possible: when the focus stop is chosen, or the focus stop
+ * itself changes, and when navigating with the keyboard. Items are updated only when their state
+ * changes.
+ */
+export declare class ListController extends DomController<ListProps> {
+    #private;
+    /**
+     * Construct a new `ListController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: ListProps);
+    /**
+     * 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;
+}
+/**
+ * List of {@link ListItem | list items}, or listbox of options.
+ *
+ * An ordinary list contains list items, whose activation is independent of the list. A
+ * {@link ListProps.selectionMode | selecting} list is a listbox, which makes its items options:
+ * activating an option selects it, single or multiple selection is controlled or uncontrolled,
+ * and focus roves between options with the arrow, Home, and End keys.
+ *
+ * # Design
+ *
+ * Lists follow the Material 3 list tokens through the [`cw-Surface`](./surface.yaml) `listItem*`
+ * roles. {@link ListProps.variant | `props.variant`} selects the baseline, standard, or segmented
+ * style, which the `data-cw-list-variant` attribute reflects.
+ *
+ * @param props - component properties
+ * @returns rendered list
+ */
+export declare const List: DomComponent<ListProps>;
+/**
+ * Client controller of a {@link ListItem}.
+ *
+ * An item is interactive while it is enabled and either an option of a listbox, which takes focus
+ * itself, or activatable, whose activation button takes focus. Interactive items enter the focus,
+ * hover, and press interaction states. Whether an item is activatable, and so renders an
+ * activation button, is decided when it is rendered.
+ *
+ * The item applies its list semantics from the state its {@link ListController | list} owns, and
+ * its own properties: role, selected and disabled state, sequential focus index, and the state of
+ * its activation button.
+ */
+export declare class ListItemController extends InteractableController<ListItemBaseProps> {
+    #private;
+    /**
+     * Construct a new `ListItemController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: ListItemBaseProps);
+    /**
+     * 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.
+     *
+     * This renders the elements of the server rendering, with the current properties: slots are
+     * reactive, while attributes are static, and updated by the controllers. The activation button
+     * is rendered if, and only if, the item is activatable when rendered.
+     *
+     * @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;
+}
+/**
+ * One-, two-, or three-line list item with leading, headline, supporting, and trailing content.
+ *
+ * Within a selecting {@link List}, the item is an option identified by its {@link
+ * ListItemBaseProps.value | value}, whose selection and focus the list coordinates. An item with
+ * an {@link ListItemBaseProps.onActivate | activation handler} renders its content as a native
+ * button outside a listbox, and is activated along with the option's selection inside one.
+ * Interactive children keep their own activation behavior.
+ *
+ * # States
+ *
+ * Enabled options and activatable items enter the focus, hover, and press interaction states,
+ * which add `cw-ListItem-<state>` classes; the press and focus states of an activatable item
+ * outside a listbox are those of its activation button. Options have the `cw-ListItem-selectable`
+ * class, and selected options the `cw-ListItem-selected` class. Disabled items have the
+ * `cw-ListItem-disabled` class and `aria-disabled="true"`.
+ *
+ * # Design
+ *
+ * Items follow the Material 3 list tokens through the [`cw-Surface`](./surface.yaml) `listItem*`
+ * roles, and the style of the enclosing list. The `data-cw-list-lines` attribute reflects the
+ * number of lines, and {@link ListItemBaseProps.leadingType | `props.leadingType`} sizes the
+ * leading content.
+ *
+ * @param props - component properties
+ * @returns rendered list item
+ */
+export declare const ListItem: InteractableComponent<ListItemBaseProps>;

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

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