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

package/target/tsc/action/group.d.ts

@@ -0,0 +1,166 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps } from "..";
+import type { SegmentedButtonItem, SegmentedGroupChangeHandler, SegmentedGroupValue } from "../selection/segmented";
+import type { ActionButtonSize } from "./base";
+import "./action.css";
+/**
+ * Button-group variants.
+ */
+export type ButtonGroupVariant = "connected" | "standard";
+/**
+ * Button-group orientation.
+ */
+export type ButtonGroupOrientation = "horizontal" | "vertical";
+/**
+ * Selectable button-group item.
+ */
+export type ButtonGroupItem = SegmentedButtonItem;
+/**
+ * Selected button-group value or values.
+ */
+export type ButtonGroupValue = SegmentedGroupValue;
+/**
+ * Button-group selection callback.
+ */
+export type ButtonGroupChangeHandler = SegmentedGroupChangeHandler;
+/**
+ * Action of a button group, rendered as a button, or as an item of the overflow menu while it does
+ * not fit into the group.
+ *
+ * An action supplied `checked` is a toggle, rendered as a {@link ./button#ToggleButton} and a
+ * checkbox menu item (`ButtonGroupScope.toggleableItem`); any other action is a
+ * {@link ./button#Button} and a menu item (`ButtonGroupScope.clickableItem`). An action has no
+ * link destination, since a menu item is not a link: a group of links nests buttons with an
+ * `href` as its children instead.
+ */
+export interface ButtonGroupAction {
+    /**
+     * Label of the button and of the menu item.
+     */
+    readonly label: string;
+    /**
+     * Icon font ligature name of a leading icon, if any.
+     */
+    readonly icon?: string | undefined;
+    /**
+     * Action cannot be activated.
+     *
+     * @defaultValue `false`
+     */
+    readonly disabled?: boolean | undefined;
+    /**
+     * Selected state of a toggle action.
+     */
+    readonly checked?: boolean | undefined;
+    /**
+     * Activate the action, from its button or from its menu item.
+     */
+    readonly onClick?: (() => void) | undefined;
+    /**
+     * Request the next selected state of a toggle action, from its button or from its menu item.
+     *
+     * @param checked - requested selected state
+     */
+    readonly onCheckedChange?: ((checked: boolean) => void) | undefined;
+}
+/**
+ * Button-group properties.
+ */
+export type ButtonGroupProps = DomProps<HTMLDivElement, JSX.HTMLAttributes<HTMLDivElement>> & {
+    /**
+     * Size of every action, which overrides their own sizes.
+     *
+     * @defaultValue `"sm"`
+     */
+    size?: ActionButtonSize | undefined;
+    /**
+     * Shape of every action, which overrides their own shapes. In a connected group, this is the
+     * shape of the outer corners.
+     *
+     * @defaultValue `"round"`
+     */
+    shape?: "round" | "square" | undefined;
+    /**
+     * Group visual treatment. Pressing an action of a standard, horizontal group widens it at the
+     * expense of its neighbors.
+     *
+     * @defaultValue `"standard"`
+     */
+    variant?: ButtonGroupVariant | undefined;
+    /**
+     * Group orientation.
+     *
+     * @defaultValue `"horizontal"`
+     */
+    orientation?: ButtonGroupOrientation | undefined;
+    /**
+     * Actions of the group, in place of children.
+     *
+     * A horizontal group of actions fills the inline size of its container. Actions which do not
+     * fit into it, from the first which does not, move into a menu opened by an overflow indicator
+     * at the end of the group (`ButtonGroup`, `overflowIndicator`). A vertical group shows every
+     * action, and has no overflow indicator. The presence of this property is read once at
+     * construction.
+     */
+    actions?: readonly ButtonGroupAction[] | undefined;
+    /**
+     * Accessible name and plain tooltip of the overflow indicator, and accessible name of its menu.
+     *
+     * @defaultValue `"More options"`
+     */
+    overflowLabel?: string | undefined;
+    /**
+     * Enable coordinated selection for segmented-button children or data items.
+     *
+     * Omit this property for ordinary action grouping. Changing its presence replaces the group
+     * implementation and initializes the newly selected mode from its current properties.
+     */
+    selection?: "single" | "multiple" | undefined;
+    /**
+     * Controlled selected value or values.
+     */
+    value?: SegmentedGroupValue | undefined;
+    /**
+     * Initial selected value or values.
+     */
+    defaultValue?: SegmentedGroupValue | undefined;
+    /**
+     * Prevent deselecting the final selected item.
+     *
+     * @defaultValue `false`
+     */
+    required?: boolean | undefined;
+    /**
+     * Selection callback.
+     */
+    onValueChange?: SegmentedGroupChangeHandler | undefined;
+    /**
+     * Selectable items, with deterministic server focus order.
+     */
+    items?: readonly SegmentedButtonItem[] | undefined;
+};
+/**
+ * Material 3 button group.
+ *
+ * A button group arranges actions, giving them one size and shape. A standard group spaces its
+ * actions; pressing an action of a horizontal standard group widens it and narrows its neighbors.
+ * A connected group joins its actions with small inner corners which morph while pressed; a
+ * selected action becomes fully round.
+ *
+ * Ordinary groups preserve their authored children. A group of
+ * {@link ButtonGroupProps.actions | actions} renders them as buttons, and moves those which do not
+ * fit into a menu opened by an overflow indicator with a plain tooltip of its name, as Compose's
+ * `ButtonGroup` does. With `selection`, the group renders segmented buttons from children or
+ * `items`, with the item data, form values, roving focus, and selection callbacks of
+ * {@link SegmentedButtonGroup}, sized as actions of the group size and colored as filled toggle
+ * buttons.
+ *
+ * # Design
+ *
+ * The [cw-ButtonGroup](./button-group.yaml) attribute defines the spacing and connected inner
+ * corners; the actions are sized by their `cw-Button` size theme.
+ *
+ * @param props - group properties
+ * @returns rendered group
+ */
+export declare const ButtonGroup: DomComponent<ButtonGroupProps>;

package/target/tsc/action/icon-button.d.ts

@@ -0,0 +1,79 @@
+import type { JSX } from "solid-js";
+import type { InteractableComponent, InteractableProps } from "../state";
+import type { ActionButtonSize, BaseActionButtonProps } from "./base";
+/**
+ * Icon-button visual variants.
+ */
+export type IconButtonVariant = "filled" | "filled-tonal" | "outlined" | "standard";
+/**
+ * Icon-button sizes, each with an optional narrow or wide container width.
+ */
+export type IconButtonSize = `${ActionButtonSize}${"" | "-narrow" | "-wide"}`;
+/**
+ * Icon button properties.
+ *
+ * An icon button supplied `toggle` is a toggle, as an {@link IconToggleButton} is.
+ */
+export type IconButtonProps = BaseActionButtonProps & {
+    /**
+     * Icon-button visual variant.
+     *
+     * @defaultValue `"standard"`
+     */
+    variant?: IconButtonVariant | undefined;
+    /**
+     * Icon-button size and width. Inside a button group or split button, the container's size
+     * applies instead, keeping the width.
+     *
+     * @defaultValue `"md"`
+     */
+    size?: IconButtonSize | undefined;
+    /**
+     * Round or square resting shape. Inside a button group, the group's shape applies instead.
+     *
+     * @defaultValue `"round"`
+     */
+    shape?: "round" | "square" | undefined;
+    /**
+     * Icon font ligature name. When omitted, nested content is used as the icon.
+     */
+    name?: string | undefined;
+};
+/**
+ * Toggle icon-button properties.
+ */
+export type IconToggleButtonProps = IconButtonProps;
+/**
+ * Material 3 icon button.
+ *
+ * Icon buttons are native buttons displaying a single icon, named by `name` or supplied as nested
+ * content. Name an icon button with `attr:aria-label`. They come in five sizes, each with narrow,
+ * default, and wide widths, keep a 48px minimum target, and morph their corners while pressed.
+ *
+ * # Design
+ *
+ * The [cw-Button](./button.yaml) attribute sizes the button and the [cw-Action](./action.yaml)
+ * attribute colors it; each variant is a `cw-Action` theme.
+ *
+ * # Styles
+ *
+ * The button applies `cw-IconButton-disabled` while disabled and the
+ * `cw-IconButton-{hover,focus,press}` interaction classes.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const IconButton: InteractableComponent<IconButtonProps>;
+/**
+ * Material 3 icon toggle button.
+ *
+ * Icon toggle buttons are icon buttons with a selected state, exposed through `aria-pressed`, with
+ * the same controlled and uncontrolled contract as {@link ./button#ToggleButton}. A round toggle
+ * becomes square when selected and a square toggle round; colors follow the unselected and selected
+ * roles of its variant. The toggle applies `cw-IconButton-toggle`, and `cw-IconButton-checked`
+ * while selected.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare function IconToggleButton(props: InteractableProps<IconToggleButtonProps>): JSX.Element;

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

@@ -0,0 +1,24 @@
+/**
+ * Material 3 action controls.
+ *
+ * Action controls are rendered as native buttons where activation semantics matter, and common
+ * buttons with an `href` as native links, since an action which navigates must be a link. They use
+ * the shared interactable controller for focus, hover, press, ripple, disabled, and toggle state
+ * handling, while keeping form and keyboard behavior provided by the browser.
+ *
+ * @packageDocumentation
+ */
+export type { ActionButtonController, ActionButtonElementProps, ActionButtonSize, ActionButtonVariant, ActionChangeHandler, ActionLinkProps, ActionToggleProps, BaseActionButtonProps } from "./base";
+export type { ButtonProps, ToggleButtonProps, ToggleButtonVariant } from "./button";
+export type { IconButtonProps, IconButtonSize, IconButtonVariant, IconToggleButtonProps } from "./icon-button";
+export type { FABProps, FABSize, FABVariant } from "./fab";
+export type { ButtonGroupAction, ButtonGroupChangeHandler, ButtonGroupItem, ButtonGroupOrientation, ButtonGroupProps, ButtonGroupValue, ButtonGroupVariant } from "./group";
+export type { SplitButtonProps } from "./split-button";
+export type { FABMenuItemProps, FABMenuProps, FABMenuTriggerFactory, FABMenuTriggerProps } from "./fab-menu";
+export type { FABMenuTriggerContextValue } from "./fab-menu-context";
+export { Button, ToggleButton } from "./button";
+export { IconButton, IconToggleButton } from "./icon-button";
+export { FAB } from "./fab";
+export { ButtonGroup } from "./group";
+export { SplitButton } from "./split-button";
+export { FABMenu, FABMenuItem, FABMenuTrigger } from "./fab-menu";

package/target/tsc/action/split-button.d.ts

@@ -0,0 +1,78 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps } from "..";
+import type { ActionButtonSize } from "./base";
+import type { ToggleButtonVariant } from "./button";
+import "./action.css";
+/**
+ * Split-button properties.
+ */
+export type SplitButtonProps = DomProps<HTMLDivElement, JSX.HTMLAttributes<HTMLDivElement>> & {
+    /**
+     * Size of both actions, which overrides their own sizes.
+     *
+     * @defaultValue `"sm"`
+     */
+    size?: ActionButtonSize | undefined;
+    /**
+     * Leading action, normally a {@link ./button#Button}. When omitted, the first child is used.
+     */
+    primary?: JSX.Element;
+    /**
+     * Trailing action, normally an {@link ./icon-button#IconButton} opening a menu. When omitted,
+     * the second child is used.
+     */
+    secondary?: JSX.Element;
+    /**
+     * Items of the menu opened by the trailing action, in place of
+     * {@link SplitButtonProps.secondary}.
+     *
+     * The split button then renders the trailing action: a button with an arrow icon opening a
+     * {@link ../surface/menu#Menu} of these items, exposed as its trigger with
+     * `aria-haspopup="menu"`, `aria-controls`, and an `aria-expanded` state kept in sync with the
+     * menu, from server rendering on. The presence of this property is read once at construction.
+     */
+    menu?: JSX.Element;
+    /**
+     * Accessible name of the trailing action rendered for {@link SplitButtonProps.menu}, and of
+     * its menu.
+     *
+     * @defaultValue `"More options"`
+     */
+    menuLabel?: string | undefined;
+    /**
+     * Variant of the trailing action rendered for {@link SplitButtonProps.menu}, which should be
+     * the variant of the leading action.
+     *
+     * @defaultValue `"filled"`
+     */
+    variant?: ToggleButtonVariant | undefined;
+};
+/**
+ * Material 3 split button.
+ *
+ * A split button pairs a leading action with a trailing action, normally opening a menu of related
+ * actions: supply the menu items as {@link SplitButtonProps.menu} for the split button to render
+ * the trailing action and its menu, or compose the trailing action yourself, for example as the
+ * trigger of a {@link ../surface/menu#Menu}. Both actions take the split button's size. Their outer
+ * corners are fully round; their inner corners morph while hovered or pressed, and the trailing
+ * action becomes fully round, with its icon turned over, while selected or while its menu is open
+ * (`aria-expanded="true"`). The content of the trailing action is centered optically between its
+ * corners (`horizontalCenterOptically`).
+ *
+ * # Design
+ *
+ * The [cw-SplitButton](./split-button.yaml) attribute defines the spacing, paddings, trailing icon
+ * size, and inner corners; the actions are sized by their `cw-Button` size theme.
+ *
+ * # Elements
+ *
+ * | Class                      | Element                     |
+ * | -------------------------- | --------------------------- |
+ * | `cw-SplitButton`           | root, with the `group` role |
+ * | `cw-SplitButton-primary`   | leading action slot         |
+ * | `cw-SplitButton-secondary` | trailing action slot        |
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const SplitButton: DomComponent<SplitButtonProps>;

package/target/tsc/color/contrast.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Determine contrast ratio of two tones.
+ *
+ * Tones are clamped to `[0, 100]`.
+ *
+ * @param tone1 - tone
+ * @param tone2 - other tone
+ * @returns contrast ratio, in `[1, 21]`
+ */
+export declare function ratioOfTones(tone1: number, tone2: number): number;
+/**
+ * Determine the tone lighter than a tone by a contrast ratio.
+ *
+ * @param tone - tone, in `[0, 100]`
+ * @param ratio - contrast ratio
+ * @returns lighter tone, in `[0, 100]`, or `-1` if no such tone exists
+ */
+export declare function lighterToneOf(tone: number, ratio: number): number;
+/**
+ * Determine the tone darker than a tone by a contrast ratio.
+ *
+ * @param tone - tone, in `[0, 100]`
+ * @param ratio - contrast ratio
+ * @returns darker tone, in `[0, 100]`, or `-1` if no such tone exists
+ */
+export declare function darkerToneOf(tone: number, ratio: number): number;
+/**
+ * Test whether content on a background of a tone is preferably lighter than the background.
+ *
+ * @param tone - tone of background
+ * @returns `true` if, and only if, `tone` rounds to less than `60`
+ */
+export declare function prefersLighterTone(tone: number): boolean;
+/**
+ * Determine the tone of content on a background, reaching a contrast ratio.
+ *
+ * This determines the lighter and darker tones reaching `ratio` against `bg`, white and black
+ * if no such tone exists, respectively, and selects one of them. Lighter content is preferred on
+ * a {@link prefersLighterTone | dark} background, and darker content otherwise. The preferred tone
+ * is selected if it reaches `ratio` or if it contrasts at least as much as the other tone. For a
+ * dark background, the lighter tone is additionally selected if neither tone reaches `ratio`
+ * and their contrast ratios differ by less than `0.1`.
+ *
+ * @param bg - tone of background
+ * @param ratio - contrast ratio to reach
+ * @returns tone of content, in `[0, 100]`
+ */
+export declare function foregroundToneOf(bg: number, ratio: number): number;

package/target/tsc/color/dynamic.d.ts

@@ -0,0 +1,203 @@
+import type { Hct } from "./hct";
+import type { ColorSchemeRole, ColorSchemeSpecVersion, ColorSchemeVariant } from "./scheme";
+/**
+ * Dynamic color scheme.
+ *
+ * A scheme assigns a color to each {@link ColorSchemeRole | role}. A role takes the color of its
+ * palette at a tone which is resolved from the definition of the role. Definitions and resolved
+ * tones are computed once, when first needed.
+ *
+ * @see {@link newDynamicScheme}
+ * @see {@link argbOfRole}
+ */
+export interface DynamicScheme {
+    /**
+     * Specification revision the scheme follows.
+     */
+    readonly specVersion: ColorSchemeSpecVersion;
+    /**
+     * Dynamic color style.
+     */
+    readonly variant: ColorSchemeVariant;
+    /**
+     * Scheme is a dark scheme.
+     */
+    readonly isDark: boolean;
+    /**
+     * Contrast level, in `[-1, 1]`.
+     */
+    readonly contrastLevel: number;
+    /**
+     * Source color.
+     */
+    readonly source: Hct;
+    /**
+     * Palettes of roles.
+     */
+    readonly palettes: Palettes;
+    /**
+     * Definitions of roles, keyed by role.
+     */
+    readonly definitions: Map<ColorSchemeRole, Definition>;
+    /**
+     * Resolved tones of roles, keyed by role.
+     */
+    readonly tones: Map<ColorSchemeRole, number>;
+    /**
+     * Light scheme of standard contrast level with the palettes of this scheme, if created.
+     *
+     * @see {@link fixedSchemeOf}
+     */
+    fixed: DynamicScheme | undefined;
+}
+/**
+ * Tonal palette of a hue and chroma.
+ *
+ * @see {@link ./palette#argbOfPalette}
+ */
+interface Palette {
+    /**
+     * Hue of palette, in degrees.
+     */
+    readonly hue: number;
+    /**
+     * Chroma of palette.
+     */
+    readonly chroma: number;
+    /**
+     * {@link searchTone | Searched} tone of palette, starting at tone `100`, if searched.
+     */
+    lightTone: number | undefined;
+    /**
+     * {@link searchTone | Searched} tone of palette, starting at tone `0`, if searched.
+     */
+    darkTone: number | undefined;
+}
+/**
+ * Palettes of a scheme.
+ */
+interface Palettes {
+    /**
+     * Primary accent palette.
+     */
+    readonly primary: Palette;
+    /**
+     * Secondary accent palette.
+     */
+    readonly secondary: Palette;
+    /**
+     * Tertiary accent palette.
+     */
+    readonly tertiary: Palette;
+    /**
+     * Error palette.
+     */
+    readonly error: Palette;
+    /**
+     * Neutral palette, of surfaces and their content.
+     */
+    readonly neutral: Palette;
+    /**
+     * Neutral variant palette, of lower emphasis content and outlines, if used by the scheme.
+     *
+     * Only the `"2021"` specification revision uses this palette.
+     */
+    readonly neutralVariant?: Palette | undefined;
+}
+/**
+ * Contrast ratios of a role against its background, at each contrast level.
+ *
+ * The ratios at contrast levels `-1`, `0`, `0.5`, and `1` are given; between, the ratio is
+ * interpolated linearly.
+ *
+ * @see {@link valueOfCurve}
+ */
+type Curve = readonly [low: number, normal: number, medium: number, high: number];
+/**
+ * Pair of accent roles whose tones keep a distance from each other.
+ *
+ * Only the `"2021"` specification revision uses pairs.
+ *
+ * @see {@link resolvePairTone}
+ */
+interface Pair {
+    /**
+     * Role of pair whose tone is nearer to the tone of the background.
+     */
+    readonly nearer: ColorSchemeRole;
+    /**
+     * Role of pair whose tone is farther from the tone of the background.
+     */
+    readonly farther: ColorSchemeRole;
+    /**
+     * Tones of both roles leave tones in `[50, 60)` together.
+     */
+    readonly together: boolean;
+}
+/**
+ * Definition of a role.
+ *
+ * The tone of a role is adjusted to reach the contrast ratio of its curve against its background
+ * role, if it has both. The tones of the roles of a {@link Pair | pair} are adjusted together.
+ *
+ * @see {@link resolveTone}
+ */
+interface Definition {
+    /**
+     * Palette of role.
+     */
+    readonly palette: Palette;
+    /**
+     * Factor of the chroma of the palette in the color of role.
+     *
+     * @defaultValue `1`
+     */
+    readonly chromaFactor?: number | undefined;
+    /**
+     * Tone of role, before adjustment.
+     */
+    readonly tone: number;
+    /**
+     * Role whose color is the background of the color of role, if any.
+     */
+    readonly background?: ColorSchemeRole | undefined;
+    /**
+     * Role whose color is another background of the color of role, if any.
+     */
+    readonly secondBackground?: ColorSchemeRole | undefined;
+    /**
+     * Contrast ratios against background, if any.
+     */
+    readonly curve?: Curve | undefined;
+    /**
+     * Pair of role, if any.
+     */
+    readonly pair?: Pair | undefined;
+    /**
+     * Role is a background, whose adjusted tone avoids tones in `(49, 65)`.
+     */
+    readonly isBackground?: boolean | undefined;
+}
+/**
+ * Construct a new dynamic color scheme.
+ *
+ * The `"2025"` specification revision is available for the `tonalSpot`, `neutral`, `vibrant`,
+ * and `expressive` variants; other variants use the `"2021"` revision instead.
+ *
+ * @param sourceColorArgb - ARGB source color, whose alpha is ignored
+ * @param variant - dynamic color style
+ * @param isDark - `true` if, and only if, the scheme is a dark scheme
+ * @param contrastLevel - contrast level, in `[-1, 1]`
+ * @param specVersion - requested specification revision
+ * @returns new scheme
+ */
+export declare function newDynamicScheme(sourceColorArgb: number, variant: ColorSchemeVariant, isDark: boolean, contrastLevel: number, specVersion: ColorSchemeSpecVersion): DynamicScheme;
+/**
+ * Determine the color of a role of a scheme.
+ *
+ * @param scheme - scheme of role
+ * @param role - role to determine color of
+ * @returns opaque, unsigned ARGB color of `role`
+ */
+export declare function argbOfRole(scheme: DynamicScheme, role: ColorSchemeRole): number;
+export {};