@swell/swell-ui 0.0.0-stage → 0.1.1

package/dist/types/runtime/config.d.ts

@@ -0,0 +1,25 @@
+import { type Config, type Theme } from "./tokens.generated.js";
+/** The kit's defaults of every global token, on the page root; under reduced motion, every duration this copy knows is zero. */
+export declare const defaultsSheet: CSSStyleSheet;
+/** The release whose configuration holds the page: this copy's, or the first copy's when the kit loaded twice. */
+export declare const version: string;
+/** The host's values and theme, on the page root after the defaults, and each area's on its `<swell-ui>`. */
+export declare const configSheet: CSSStyleSheet;
+/**
+ * Replaces the page's configuration, its theme included; with no configuration, restores the defaults. The configurations of areas stay.
+ * With `id`, replaces the configuration of that area instead: its tokens and theme apply inside every `<swell-ui config="id">`, and no configuration removes it.
+ */
+export declare const configure: (config?: Config | null, id?: string) => void;
+/** Chooses the light theme, the dark one, or the system setting, and keeps the rest of the configuration. */
+export declare const setTheme: (theme: Theme) => void;
+/** A copy of the page's applied configuration with the theme in effect; with `id`, a copy of that area's own configuration. */
+export declare const getConfig: (id?: string) => Config;
+/** The host's own variants, the palettes its configurations add to `color`. */
+export declare const hostVariants: () => readonly string[];
+/** Calls `listener` after every `configure`, the page's or an area's, and every `setTheme`; returns the function that unsubscribes it. */
+export declare const onChange: (listener: () => void) => () => void;
+/**
+ * The value of setting `name` on `node`: the host's, else the kit's default; `undefined` when the node has none.
+ * A setting the first copy doesn't know takes this copy's default.
+ */
+export declare function resolveSetting(node: string, name: string): string | undefined;

package/dist/types/runtime/css.d.ts

@@ -0,0 +1,12 @@
+/** CSS naming shared by the runtime and the token tool; this module imports nothing. */
+/** The CSS variable of token `name`: `button.color.background` → `--swell-button-color-background`. */
+export declare const cssVar: (name: string) => string;
+/** The roles of a variant's palette, such as `color.secondary.background`: it holds the first four and may leave out `shadow`. */
+export declare const VARIANT_ROLES: readonly ["background", "foreground", "border", "accent", "shadow"];
+export declare const REQUIRED_VARIANT_ROLES: ("background" | "foreground" | "border" | "accent" | "shadow")[];
+/** The private alias a component reads token `name` through, declared on its element: `--_swell-button-color-background`. */
+export declare const alias: (name: string) => string;
+/** A CSS time, such as `250ms` or `0.25s`, in milliseconds. */
+export declare const milliseconds: (time: string) => number;
+/** A font family name as CSS: a generic family or a single identifier as is, any other name quoted. */
+export declare function familyName(name: string): string;

package/dist/types/runtime/define.d.ts

@@ -0,0 +1,4 @@
+/** Defines a custom element once; a second copy of the kit on the page reuses the first one's element. */
+export declare function defineElement(tag: `swell-${string}`, element: CustomElementConstructor): void;
+/** Re-applies a property that was set on the element before its class was defined. */
+export declare function upgradeProperty(element: HTMLElement, name: string): void;

package/dist/types/runtime/description.d.ts

@@ -0,0 +1,12 @@
+/** The hint and the error of a field component, and how they describe its native control. */
+export interface Description {
+    hint: HTMLElement;
+    error: HTMLElement;
+}
+/** Creates the hint and error elements, with classes `<prefix>-hint` and `<prefix>-error`. */
+export declare function createDescription(prefix: string, id: string): Description;
+/**
+ * Shows the field's `hint`, and its `error` while it is `invalid`, and points the control (a native input or a radio group) to them.
+ * The host's own hint content, `custom`, takes the place of the `hint` text.
+ */
+export declare function describe(field: HTMLElement, control: HTMLElement, { hint, error }: Description, custom?: HTMLElement): void;

package/dist/types/runtime/element.d.ts

@@ -0,0 +1,61 @@
+/** A copy of the markup of a class's shadow root, its static `template`, parsed once per class. */
+export declare function cloneTemplate(owner: {
+    template: string;
+}): DocumentFragment;
+/** The base of every Swell UI element: it turns the appearance into a custom state. */
+export declare abstract class SwellElement extends HTMLElement {
+    #private;
+    /** The token group whose attribute values the element supports, such as `button`. */
+    static group: string | null;
+    /** The settings node of the element's appearance, such as `button` or `field`. */
+    static appearance: string | null;
+    /** Appearances the element takes from its `appearance` attribute only, beyond the values of its setting, such as the radio's `segmented`. */
+    static appearances: string[];
+    /** The component's CSS, imported with `?inline`. */
+    static styles: string;
+    static observedAttributes: string[];
+    protected readonly internals: ElementInternals;
+    constructor();
+    protected get definition(): typeof SwellElement;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, previous: string | null, value: string | null): void;
+    /** Called when an observed attribute changes. */
+    protected update(_name: string): void;
+    /** The element whose `appearance` and `variant` attributes set this element's appearance: the element itself, or a radio option's group. */
+    protected appearanceSource(): Element;
+    /** States beyond the appearance, such as the label position of a field. */
+    protected extraStates(): string[];
+    protected stylesheet(): CSSStyleSheet;
+    protected updateStates(): void;
+}
+/** Where a field's label sits: from the `field.label.position` setting, and above at size `xsmall`, which has no room for a floating label. */
+export declare function labelPosition(field: Element): string | undefined;
+/**
+ * Puts a focusable host into the tab order or takes it out. `tabindex="0"` counts as the kit's, also on a clone, which copies it; any other value is the host's and stays.
+ */
+export declare function syncTabStop(host: HTMLElement, inTabOrder: boolean): void;
+/**
+ * Makes a host with the button role click on Enter, as the key goes down, and on Space, as it comes up, as a native button does.
+ * A key that another listener cancelled, or that was pressed on a control in its shadow root, such as a link's anchor, keeps its own action; an inactive host takes the keys and stays still.
+ */
+export declare function clickOnKeys(host: HTMLElement, inactive?: () => boolean): void;
+/** A component that renders into shadow DOM and shows its children through slots. */
+export declare abstract class SwellShadowElement extends SwellElement {
+    static template: string;
+    static shadowOptions: ShadowRootInit;
+    constructor();
+}
+/** A field component: it renders its own markup into light DOM and styles it from the root that holds it. */
+export declare abstract class SwellFieldElement extends SwellElement {
+    #private;
+    /** Whether the element shows the label position as a state. */
+    static labelPosition: boolean;
+    connectedCallback(): void;
+    /**
+     * Builds the element's markup; runs once, on the first connect.
+     * Children found here are the markup of a deep clone's original, whose native control keeps the user's state, and a text field's `start` and `end` content, which stays.
+     */
+    protected abstract render(): void;
+    protected extraStates(): string[];
+}

package/dist/types/runtime/focus.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Focuses the first control among `host`'s children, its trigger left out, that takes the focus (a hidden or disabled one doesn't);
+ * else `fallback`, for as long as it holds the focus.
+ */
+export declare function focusFirst(host: Element, fallback: HTMLElement): void;

package/dist/types/runtime/form.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Enter in a field submits its form through the form's first submit button, as a browser does for native buttons.
+ * A native submit button is left to the browser; a `<swell-button>` is clicked, so a disabled one submits nothing.
+ */
+export declare function submitImplicitly(event: KeyboardEvent, control: HTMLInputElement): void;

package/dist/types/runtime/index.d.ts

@@ -0,0 +1,2 @@
+export { configure, getConfig, onChange, setTheme } from "./config.js";
+export type { Color, Config, Theme } from "./tokens.generated.js";

package/dist/types/runtime/link.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Links a group element with its child elements, such as a radio group with its options:
+ * a child reaches its group's link through its parent, and the group applies its state to each child.
+ * The child's class passes its private way of taking the state to `receive` from a static block.
+ */
+export declare function groupLink<Link, Child extends Element, State>(): {
+    /** Registers `group`, so the children among its children can reach it. */
+    link(group: Element, link: Link): void;
+    /** The group of a child: its parent, when the parent is linked. */
+    groupOf(child: Element): Element | undefined;
+    /** The link of a child's group, looked up on use, since the group may be defined after the child connected. */
+    linkOf(child: Element): Link | undefined;
+    /** Sets how a child takes its state. */
+    receive(fn: (child: Child, state: State) => void): void;
+    /** Applies the group's state to a child. */
+    sync(child: Child, state: State): void;
+};

package/dist/types/runtime/loader.d.ts

@@ -0,0 +1,21 @@
+/** Where the kit's elements are searched for and observed: a document, a shadow root, or an element in either. */
+export type Root = Document | ShadowRoot | Element;
+export interface Loader {
+    /**
+     * With a root, loads the chunk of every undefined kit element in it and of each one added to it later; with tag names, loads those tags.
+     * Resolves when they are defined, and rejects when a chunk can't load.
+     */
+    load: (target: Root | readonly string[]) => Promise<void>;
+    /** Resolves when `tags` are defined; without them, the kit's tags undefined in the document now. */
+    ready: (tags?: readonly string[]) => Promise<void>;
+}
+/** Whether a module URL is the kit's entry the platform serves, `/.swell/ui/v<major>/index.js`, rather than a host's bundle that holds the kit. */
+export declare const servedByPlatform: (url: string) => boolean;
+/**
+ * The loader of the kit's elements: each tag's chunk loads the first time the tag appears.
+ * With `page`, the loader is the page's: it reports in the console a chunk that fails. With `page.refresh`, when a chunk fails,
+ * such as one a later deploy removed, it first reads a fresh module map once and loads the tag from it.
+ */
+export declare function createLoader(elements: Record<string, () => Promise<unknown>>, page?: {
+    refresh?: () => Promise<Pick<Loader, "load">>;
+}): Loader;

package/dist/types/runtime/popup.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Places a fixed popup under `anchor`, or above it when there is more room there, at least as wide as the anchor.
+ * It lines up with the anchor's start edge in the direction of `host`, or with its end edge when it would leave the window there;
+ * when both would, it moves into the window, `EDGE` from its sides as far as its width allows. It keeps `overlay.offset` from the anchor and grows to `overlay.height` at most. Returns whether the popup went above.
+ */
+export declare function place(anchor: Element, popup: HTMLElement, host: Element): boolean;
+/** Calls `update` while the page scrolls or the window resizes; returns the function that stops it. */
+export declare function follow(update: () => void): () => void;

package/dist/types/runtime/sheet.d.ts

@@ -0,0 +1,31 @@
+import { type Config, type Theme } from "./tokens.generated.js";
+export interface Flattened {
+    /** Configured values by token name. */
+    tokens: Map<string, unknown>;
+    /** Configured settings by setting name, such as `button.secondary.appearance`. */
+    settings: Map<string, string>;
+    /** The theme the host chose; none means the page's `color-scheme`. */
+    theme?: Theme;
+    /** The accepted values, the theme included, at their configuration paths. */
+    config: Config;
+    /** One message per key or value that was skipped. */
+    warnings: string[];
+    /** The area the configuration belongs to; none for the page's. */
+    area?: string;
+    /** The host's own variants, the palettes the configuration adds to `color`. */
+    variants: string[];
+}
+export declare const THEMES: readonly Theme[];
+/**
+ * Reads a configuration into token and setting names: each key sits at its name, a component's under `components`.
+ * No configuration, `undefined` or `null`, reads as an empty one.
+ * The configuration of an area, named by `area`, holds tokens and a theme: its settings are reported and skipped.
+ */
+export declare function flatten(config: unknown, area?: string): Flattened;
+/** Zero for every duration under reduced motion, on the page root and in every area. */
+export declare const REDUCED_MOTION: string;
+/**
+ * The configuration stylesheet: the page's values and theme on the page root, then each area's on its `<swell-ui config>`.
+ * Inside an area, a token whose default references another one is declared again, so it follows the area's values, unless the page or the area gives it a value.
+ */
+export declare function buildConfigCss(page: Flattened, areas?: ReadonlyMap<string, Flattened>): string;

package/dist/types/runtime/text-field.d.ts

@@ -0,0 +1,47 @@
+import { SwellFieldElement } from "./element.js";
+type Control = HTMLInputElement | HTMLTextAreaElement;
+/**
+ * A text field: a native control with its label, hint and error, rendered into light DOM.
+ * Its shadow root only lays them out: the label above, the frame that draws the field around the control, and the hint and error under it.
+ * A subclass names its control and the attributes it passes to it.
+ */
+export declare abstract class SwellTextFieldElement extends SwellFieldElement {
+    #private;
+    static appearance: string;
+    /** The shadow root's markup; a floating label goes into the frame's `control` slot, a label above into `label`. */
+    static template: string;
+    /** The tag of the native control. */
+    static control: "input" | "textarea";
+    /** The prefix of the classes and ids of the field's parts, such as `swell-input`. */
+    static prefix: string;
+    /** Attributes copied to the native control as they are. */
+    static passed: string[];
+    /** Attributes the subclass handles itself, in `syncControl`. */
+    static own: string[];
+    /** Every attribute a text field observes, for the subclass's `observedAttributes`. */
+    static attributesOf(passed: string[], own?: string[]): string[];
+    constructor();
+    /** The current value of the field. */
+    get value(): string;
+    set value(value: string);
+    get disabled(): boolean;
+    set disabled(value: boolean);
+    get required(): boolean;
+    set required(value: boolean);
+    get readOnly(): boolean;
+    set readOnly(value: boolean);
+    get invalid(): boolean;
+    set invalid(value: boolean);
+    get name(): string;
+    set name(value: string);
+    focus(options?: FocusOptions): void;
+    connectedCallback(): void;
+    /** Sets up the native control once it is created, such as its listeners. */
+    protected setUpControl(_control: Control): void;
+    /** Applies an attribute from the subclass's `own` list to the native control. */
+    protected syncControl(_name: string, _control: Control): void;
+    protected render(): void;
+    protected updateStates(): void;
+    protected update(name: string): void;
+}
+export {};

package/dist/types/runtime/toggle.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Announces the changes of a host's `open` with a `toggle` event, once the script that changed it has run, with the state before and after.
+ * The event neither bubbles nor cancels, as a native popover's; changes that end where they started fire nothing.
+ * Returns the function to call on each change of `open`.
+ */
+export declare function announceToggle(host: HTMLElement & {
+    open: boolean;
+}): () => void;