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

package/target/tsc/feedback/tooltip.d.ts

@@ -0,0 +1,326 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps, FunctionElement, StyleElement } from "..";
+import { DomController } from "../dom/client";
+import "../container/elevation-shadow.css";
+import "./feedback.css";
+/**
+ * Preferred placement of a tooltip relative to its anchor.
+ *
+ * `"start"` and `"end"` follow the text direction of the anchor.
+ */
+export type TooltipPlacement = "bottom" | "end" | "start" | "top";
+/**
+ * Attributes supplied to a {@link TooltipTriggerFactory}.
+ *
+ * Spread the attributes onto the element which receives focus, or map them to the `attr:`
+ * properties of a Cobweb control. The ARIA attributes and `tabIndex` are reactive getters, so
+ * the trigger is not rendered again as they change. ARIA attributes supplied to the tooltip
+ * through `attr:` properties take precedence over the generated ones.
+ */
+export interface TooltipTriggerContext extends JSX.AriaAttributes {
+    /**
+     * Id of the popup.
+     *
+     * This is metadata, not an attribute: it is not enumerable, so a spread omits it.
+     */
+    readonly popupId: string;
+    /**
+     * Popup is open.
+     *
+     * This is metadata, not an attribute: it is not enumerable, so a spread omits it.
+     */
+    readonly open: boolean;
+    /**
+     * Sequential focus index: `0` while the tooltip is enabled, `undefined` while disabled.
+     */
+    readonly tabIndex: 0 | undefined;
+    /**
+     * Id of the popup, describing the trigger; `undefined` while disabled.
+     */
+    readonly "aria-describedby"?: string;
+    /**
+     * Id of the popup of a rich tooltip; `undefined` for a plain tooltip and while disabled.
+     */
+    readonly "aria-controls"?: string;
+    /**
+     * Visibility of the popup of a rich tooltip; `undefined` for a plain tooltip and while
+     * disabled.
+     */
+    readonly "aria-expanded"?: "false" | "true";
+    /**
+     * `"dialog"` for a rich tooltip; `undefined` for a plain tooltip and while disabled.
+     */
+    readonly "aria-haspopup"?: JSX.AriaAttributes["aria-haspopup"];
+}
+/**
+ * Function rendering the trigger of a tooltip.
+ *
+ * The returned element is the anchor of the tooltip, and receives keyboard focus, so it is
+ * rendered identically by the server and the client.
+ *
+ * @param context - attributes linking the trigger to the popup
+ * @returns trigger element
+ */
+export type TooltipTriggerFactory = (context: TooltipTriggerContext) => JSX.Element;
+/**
+ * Properties common to {@link PlainTooltip} and {@link RichTooltip}.
+ */
+export type TooltipBaseProps = DomProps<HTMLSpanElement, Omit<JSX.HTMLAttributes<HTMLSpanElement>, "role">> & {
+    /**
+     * Content of the popup: the text of a plain tooltip, or the supporting text of a rich
+     * tooltip.
+     */
+    content?: JSX.Element;
+    /**
+     * Popup is open.
+     *
+     * Supplying this property, including as `undefined`, controls the tooltip: interaction then
+     * requests visibility changes through {@link TooltipBaseProps.onOpenChange | `onOpenChange`},
+     * which the owner accepts by updating this property. Omit it to let interaction open and close
+     * the tooltip.
+     */
+    open?: boolean | undefined;
+    /**
+     * Delay before hover or keyboard focus opens the popup, in milliseconds.
+     *
+     * Negative delays are `0`, and non-finite delays the default. A touch long press always opens
+     * after 500 milliseconds.
+     *
+     * @defaultValue `500`
+     */
+    showDelay?: number | undefined;
+    /**
+     * Delay before the popup closes once neither hovered nor focused, or once a long press ends,
+     * in milliseconds.
+     *
+     * Negative delays are `0`, and non-finite delays the default. Escape, activation, and a
+     * cancelled touch close the popup at once.
+     *
+     * @defaultValue `1500`
+     */
+    hideDelay?: number | undefined;
+    /**
+     * Preferred placement of the popup.
+     *
+     * The popup is placed on the opposite side when the preferred side lacks room, and is kept
+     * within the viewport.
+     *
+     * @defaultValue `"top"`
+     */
+    placement?: TooltipPlacement | undefined;
+    /**
+     * Popup shows a caret pointing at its anchor (`TooltipDefaults.caretShape()`).
+     *
+     * @defaultValue `false`
+     */
+    caret?: boolean | undefined;
+    /**
+     * Tooltip is disabled: interaction does not open it, its popup is closed, and the trigger is
+     * not linked to the popup.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Id of the popup, referenced by the trigger; generated when omitted.
+     */
+    id?: string | undefined;
+    /**
+     * Function rendering the trigger.
+     *
+     * The trigger receives the attributes linking it to the popup. Without a factory, nested
+     * children are wrapped by an element which links the first focusable child, or becomes
+     * focusable itself when no child is.
+     */
+    trigger?: TooltipTriggerFactory | undefined;
+    /**
+     * Function notified of a request to change the visibility of the popup.
+     *
+     * Opening a tooltip through interaction also requests the other open tooltips of its document
+     * to close.
+     *
+     * @param open - requested visibility
+     */
+    onOpenChange?: ((open: boolean) => void) | undefined;
+};
+/**
+ * {@link PlainTooltip} component properties.
+ */
+export type PlainTooltipProps = TooltipBaseProps;
+/**
+ * {@link RichTooltip} component properties.
+ */
+export type RichTooltipProps = TooltipBaseProps & {
+    /**
+     * Title, which also names the popup.
+     */
+    title?: JSX.Element;
+    /**
+     * Accessible name of the popup without a title.
+     *
+     * @defaultValue `"Tooltip"`
+     */
+    popupLabel?: string | undefined;
+    /**
+     * Supporting text, superseding {@link TooltipBaseProps.content | `content`}.
+     */
+    supportingText?: JSX.Element;
+    /**
+     * Action content, usually a text button.
+     */
+    action?: JSX.Element;
+    /**
+     * Popup stays open until dismissed (`TooltipState.isPersistent`).
+     *
+     * A persistent tooltip opens on hover, keyboard focus, long press, and activation of its
+     * trigger, which also closes it again. It does not close when the pointer or focus leaves it,
+     * but on Escape and on a press outside of the trigger and the popup. Make a tooltip with an
+     * action persistent, so its action remains reachable.
+     *
+     * @defaultValue `false`
+     */
+    persistent?: boolean | undefined;
+};
+/**
+ * Client-side controller shared by tooltips.
+ *
+ * The controller links the element which actually receives focus, the *target*, to the popup:
+ * the element rendered by a trigger factory, the first focusable child of the trigger wrapper,
+ * or the wrapper itself. It opens and closes the popup on interaction, coordinates open tooltips
+ * of a document, and positions the popup in the top layer.
+ *
+ * # Interaction
+ *
+ * | Interaction                    | Plain or rich tooltip       | Persistent rich tooltip     |
+ * | ------------------------------ | --------------------------- | --------------------------- |
+ * | Hover the trigger or the popup | Opens after the show delay  | Opens after the show delay  |
+ * | Keyboard focus on the target   | Opens after the show delay  | Opens after the show delay  |
+ * | Pointer and focus leave        | Closes after the hide delay | Stays open                  |
+ * | Touch long press               | Opens; release starts the hide delay | Opens          |
+ * | Activate the trigger           | Closes                      | Opens or closes             |
+ * | Escape                         | Closes the most recent      | Closes the most recent      |
+ * | Press outside                  | Closes                      | Closes                      |
+ *
+ * @typeParam P - component properties type
+ */
+export declare abstract class TooltipController<P extends TooltipBaseProps> extends DomController<P> {
+    #private;
+    /**
+     * Construct a new controller.
+     *
+     * @param props - component properties
+     * @param rich - tooltip is rich
+     */
+    constructor(props: P, rich: boolean);
+    /**
+     * Popup is persistent.
+     *
+     * @returns `true` if, and only if, the popup stays open until dismissed
+     */
+    protected get persistent(): boolean;
+    protected applyComponentProps(): void;
+    /**
+     * Name the popup.
+     *
+     * This is invoked by {@link TooltipController.applyComponentProps}, in the same tracking
+     * context, after the popup id is applied. A plain tooltip popup needs no name.
+     *
+     * @param _popup - popup element
+     */
+    protected applyPopupName(_popup: HTMLSpanElement): void;
+    protected onFunctionElementChanged(curr: FunctionElement<P> | null): void;
+    protected onStyleElementChanged(curr: StyleElement | null): void;
+    protected onControllerCleanup(): void;
+    /**
+     * Render the trigger content.
+     *
+     * @param children - nested children
+     * @returns trigger content
+     */
+    protected renderTrigger(children: JSX.Element): JSX.Element;
+    /**
+     * Register the rendered popup of the tooltip.
+     *
+     * @param popup - popup element
+     */
+    protected setPopup(popup: HTMLSpanElement): void;
+}
+/**
+ * Client-side controller of a {@link PlainTooltip}.
+ */
+export declare class PlainTooltipController extends TooltipController<PlainTooltipProps> {
+    /**
+     * Construct a new controller.
+     *
+     * @param props - component properties
+     */
+    constructor(props: PlainTooltipProps);
+    protected render(children: JSX.Element, funcRef?: (elem: FunctionElement<PlainTooltipProps>) => void): JSX.Element;
+}
+/**
+ * Material 3 plain tooltip.
+ *
+ * A plain tooltip briefly describes an element, usually an icon button, in a small popup which
+ * opens on hover, keyboard focus, and touch long press, and closes once the pointer and focus
+ * leave, or on Escape. The popup describes the element which receives focus through
+ * `aria-describedby`; keep its content short and non-interactive, and give the element its own
+ * accessible name.
+ *
+ * Render the trigger through {@link TooltipBaseProps.trigger | `props.trigger`}, which renders
+ * the same linkage on the server and the client. Popups are positioned in the top layer, above
+ * clipping containers.
+ *
+ * # Design
+ *
+ * Design is controlled through the `tooltip` roles of the [`cw-Feedback`](./feedback.yaml) design
+ * attribute (`PlainTooltipTokens`): an inverse surface container with an extra small shape, from
+ * 40px to 200px wide and at least 24px tall, 4px from its anchor. Opening fades the popup in with
+ * the fast effects spring while scaling it from 0.8 with the fast spatial spring (`Tooltip.kt`).
+ * {@link TooltipBaseProps.caret | `props.caret`} adds a caret pointing at the anchor.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const PlainTooltip: DomComponent<PlainTooltipProps>;
+/**
+ * Client-side controller of a {@link RichTooltip}.
+ */
+export declare class RichTooltipController extends TooltipController<RichTooltipProps> {
+    #private;
+    /**
+     * Construct a new controller.
+     *
+     * @param props - component properties
+     */
+    constructor(props: RichTooltipProps);
+    protected get persistent(): boolean;
+    protected applyComponentProps(): void;
+    protected applyPopupName(popup: HTMLSpanElement): void;
+    protected render(children: JSX.Element, funcRef?: (elem: FunctionElement<RichTooltipProps>) => void): JSX.Element;
+}
+/**
+ * Material 3 rich tooltip.
+ *
+ * A rich tooltip shows a title, supporting text, and an optional action in a popup, a non-modal
+ * `dialog`, which opens on hover, keyboard focus, and touch long press. Focus stays on the
+ * trigger as the popup opens, and Tab reaches its action; Escape closes the popup, returning
+ * focus to the trigger when it was within the popup. A
+ * {@link RichTooltipProps.persistent | persistent} tooltip also opens and closes through its
+ * trigger, and stays open until dismissed, as a tooltip with an action should.
+ *
+ * The trigger is linked to the popup through `aria-controls`, `aria-describedby`,
+ * `aria-expanded`, and `aria-haspopup`. The popup is named by its title, or by
+ * {@link RichTooltipProps.popupLabel | `props.popupLabel`}.
+ *
+ * # Design
+ *
+ * Design is controlled through the `tooltip` roles of the [`cw-Feedback`](./feedback.yaml) design
+ * attribute, with the `richTooltip` theme (`RichTooltipTokens`): a surface container with a
+ * medium shape and level 2 elevation, up to 320px wide, 4px from its anchor. The title is
+ * title-small in the on-surface-variant color, and Material buttons in the action slot take the
+ * primary color.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const RichTooltip: DomComponent<RichTooltipProps>;

package/target/tsc/icon/icon.css.d.ts

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

package/target/tsc/icon/icon.d.ts

@@ -0,0 +1,69 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps } from "..";
+import "./icon.css";
+/**
+ * Icon {@link Icon | component} properties.
+ */
+export type IconProps = DomProps<HTMLElement, JSX.HTMLElementTags["i"]> & {
+    /**
+     * Icon is mirrored horizontally in a right-to-left context.
+     *
+     * Enable this for icons indicating a direction, such as arrows pointing back or forward, so
+     * that they point the same way as the layout when the directionality of the icon element is
+     * right-to-left.
+     *
+     * @defaultValue `false`
+     */
+    autoMirror?: boolean;
+    /**
+     * Name of icon to render.
+     *
+     * If this is not omitted, then any {@link IconProps.children | nested} children are
+     * ignored.
+     */
+    name?: string | undefined;
+};
+/**
+ * Icon component.
+ *
+ * Icons are rendered within a non-interactive container. There is no restriction on what may be
+ * nested within an icon component; however, usually text will be nested within the icon. As there
+ * are no restrictions on nesting, an `<img>` may also be nested within an icon, without any text.
+ * The `<img>` will then be rendered in place of the icon font rendered icon.
+ *
+ * If {@link IconProps.name | `props.name`} is specified, then all nested children are ignored and
+ * `props.name` is used as the name of the icon to render. This may be preferred as this evaluates
+ * to a simple `textContent` assignment, which performs better than updating nested children.
+ *
+ * By default, rendered elements have the `attr:aria-hidden` and `attr:role` attributes set to
+ * `true` and `img`, respectively. This can be disabled by explicitly setting `attr:aria-hidden`
+ * or `attr:role` within `props`.
+ *
+ * Since icon components are not interactable, `event:*` handlers, such as `event:click`, will
+ * never be invoked. These handlers should be excluded from `props`. If handling events is
+ * required, the icon component should be nested within an interactable container.
+ *
+ * # Design
+ *
+ * Icons are rendered with the icon font specification, defined by the
+ * [`cw-IconFont`](./icon-font.yaml) reference design attribute. Component specific design,
+ * however, is controlled through the [`cw-Icon`](./icon.yaml) design attribute. Its fill, grade,
+ * and weight roles set the corresponding axes of the icon font, while the optical size axis
+ * follows the icon size. The fill role is a number, so that transitions of it animate the fill.
+ * The glyphs of an icon without nested elements are painted in the icon color as graphics,
+ * smoothed in grayscale, unless colors are forced. Icons indicating a direction set
+ * {@link IconProps.autoMirror | `props.autoMirror`} to be mirrored in a right-to-left context.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ * @example
+ * ```tsx
+ * // Renders a `home` icon using the configured icon font.
+ * <Icon>home</Icon> // equivalent to: <Icon name="home" />
+ * // Renders an image icon:
+ * <Icon><img src="https://foo/bar.png" /></Icon>
+ * // Renders a back arrow, pointing right in a right-to-left context:
+ * <Icon autoMirror name="arrow_back" />
+ * ```
+ */
+export declare const Icon: DomComponent<IconProps>;

package/target/tsc/icon/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Icon definitions.
+ *
+ * This module defines the {@link Icon} component. While icon components are not formally defined
+ * by the Material 3 design specification, the [`cw-IconFont`](./icon-font.yaml) design attribute
+ * is well [defined](https://m3.material.io/styles/icons/overview). The icon component uses this
+ * reference design attribute, along with the [`cw-Icon`](./icon.yaml) component design attribute,
+ * to control its design.
+ *
+ * @packageDocumentation
+ */
+export type { IconProps } from "./icon";
+export { Icon } from "./icon";

package/target/tsc/index.css.d.ts

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

package/target/tsc/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Components library, based on Material 3, for SolidJS.
+ *
+ * @packageDocumentation
+ */
+export type { BaseDomProps, ClientDomProps, DomAttributes, DomComponent, DomController, DomControllerOptions, DomEventHandlerProps, DomProps, DomTag, ElementDomProps, FunctionElement, PickDomAttributes, PickLocalDomProps, ReadProps, RenderServerDom, StyleElement } from "./dom";
+export { defineDomComponent } from "./dom";

package/target/tsc/input/autocomplete.d.ts

@@ -0,0 +1,119 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, FunctionElement } from "..";
+import type { TextFieldProps } from "./text-field";
+import { TextFieldController } from "./text-field";
+import "../container/elevation-shadow.css";
+/**
+ * {@link Autocomplete} component properties.
+ *
+ * An autocomplete field accepts the single-line {@link ./text-field#TextFieldProps | text-field
+ * properties}. Use `attr:form` to associate the native input with a form outside its ancestors.
+ */
+export type AutocompleteProps = Omit<TextFieldProps, "cols" | "max" | "min" | "multiline" | "revealPassword" | "revealPasswordLabel" | "rows" | "secure" | "step" | "type"> & {
+    /**
+     * Suggestions shown in the menu, in order.
+     *
+     * The caller filters the suggestions for the current value, which it receives through the
+     * value-change callbacks. Choosing a suggestion commits it as the field value. The menu is
+     * shown while the user edits the field or navigates the suggestions, and while there is at
+     * least one suggestion.
+     */
+    options: readonly string[];
+};
+/**
+ * Client controller of an {@link Autocomplete}.
+ *
+ * The native input is an ARIA 1.2 combobox controlling a listbox of suggestions, which opens in the
+ * top layer as a native popover. The input keeps focus while suggestions are navigated; the active
+ * suggestion is referenced by `aria-activedescendant`.
+ *
+ * # Keyboard
+ *
+ * | Key | Behavior |
+ * | --- | --- |
+ * | Down arrow | Open the menu and activate the first suggestion, or activate the next one. |
+ * | Up arrow | Open the menu and activate the last suggestion, or activate the previous one. |
+ * | Alt + Down arrow | Open the menu without activating a suggestion. |
+ * | Home, End | Activate the first or last suggestion while one is active. |
+ * | Enter | Choose the active suggestion. |
+ * | Escape | Close the menu. |
+ *
+ * Typing opens the menu without activating a suggestion; moving focus away closes it. A field
+ * which is read-only or disabled, including through a disabled `<fieldset>` ancestor, neither
+ * opens the menu nor chooses a suggestion: the arrow keys keep their native behavior, and the
+ * menu closes when the field becomes read-only or disabled.
+ */
+export declare class AutocompleteController extends TextFieldController<AutocompleteProps> {
+    #private;
+    /**
+     * Construct a new `AutocompleteController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: AutocompleteProps);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Handle function element replacement before the controller reference is updated.
+     *
+     * @param element - new function element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onFunctionElementChanged}
+     */
+    protected onFunctionElementChanged(element: FunctionElement<AutocompleteProps> | null): void;
+    /**
+     * Render the suggestion menu after the field.
+     *
+     * Suggestions are a reactive list; every other part of the menu is static.
+     *
+     * @returns suggestion menu
+     * @see {@link ./text-field#TextFieldController.renderExtension}
+     */
+    protected renderExtension(): JSX.Element;
+}
+/**
+ * Material 3 autocomplete text field.
+ *
+ * An autocomplete field is a single-line {@link ./text-field#TextField | text field} whose
+ * suggestions, supplied and filtered by the caller, are shown in a menu below the field
+ * (`FilledAutocompleteTokens.kt`, `OutlinedAutocompleteTokens.kt`). Choosing a suggestion
+ * commits it as the field value through the value-change callbacks; the native input keeps
+ * submitting the field value with its form.
+ *
+ * # States
+ *
+ * The field states follow {@link ./text-field#TextField}. The menu opens, scaling and fading in,
+ * while the user edits the field or navigates the suggestions, and closes when a suggestion is
+ * chosen, Escape is pressed, focus leaves the field, or no suggestion remains. A read-only or
+ * disabled field offers no suggestions.
+ *
+ * # Design
+ *
+ * Design is controlled through the [`cw-TextField`](./text-field.yaml) component design attribute,
+ * whose `menu` roles style the suggestion menu. The root element has the `cw-TextField` and
+ * `cw-Autocomplete` classes; the menu has the `cw-Autocomplete-menu` class and each suggestion
+ * the `cw-Autocomplete-option` class.
+ *
+ * # Accessibility
+ *
+ * The input is an ARIA 1.2 combobox with list autocompletion, controlling the suggestion listbox;
+ * see {@link AutocompleteController} for keyboard interaction.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ * @example
+ * ```tsx
+ * const [city, setCity] = createSignal("");
+ *
+ * <Autocomplete
+ *   label="City"
+ *   value={city()}
+ *   onValueChange={setCity}
+ *   options={CITIES.filter((name) => name.toLowerCase().startsWith(city().toLowerCase()))}
+ * />
+ * ```
+ */
+export declare const Autocomplete: DomComponent<AutocompleteProps>;