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

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

@@ -0,0 +1,384 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps, StyleElement } from "..";
+import type { ListProps } from "./list";
+import { DomController } from "../dom/client";
+import { ListController } from "./list";
+import "../container/elevation-shadow.css";
+import "./surface.css";
+import "./list.css";
+/**
+ * Properties accepted by {@link ExpandedListItem}.
+ */
+export type ExpandedListItemProps = DomProps<HTMLLIElement, JSX.LiHTMLAttributes<HTMLLIElement>> & {
+    /**
+     * Summary headline.
+     */
+    headline?: JSX.Element;
+    /**
+     * Leading content of the summary.
+     */
+    leading?: JSX.Element;
+    /**
+     * Supporting text beneath the headline.
+     */
+    supportingText?: JSX.Element;
+    /**
+     * Controlled disclosure state.
+     */
+    open?: boolean | undefined;
+    /**
+     * Initial disclosure state of an uncontrolled item.
+     *
+     * @defaultValue `false`
+     */
+    defaultOpen?: boolean | undefined;
+    /**
+     * Prevent disclosure changes.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Notify the consumer of a disclosure change, or request it when controlled.
+     *
+     * A controlled item restores its `open` state unless the parent accepts the request.
+     * Cancelling the event does not restore an uncontrolled item.
+     *
+     * @param open - new or requested disclosure state
+     * @param event - native `toggle` event of the disclosure
+     */
+    onOpenChange?: ((open: boolean, event: Event) => void) | undefined;
+};
+/**
+ * Client controller of an {@link ExpandedListItem}.
+ *
+ * The native disclosure toggles itself; the controller notifies each toggle, restores a toggle
+ * of a controlled item which the parent did not accept, and prevents toggling a disabled item.
+ */
+export declare class ExpandedListItemController extends DomController<ExpandedListItemProps> {
+    #private;
+    /**
+     * Construct a new `ExpandedListItemController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: ExpandedListItemProps);
+    /**
+     * 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: the summary
+     * slots and the body are reactive, while attributes are static.
+     *
+     * @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 item whose summary row discloses expanded content.
+ *
+ * The item is a native disclosure, with native keyboard and accessibility behavior. Its open
+ * state is controlled or uncontrolled.
+ *
+ * # Design
+ *
+ * The item follows the Material 3 expanded list tokens (`ExpandedListTokens.kt`): a rounded
+ * container, and a trailing Material Symbols `expand_more` icon whose container changes and which
+ * turns over while open. The icon is hidden from accessibility.
+ *
+ * @param props - component properties
+ * @returns rendered list item
+ */
+export declare const ExpandedListItem: DomComponent<ExpandedListItemProps>;
+/**
+ * Properties accepted by {@link RevealListItem}.
+ */
+export type RevealListItemProps = DomProps<HTMLLIElement, JSX.LiHTMLAttributes<HTMLLIElement>> & {
+    /**
+     * Row headline.
+     *
+     * When omitted, children are the headline.
+     */
+    headline?: JSX.Element;
+    /**
+     * Leading content of the row.
+     */
+    leading?: JSX.Element;
+    /**
+     * Supporting text beneath the headline.
+     */
+    supportingText?: JSX.Element;
+    /**
+     * Native buttons or links revealed beside the row.
+     */
+    actions?: JSX.Element;
+    /**
+     * Controlled visibility of the actions.
+     */
+    expanded?: boolean | undefined;
+    /**
+     * Initial visibility of the actions of an uncontrolled item.
+     *
+     * @defaultValue `false`
+     */
+    defaultExpanded?: boolean | undefined;
+    /**
+     * Prevent revealing and hiding the actions.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Accessible name of the toggle button while the actions are hidden.
+     *
+     * @defaultValue `"Show actions"`
+     */
+    revealLabel?: string | undefined;
+    /**
+     * Accessible name of the toggle button while the actions are revealed.
+     *
+     * @defaultValue `"Hide actions"`
+     */
+    hideLabel?: string | undefined;
+    /**
+     * Notify the consumer of a request to reveal or hide the actions.
+     *
+     * Update a controlled `expanded` to accept the request. An uncontrolled item updates after
+     * the callback; cancelling the event does not veto the update.
+     *
+     * @param expanded - requested visibility of the actions
+     * @param event - toggle button click, Escape key, or releasing pointer event
+     */
+    onExpandedChange?: ((expanded: boolean, event: Event) => void) | undefined;
+};
+/**
+ * Client controller of a {@link RevealListItem}.
+ *
+ * A primary pointer moving horizontally, past {@link GESTURE_SLOP}, captures the pointer and
+ * slides the row over its actions; vertical movement first releases the gesture to native
+ * scrolling. The row moves by transforms only, along the measured width of the actions. On
+ * release, the requested state is chosen as Compose's anchored drag does, with a positional
+ * threshold of half the width, and the row settles with a spatial spring which continues the
+ * release velocity. State changes from the toggle button, the Escape key, or properties settle
+ * the same way. Pressing the row stops it where it is, so that a drag continues from there; a
+ * press which claims no drag, such as a tap or a scroll, or which is ended by disabling the item,
+ * requests no change, and the row resumes settling at the current visibility.
+ */
+export declare class RevealListItemController extends DomController<RevealListItemProps> {
+    #private;
+    /**
+     * Construct a new `RevealListItemController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: RevealListItemProps);
+    /**
+     * 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. The
+     * identifier of server-rendered actions is kept.
+     *
+     * @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: the row
+     * slots and the actions are reactive, while attributes are static.
+     *
+     * @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 item revealing secondary actions beside its row.
+ *
+ * The toggle button reveals and hides the actions, so the gesture is an enhancement: swiping
+ * the row toward the inline start reveals them, and back hides them. The Escape key hides
+ * revealed actions. Hidden actions are inert and hidden from accessibility. Visibility is
+ * controlled or uncontrolled.
+ *
+ * # States
+ *
+ * The item has the `cw-RevealListItem-expanded` class while its actions are revealed, the
+ * `cw-RevealListItem-dragging` class while dragged, and the `cw-RevealListItem-settling` class
+ * while its row settles.
+ *
+ * # Design
+ *
+ * The item follows the Material 3 reveal list tokens (`RevealListTokens.kt`). The toggle button
+ * shows the Material Symbols `arrow_forward` icon, mirrored in a right-to-left context, which turns
+ * over while the actions are revealed. The icon is hidden from accessibility; the accessible name
+ * of the button is its {@link RevealListItemProps.revealLabel | `revealLabel`} or
+ * {@link RevealListItemProps.hideLabel | `hideLabel`}.
+ *
+ * @param props - component properties
+ * @returns rendered list item
+ */
+export declare const RevealListItem: DomComponent<RevealListItemProps>;
+/**
+ * Properties accepted by {@link ReorderableList}.
+ */
+export type ReorderableListProps = Omit<ListProps, "selectionMode"> & {
+    /**
+     * Unique values of the rows, in rendered order.
+     *
+     * Render keyed {@link ./list#ListItem | list items} with these values.
+     */
+    values: readonly string[];
+    /**
+     * Request an order of the rows, including the restoration of a cancelled move.
+     *
+     * The list is controlled: update `values` and the keyed rows to accept the order.
+     *
+     * @param values - requested values, in rendered order
+     * @param event - event which moved a row or cancelled the move
+     */
+    onReorder: (values: readonly string[], event: Event) => void;
+    /**
+     * Prevent moving rows by dragging and with the keyboard.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Customize the announcements of the live status region.
+     *
+     * @param value - value of the moved row
+     * @param position - one-based position in the current `values`, or `0` if the row was removed
+     * @param total - number of rows
+     * @param moving - the row is still being moved
+     * @param cancelled - the move was cancelled, and the original order requested
+     * @returns announced text
+     */
+    announcement?: ((value: string, position: number, total: number, moving: boolean, cancelled: boolean) => string) | undefined;
+};
+/**
+ * Properties accepted by {@link ReorderHandle}.
+ */
+export type ReorderHandleProps = DomProps<HTMLButtonElement, JSX.ButtonHTMLAttributes<HTMLButtonElement>> & {
+    /**
+     * Accessible name, which should include the name of the row.
+     *
+     * @defaultValue `"Reorder item"`
+     */
+    label?: string | undefined;
+    /**
+     * Disable the handle.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+};
+/**
+ * Native button moving the row of a {@link ReorderableList} it is placed in.
+ *
+ * Place the handle in the trailing slot of each row. Dragging it moves the row; Space lifts and
+ * drops the row, and while lifted, the arrow, Home, and End keys move it, and Escape cancels the
+ * move. The handle is pressed while its row is lifted.
+ *
+ * The handle shows its children, or else the Material Symbols `drag_handle` icon, which is hidden
+ * from accessibility; its accessible name is its {@link ReorderHandleProps.label | `label`}.
+ *
+ * @param props - component properties
+ * @returns rendered handle
+ */
+export declare const ReorderHandle: DomComponent<ReorderHandleProps>;
+/**
+ * Client controller of a {@link ReorderableList}.
+ *
+ * Rows are moved through order requests, so Solid keeps owning the row nodes. A drag from a
+ * handle lifts its row, measures the rows once, and then follows the pointer with transforms:
+ * the rows the dragged row passes move out of the way, leaving a drop zone where it would be
+ * dropped. On release, the order is requested, and the dropped row settles into its new position
+ * with a spatial spring which continues the release velocity. Pressing a handle without dragging
+ * lifts its row for keyboard moves.
+ */
+export declare class ReorderableListController extends ListController {
+    #private;
+    /**
+     * Construct a new `ReorderableListController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: ReorderableListProps);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * A lifted row which is no longer rendered, or a disabled list, ends the move.
+     *
+     * @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 status region and list, the list being the style element
+     * @see {@link ../dom/client#DomController.render}
+     */
+    protected render(children: JSX.Element): JSX.Element;
+}
+/**
+ * Controlled list whose rows move by dragging, with a complete keyboard alternative.
+ *
+ * Render keyed {@link ./list#ListItem | list items} from {@link ReorderableListProps.values |
+ * `values`}, each with a {@link ReorderHandle} in its trailing slot, and accept requested orders
+ * in {@link ReorderableListProps.onReorder | `onReorder`}. The list never reparents the rows
+ * itself. Space on a handle lifts and drops its row; the arrow, Home, and End keys request moves,
+ * and Escape requests the original order. A live status region, rendered before the list,
+ * announces positions.
+ *
+ * # States
+ *
+ * The lifted row has the `cw-ReorderableList-moving` class and is styled as dragged, and its
+ * handle is pressed. While dragged, the list has the `cw-ReorderableList-dragging` class, and the
+ * rows the dragged row passes have the `cw-ReorderableList-shiftedUp` or
+ * `cw-ReorderableList-shiftedDown` class. A dropped row has the `cw-ReorderableList-settling`
+ * class while it settles.
+ *
+ * # Design
+ *
+ * The dragged row follows the Material 3 reorder list tokens (`ReorderListTokens.kt`) and the
+ * dragged list item tokens (`ListTokens.kt`), through the [`cw-Surface`](./surface.yaml)
+ * `listItemDragged*` and `listItemDropZoneColor` roles.
+ *
+ * @param props - component properties
+ * @returns rendered status region and list
+ */
+export declare const ReorderableList: DomComponent<ReorderableListProps>;

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

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