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

package/target/tsc/container/card.d.ts

@@ -0,0 +1,110 @@
+import type { JSX } from "solid-js";
+import type { DomProps } from "..";
+import type { InteractableComponent } from "../state";
+import "./elevation-shadow.css";
+import "./card.css";
+/**
+ * {@link Card} component properties.
+ */
+export type CardProps = DomProps<HTMLDivElement, Omit<JSX.HTMLElementTags["div"], "aria-disabled" | "role" | "tabindex">> & {
+    /**
+     * Card is disabled.
+     *
+     * When `true`, interaction, if any, with the card is disabled.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean;
+    /**
+     * Card represents a single button action.
+     *
+     * Enable this only when the entire card is one action and its children contain no links,
+     * buttons, or other interactive controls. Cards containing secondary actions should leave this
+     * disabled and give those actions their own native semantics.
+     *
+     * When `true`, the card is exposed as an ARIA button, is keyboard activatable, and is also
+     * {@link CardProps.pressable | pressable}.
+     *
+     * @defaultValue `false`
+     */
+    button?: boolean;
+    /**
+     * Card can be dragged.
+     *
+     * When `true`, the {@link ../state#DragState | drag} state is {@link
+     * ../state#InteractableController.setEnabledInteractionStates | enabled} for the rendered
+     * card, which raises the card to its dragged elevation and shows the dragged state layer while
+     * the primary pointer drags it. The card does not move itself; the application moves it, for
+     * example while the drag state is entered, as reported by `onInteractionStateEntered` and
+     * `onInteractionStateExited`. Touch drags compete with native scrolling, unless the application
+     * restricts `touch-action` of the card.
+     *
+     * @defaultValue `false`
+     */
+    draggable?: boolean;
+    /**
+     * Card has pressable interaction styling.
+     *
+     * When `true`, the {@link ../state#FocusState | focus}, {@link ../state#HoverState |
+     * hover}, and {@link ../state#PressState | press} states are {@link
+     * ../state#InteractableController.setEnabledInteractionStates | enabled} for the rendered
+     * card. This property does not assign an accessibility role or make the card a keyboard action;
+     * use {@link CardProps.button | `button`} for a card that represents one button action.
+     *
+     * @defaultValue `false`
+     */
+    pressable?: boolean;
+    /**
+     * Sequential focus index.
+     */
+    tabIndex?: number;
+    /**
+     * Card design theme.
+     *
+     * This controls the design theme applied to the rendered card. The standard `"elevated"`,
+     * `"filled"`, and `"outlined"` themes apply `elevated`, `filled`, and `outlined` themes,
+     * respectively.
+     *
+     * @defaultValue `"filled"`
+     */
+    design?: "elevated" | "filled" | "outlined";
+};
+/**
+ * Card container component.
+ *
+ * Cards contain content, and optional actions, for a single subject. Cards support standard design
+ * themes controlled using {@link CardProps.design | `props.design`}.
+ *
+ * # States
+ *
+ * Cards are optionally interactable, depending on whether {@link CardProps.pressable |
+ * `props.pressable`} is `true` or not. When `props.pressable` is `true`, the card may be
+ * interacted with in terms of the {@link FocusState | focus}, {@link HoverState | hover}, and
+ * {@link PressState | press} states. A card representing a single button action should instead
+ * set {@link CardProps.button | `props.button`}; cards containing links, buttons, or other
+ * actions must not use button semantics on their container. Independently, a card the
+ * application can drag sets {@link CardProps.draggable | `props.draggable`} to enter the {@link
+ * DragState | drag} state while dragged.
+ *
+ * Additionally, cards can enter into a disabled state, controlled through {@link
+ * CardProps.disabled | `props.disabled`}. When `props.disabled` is `true`, the disabled design
+ * styling is applied, along with `pointer-events` and `user-select` being assigned to `none`.
+ *
+ * # Design
+ *
+ * Card design is controlled through the [`cw-Card`](./card.yaml) component design attribute. The
+ * design theme a card is rendered with can be controlled using {@link CardProps.design |
+ * `props.design`}. Content inherits the content color paired with the container color, which is
+ * dimmed while the card is disabled.
+ *
+ * When a card is {@link CardProps.disabled | disabled}, the `cw-Card-disabled` is added to the
+ * card element. Likewise, when non-disabled {@link CardProps.pressable | pressable} or {@link
+ * CardProps.draggable | draggable} cards are interacted with, `cw-Card-<state>` class is added
+ * to the card element, where `<state>` is the name of the interaction state the card entered
+ * into. Note that interaction state classes are added and removed based on their precedence, see
+ * {@link InteractionState} for more information.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const Card: InteractableComponent<CardProps>;

package/target/tsc/container/elevation-shadow.css.d.ts

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

package/target/tsc/container/elevation-shadow.d.ts

@@ -0,0 +1,23 @@
+import "./elevation-shadow.css";
+/**
+ * Name of CSS class which applies elevation styling, in terms of a shadow.
+ *
+ * When applied to an element, the `box-shadow` property is used to apply an elevation shadow,
+ * based on configured elevation shadow properties. The element is expected to define the following
+ * CSS properties.
+ *
+ * | Property                     | Description                                                   |
+ * | ---------------------------- | ------------------------------------------------------------- |
+ * | `--cw-elevationShadow-color` | A `<color>` value to use for drawing elevation shadow. If not specified, defaults to `--cw-Color-shadow`. |
+ * | `--cw-elevationShadow-level` | A `<number>` value between `0` (no elevation) and `5` (highest elevation). When `0`, no elevation shadow is drawn. Any other positive value will draw an elevation shadow, where a value of `5` will draw the largest elevation shadow. If not specified, this defaults to `1`. |
+ *
+ * Levels are those of the [`cw-Elevation`](./elevation.yaml) design attribute; values between
+ * two levels draw an intermediate shadow, such that transitions between levels are continuous.
+ *
+ * The defaults have no specificity, so any rule assigning either property takes precedence over
+ * them, regardless of stylesheet order. These properties cannot be inherited by child elements.
+ * Both of these properties support transitions, as such, if either can change, and a motion is
+ * required, then they should be included within `transition-property`; otherwise, `box-shadow`
+ * itself could also be added to `transition-property`.
+ */
+export declare const ELEVATION_SHADOW_CSS_CLASS: string;

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

@@ -0,0 +1,44 @@
+/**
+ * Container component definitions.
+ *
+ * This module defines components for containing other components, as well as components and
+ * styles for visual separation between components.
+ *
+ * # Elevation
+ *
+ * Elevation shadow around containers, using elevation levels defined by the
+ * [`cw-Elevation`](./elevation.yaml) system design attribute, can be implemented for a container
+ * by applying the elevation shadow {@link ./elevation-shadow#ELEVATION_SHADOW_CSS_CLASS | CSS
+ * class} to the respective container.
+ *
+ * # Cards
+ *
+ * [Card](https://m3.material.io/components/cards/overview) containers are used to contain content,
+ * with optional actions, for a single subject. Material 3 defines three card themes, `elevated`,
+ * `filled`, and `outlined`, which are implemented by {@link ./card#Card} through {@link
+ * ./card#CardProps.design | `props.design`}.
+ *
+ * All card designs support elevation, with only the elevated design having a resting elevation.
+ * Additionally, cards are {@link ../state#InteractableComponent | interactable}, with no
+ * interaction {@link ../state#InteractionState | state} enabled by default. See {@link
+ * ./card#Card} for more information.
+ *
+ * ```tsx
+ * import type { JSX } from "solid-js";
+ *
+ * import { Card } from "@pg-labs-incubator/cobweb/container";
+ *
+ * export default function(): JSX.Element {
+ *     return <>
+ *         <Card design="elevated">Elevated Card</Card>
+ *         <Card design="filled">Filled Card</Card>
+ *         <Card design="outlined">Outlined Card</Card>
+ *     </>;
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { CardProps } from "./card";
+export { Card } from "./card";
+export { ELEVATION_SHADOW_CSS_CLASS } from "./elevation-shadow";

package/target/tsc/dom/client.d.ts

@@ -0,0 +1,387 @@
+import type { Accessor, JSX } from "solid-js";
+import type { DomProps, FunctionElement, StyleElement } from "./types";
+declare module "solid-js/web" {
+    function assign(node: Element, props: object, isSVG: boolean, skipChildren: boolean, prevProps: object, skipRef: boolean): void;
+}
+/**
+ * DOM component properties accepted by a {@link ..#defineDomComponent | defined} component.
+ *
+ * @typeParam P - base component properties
+ */
+export type ClientDomProps<P extends DomProps> = P & {
+    /**
+     * Reference to client-side DOM controller.
+     *
+     * When the component is constructed in a client environment, this is invoked with the
+     * constructed controller, *before* the component is rendered. This is **not** invoked during
+     * server rendering.
+     *
+     * @remarks
+     * This is **not** reactive.
+     */
+    readonly controllerRef?: (cont: DomController<P>) => void;
+};
+/**
+ * DOM element rendering component.
+ *
+ * DOM components are guaranteed to render a DOM element, possibly reactively. Components which
+ * support transitions, the component may return an array of DOM elements, of which the last
+ * element is the element which will persist after the transition.
+ *
+ * These components render two types of elements, a style and function element. The element
+ * returned is *always* the style element, while {@link DomProps.ref | `props.ref`} is updated
+ * with the function element. Style element is responsible for applying component style. The
+ * function element, however, *may* be the style element *or* an element within the sub-tree of
+ * the style element. Function element provide user-interface functions the component provides.
+ * For example, a component providing user input functions would likely have an `input` element
+ * as its function element and may have an outer `div` container, serving as the style element.
+ *
+ * This distinction is important in order to determine which properties are applied to which
+ * element. See {@link DomProps} for more information.
+ *
+ * @typeParam P - component {@link DomProps | properties} type
+ * @param props - component properties
+ * @returns style element or style element accessor
+ * @see {@link DomProps}
+ * @see {@link StyleElement}
+ * @see {@link ./index#defineDomComponent}
+ */
+export type DomComponent<P extends DomProps> = (props: ClientDomProps<P>) => JSX.Element;
+/**
+ * DOM component {@link DomController | controller} options.
+ *
+ * These optional options are used to construct a controller instance.
+ */
+export interface DomControllerOptions {
+    /**
+     * Function element is static.
+     *
+     * @defaultValue `true` if, and only if, {@link
+     * DomControllerOptions.styleElementIsFunction | `styleElementIsFunction`} is `true` *and*
+     * {@link DomController.render} does not return an accessor; otherwise, `false`
+     * @see {@link DomController.isFunctionElementStatic}
+     */
+    functionElementIsStatic?: boolean;
+    /**
+     * Component has no distinct function element.
+     *
+     * When `true`, the style element returned by {@link DomController.render} is used as
+     * the function element.
+     *
+     * @defaultValue `false`
+     * @see {@link DomController.isFunctionElementStyle}
+     */
+    styleElementIsFunction?: boolean;
+}
+/**
+ * {@link DomController.readProps | Read} DOM properties.
+ *
+ * This evaluates to a mapping of read DOM properties `K`. Each property `Ki` in `K` has two
+ * additional properties, `${Ki}Changed` and `${Ki}Previous` for whether the property value has
+ * changed since its last observed value and its last observed value, respectively.
+ *
+ * @typeParam P - component properties type
+ * @typeParam K - read properties type
+ * @see {@link DomController.readProps}
+ */
+export type ReadProps<P extends DomProps, K extends (keyof P)[]> = Pick<P, K[number]> & {
+    [C in K[number] as C extends string ? `${C}Changed` : never]: boolean;
+} & {
+    [C in K[number] as C extends string ? `${C}Previous` : never]: P[C] | undefined;
+};
+/**
+ * Client-side controller of a DOM {@link DomComponent | component}.
+ *
+ * Instances of this control the state of a component instance, with respect to the {@link
+ * DomProps | properties} the component is constructed with. Based on properties, the state of the
+ * function and style elements is updated. The base implementation of this controls all {@link
+ * DomEventHandlerProps | event handler}, {@link ./types#DomAttributes | attributes}, and {@link
+ * ./types#BaseDomProps | base} component properties, implementations are expected to control their
+ * local component properties, if any.
+ *
+ * Implementations are required to implement the {@link DomController.render} method. This method
+ * must return a style element or style element accessor. Additionally, the function reference
+ * the method is invoked with, if any, must be used to update the function element reference of
+ * the controller.
+ *
+ * A controller maintains a reference to the {@link DomController.styleElement | style} and {@link
+ * DomController.functionElement | function} elements of the component. As the style and function
+ * elements are rendered, including when the elements change, the respective elements are updated
+ * based on the controller defined state.
+ *
+ * Implementations must override {@link DomController.applyComponentProps} to control their local
+ * component properties. This method is invoked in a tracking context, as such, when properties,
+ * accessed during an invocation, change, the method will be invoked again. Properties must be
+ * accessed using {@link DomController.readProp}. The `readProp` method tracks the last observed
+ * value, and allows the caller to determine if the value has changed from its last observed value.
+ *
+ * Based on property changes, implementations can apply {@link DomController.setAttribute |
+ * attributes}, CSS {@link DomController.setClass | classes}, and inline CSS {@link
+ * DomController.setStyle | style}. When style or function elements change, if at all, the applied
+ * attributes, CSS classes, and inline CSS style are applied to the new element.
+ *
+ * @typeParam P - component properties type
+ * @see {@link ./index#defineDomComponent}
+ */
+export declare abstract class DomController<P extends DomProps = DomProps> {
+    #private;
+    /**
+     * Underlying component properties.
+     *
+     * Avoid accessing this directly, instead use {@link DomController.readProp | `readProp()`}.
+     */
+    readonly props: P;
+    /**
+     * Construct a new DOM controller.
+     *
+     * @param props - owning component properties
+     * @param opts - controller options
+     */
+    constructor(props: P, opts?: DomControllerOptions);
+    /**
+     * Release controller-owned resources when the component owner is disposed.
+     *
+     * Subclasses which retain document-level resources should override this method and invoke
+     * `super.onControllerCleanup()` after releasing their own resources.
+     */
+    protected onControllerCleanup(): void;
+    /**
+     * Read value of a property.
+     *
+     * This reads the last observed and current values of a property, identified by `key`.
+     * If the last observed value is not strictly equal to the current value, then this
+     * returns a tuple of current value, `true`, and last observed value, respectively;
+     * otherwise, this returns a tuple of the last observed value and `false`, respectively.
+     * When tracked in a tracking context, the property access for `key` will result in a
+     * dependency edge between the access and the property.
+     *
+     * Note, however, when `onlyObserved` is `true` this does *not* access the property at
+     * all, instead, this returns the last observed value, if any, followed by `false`,
+     * respectively. Thus, when `onlyObserved` is `true`, an invocation of this will *not*
+     * result in a dependency edge when invoked within a tracking context.
+     *
+     * @typeParam K - property key type
+     * @param key - property key to read value of
+     * @param onlyObserved - `true` if, and only if, only last observed value should be
+     * returned
+     * @returns tuple of current value, `true`, and last observed value, or, tuple of
+     * last observed value and `false`
+     */
+    readProp<K extends keyof P>(key: K, onlyObserved?: boolean): [
+        P[K],
+        false
+    ] | [P[K], true, P[K] | undefined];
+    /**
+     * Read zero or more property values.
+     *
+     * This {@link DomController.readProp | reads} each property specified in `props`, and
+     * returns an object containing, for each property `Ki`:
+     *
+     * 1. `Ki` is set to the current or last observed value of the `Ki` if the value has or
+     *    has not changed, respectively.
+     *
+     * 2. `${Ki}Changed` is set to `true` or `false` if the property value has changed.
+     *
+     * 3. `${Ki}Previous` is set to the last observed value if, and only if, the value has
+     *    changed.
+     *
+     * @typeParam K - property keys type
+     * @param props - property keys to read
+     * @param onlyObserved - `true` if, and only if, only last observed value should be
+     * returned
+     * @returns read properties
+     */
+    readProps<K extends (keyof P)[]>(props: K, onlyObserved?: boolean): ReadProps<P, K>;
+    /**
+     * Consume possibly static property values.
+     *
+     * This {@link ../util#consumeProps | consumes} properties underlying this controller. See
+     * {@link ../util#consumeProps} for more information.
+     *
+     * @typeParam KO - optional property keys type
+     * @typeParam KR - required property keys type
+     * @param optKeys - optional keys to consume
+     * @param reqKeys - required keys to consume
+     * @returns resulting object with consumed property values
+     */
+    consumeProps<KO extends (keyof P)[], KR extends (keyof P)[]>(optKeys: KO, reqKeys?: KR): (Partial<Pick<P, KO[number]>> & Pick<P, KR[number]>);
+    /**
+     * Component style element.
+     *
+     * The element returned, if any, is the element to which the component applies its
+     * styling.
+     *
+     * @returns rendered style element or `null` if an element is not rendered
+     */
+    get styleElement(): StyleElement | null;
+    /**
+     * Component function element.
+     *
+     * The element returned, if any, is the element which applies the user-facing function of
+     * the component.
+     *
+     * @returns rendered function element or `null` if an element is not rendered
+     */
+    get functionElement(): FunctionElement<P> | null;
+    /**
+     * {@link DomController.functionElement | Function} element cannot change once rendered.
+     *
+     * @returns `true` if, and only if, function element cannot be modified after initial
+     * render
+     * @see {@link DomControllerOptions.functionElementIsStatic}
+     */
+    isFunctionElementStatic(): boolean;
+    /**
+     * {@link DomController.styleElement | Style} element cannot change once rendered.
+     *
+     * This returns `true` *only* after component is {@link DomController.render | rendered}
+     * *and* the rendered style element is reactive.
+     *
+     * @returns `true` if, and only if, style element cannot be modified after initial render
+     */
+    isStyleElementStatic(): boolean;
+    /**
+     * {@link DomController.functionElement | Function} element and {@link
+     * DomController.styleElement | style} element are the same element.
+     *
+     * If this returns `true`, then it's guaranteed that {@link DomController.functionElement |
+     * `functionElement`} and {@link DomController.styleElement | `styleElement`} return the
+     * same value.
+     *
+     * @returns `true` if, and only if, component has no distinct function element and the
+     * style element provides the component function
+     * @see {@link DomControllerOptions.styleElementIsFunction}
+     */
+    isFunctionElementStyle(): boolean;
+    /**
+     * Assign style to {@link DomController.styleElement | style} element.
+     *
+     * If `value` is `undefined`, then the style declaration for `name` is removed from the
+     * style element; otherwise, `value` is set for the style property `name`. When a style
+     * element has not yet rendered, the resulting style declaration is noted and applied
+     * when a style element is rendered.
+     *
+     * @param name - name of style property to assign
+     * @param value - value to assign to or `undefined` to remove assignment
+     */
+    setStyle(name: string, value?: number | string | undefined): void;
+    /**
+     * Add, replace, or remove CSS class applied to {@link DomController.styleElement | style}
+     * element.
+     *
+     * If `name` is `undefined`, then the previous class set for `key` is removed from the
+     * style element, if any. If `key` was previously mapped to a class, the previously applied
+     * class is replaced with `name`; otherwise, `name` is applied to the style element and set
+     * as the class applied for `key`. `name` may also list several CSS classes, separated by
+     * whitespace, which are then added, replaced, or removed together.
+     *
+     * @param key - styling key to add, replace, or remove CSS class for
+     * @param name - name of CSS class, or whitespace-separated names of CSS classes, to add or
+     * replace, or, an empty string or `undefined` to remove class
+     * @throws {@link Error} `key` is equal to `name`
+     */
+    setClass(key: string, name?: string | undefined): void;
+    /**
+     * Add or remove CSS class applied to {@link DomController.styleElement | style} element.
+     *
+     * This adds or removes the CSS class `name` to or from the style element based on whether
+     * `add` is `true` or `false`, respectively. `name` may also list several CSS classes,
+     * separated by whitespace, which are then added or removed together.
+     *
+     * @param name - name of CSS class, or whitespace-separated names of CSS classes, to add or
+     * remove
+     * @param add - `true` or `false` if class should be added or removed, respectively
+     */
+    setClass(name: string, add: boolean): void;
+    /**
+     * Assign attribute to {@link DomController.functionElement | function} element.
+     *
+     * The attribute is assigned to the value {@link ../util#attributeValueOf | resolved} for
+     * `value`. If `value` is a `boolean`, then a value of `true` assigns the attribute `name` to
+     * an empty string; otherwise, a `false` value removes the attribute assignment. ARIA and
+     * enumerated attributes, such as `aria-expanded` or `draggable`, are an exception, and are
+     * instead assigned the keyword of the respective state, such as `"true"` or `"false"`.
+     * Additionally, an `undefined` or `null` value also removes the attribute assignment. All
+     * other values are converted to a `string` value, which is then assigned to the function
+     * element.
+     *
+     * If a function element is not yet present, then the attribute assignment is deferred
+     * until a function element is rendered, while an `undefined` or `null` value cancels the
+     * deferred assignment, if any.
+     *
+     * @param name - name of attribute to assign
+     * @param value - value to assign to
+     * @see {@link ../util#attributeValueOf}
+     */
+    setAttribute(name: string, value?: boolean | number | string | undefined): void;
+    /**
+     * Apply component updates from properties.
+     *
+     * This is invoked in a reactive tracking context to apply updates from non-DOM component
+     * properties. Implementations may override this to apply updates from properties not
+     * directly defined by {@link DomProps}. Component properties should be accessed using
+     * {@link DomController.readProp}.
+     *
+     * @remarks
+     * It is guaranteed that the {@link DomController.styleElement | style} element will be
+     * non-`null` when this is *first* invoked.
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Render DOM elements.
+     *
+     * This is invoked, at most *once*, when the component, which owns this controller, is
+     * first initialized. This must render the style and function elements of the component.
+     * This should always render DOM elements without reactive attributes. Instead, reactive
+     * attributes should be controlled through this controller.
+     *
+     * The style element must be returned, while the function element must be specified using
+     * `funcRef`. This may return a DOM element as the style element, or a reactive {@link
+     * Accessor | accessor} which returns the style DOM element. When a reactive accessor is
+     * returned, it must return the same DOM element for every invocation, until the
+     * underlying reactive state changes.
+     *
+     * If a DOM element is returned, it is assumed the style element is static and cannot be
+     * changed. This results in some additional optimizations. If this controller was
+     * configured for a {@link DomControllerOptions.functionElementIsStatic | static} function
+     * element, then `funcRef`, if specified, may be invoked at most once.
+     *
+     * The `funcRef` function is guaranteed to be defined when this controller was *not*
+     * configured with an {@link DomControllerOptions.styleElementIsFunction | function
+     * identity}. If the controller was configured with a function identity, then the style
+     * element returned is used as the function element.
+     *
+     * @param children - nested children
+     * @param funcRef - function to invoke with function element
+     * @returns style element or style element accessor
+     */
+    protected abstract render(children: JSX.Element, funcRef?: (elem: FunctionElement<P>) => void): Accessor<JSX.Element> | JSX.Element;
+    /**
+     * Handle style element change.
+     *
+     * This is invoked whenever the style element changes, *before* the {@link
+     * DomController.styleElement | style} element is updated. The new style element, if any,
+     * is supplied in `curr`.
+     *
+     * @param curr - new style element, if any
+     */
+    protected onStyleElementChanged(curr: StyleElement | null): void;
+    /**
+     * Handle function element change.
+     *
+     * This is invoked whenever the function element changes, *before* the {@link
+     * DomController.functionElement | function} element is updated. The new function element,
+     * if any, is supplied in `curr`.
+     *
+     * @param curr - new function element, if any
+     */
+    protected onFunctionElementChanged(curr: FunctionElement<P> | null): void;
+}
+/**
+ * Define a new client-side DOM {@link DomComponent | component}.
+ *
+ * @typeParam P - component properties type
+ * @param supp - controller constructor provider
+ * @returns resulting component
+ */
+export declare function defineClientDomComponent<P extends DomProps>(supp: (Controller: typeof DomController) => (new (props: P) => DomController<P>)): DomComponent<P>;

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

@@ -0,0 +1,93 @@
+/**
+ * DOM component definitions.
+ *
+ * @packageDocumentation
+ */
+export type { BaseDomProps, DomAttributes, DomEventHandlerProps, DomProps, DomTag, FunctionElement, PickDomAttributes, StyleElement } from "./types";
+export type { ClientDomProps, DomComponent, DomController, DomControllerOptions, ReadProps } from "./client";
+export type { ElementDomProps, PickLocalDomProps, RenderServerDom } from "./server";
+import type { DomComponent, DomController } from "./client";
+import type { RenderServerDom } from "./server";
+import type { DomProps } from "./types";
+/**
+ * Define a new DOM {@link DomComponent | component} in terms of a render function and controller.
+ *
+ * This defines a new component which uses the render function, returned by `server`, or {@link
+ * DomController | controller}, returned by `client` for rendering DOM elements in a server or
+ * client -side environment, respectively. When invoked in a server or client -side environment,
+ * `server` or `client` is invoked **once** to return the respective render function or controller
+ * implementation, respectively.
+ *
+ * The server-side render function is expected to return a DOM element with {@link
+ * ./server#ElementDomProps | element} and {@link ./server#PickLocalDomProps | local} component
+ * properties it is invoked with, respectively. The element and local component properties are
+ * {@link solid-js#splitProps | split} from the properties the component is invoked with. The
+ * element returned must match, structurally, the element {@link DomController.render | rendered}
+ * by the client-side controller implementation, returned by `client`.
+ *
+ * The client-side controller implementation, returned by `client`, must accept component
+ * properties, returning a new controller implementation instance. The controller implementation
+ * must render structurally the same DOM as what the server-side render function renders, creating
+ * the elements in the same order, since hydration identifies each element by the order in which it
+ * is created. The server-side render function must therefore not read a slot property, such as
+ * `children`, before it creates the element the slot is nested within; see {@link RenderServerDom}.
+ * State of the component must be controlled using the controller. The controller need only track
+ * state with respect to its local properties. Properties defined directly by {@link DomProps} are
+ * managed automatically by the base controller.
+ *
+ * The component returned accepts a `controllerRef` parameter, which, when component is constructed
+ * within client environment, is invoked with the controller instance of the component.
+ *
+ * ```tsx
+ * import type { DomComponent, DomProps } from "@pg-labs-incubator/cobweb";
+ * import type { JSX } from "solid-js";
+ *
+ * import { defineDomComponent } from "@pg-labs-incubator/cobweb";
+ *
+ * export type MyProps = DomProps<HTMLSpanElement, JSX.HTMLElementTags["span"]> & {
+ *     size?: "large" | "medium" | "small";
+ * };
+ *
+ * export const MyComponent: DomComponent<MyProps> = defineDomComponent(
+ *     // Render on server-side:
+ *     () => (elemProps, localProps) => <span
+ *         {...elemProps}
+ *         classList={{
+ *             ...elemProps.classList,
+ *             [`MyComponent-size-${localProps.size ?? "small"}`]: true,
+ *             "MyComponent": true
+ *         }}
+ *     />,
+ *     // Render on client-side:
+ *     (Base) => class extends Base<MyProps> {
+ *         constructor(props: MyProps) {
+ *             super(props, {
+ *                 // Our style element is our function element; without this, we would need to
+ *                 // include the function reference.
+ *                 styleElementIsFunction: true
+ *             });
+ *         }
+ *
+ *         protected override applyComponentProps(): void {
+ *             // Invoked in a reactive context. When `size` changes, we'll get invoked again.
+ *             const [size, sizeChanged] = super.readProp("size");
+ *
+ *             if (sizeChanged) {
+ *                 // `size` changed, update the style
+ *                 super.setClass("size", `MyComponent-size-${size ?? "small"}`);
+ *             }
+ *         }
+ *
+ *         protected override render(children: JSX.Element): JSX.Element {
+ *             return <span class="MyComponent">{children}</span>;
+ *         }
+ *     }
+ * );
+ * ```
+ *
+ * @typeParam P - component properties type
+ * @param server - server-side DOM render function supplier
+ * @param client - client-side DOM controller implementation provider
+ * @returns resulting component
+ */
+export declare const defineDomComponent: <P extends DomProps>(server: () => RenderServerDom<P>, client: (Controller: typeof DomController) => (new (props: P) => DomController<P>)) => DomComponent<P>;