@fluixi/web-components 0.0.0-stage → 1.0.0-alpha.100

package/dist/element.d.ts

@@ -0,0 +1,213 @@
+/**
+ * The custom element itself: lifecycle on Fluixi's existing ownership model.
+ *
+ * `HTMLReactiveElement` is a real class, authored the way the platform defines elements:
+ * `class X extends HTMLReactiveElement`, callbacks as methods, `customElements.define`.
+ * What it adds is the reactive part. Declared props are signals behind accessors, and the
+ * first connect runs `render()` once inside one `createRoot` scope; bindings update after
+ * that and `dispose` takes the whole subtree down.
+ *
+ * Visibility is deliberate. The platform callbacks are public because the browser calls
+ * them. `render`, `emit`, `targets`, `renderRoot`, `internals` and `authoredChildren` are
+ * protected: they are for the element's own code, not its consumers. The engine's state is
+ * in `#private` fields, private at runtime and not only to TypeScript.
+ *
+ * `insert` rather than `render`: `render` clears its container going in and again coming
+ * out (@fluixi/dom runtime.ts), which for a light-DOM element would delete the author's own
+ * children before the component ever saw them.
+ */
+import { type Accessor } from '@fluixi/reactive/signal';
+import { type PropAccessors, type PropDeclaration } from './props.js';
+import { type DefineOptions } from './registry.js';
+import { type Dispatch, type DispatchInit } from './events.js';
+import { type Targets } from './targets.js';
+import { type ElementStyles } from './styles.js';
+import { type ConsumeOptions, type ElementContext } from './context.js';
+/** Each element class's own server render, so the copy of this package that defined it does the work. */
+declare const RENDER_ON_SERVER: unique symbol;
+/** The part of a @fluixi/dom server node the renderer uses. */
+interface ServerNodeLike {
+    localName: string;
+    childNodes: unknown[];
+    getAttribute(name: string): string | null;
+    setAttribute(name: string, value: string): void;
+    removeChild(child: unknown): unknown;
+}
+import type { PropValues } from './types.js';
+/**
+ * `true`, `'open'` or `'closed'` for a plain shadow root, or the options `attachShadow` takes:
+ * `{ mode: 'open', delegatesFocus: true }` makes focusing the host focus the first focusable
+ * thing inside, which is what a custom input wants.
+ */
+export type ShadowOption = boolean | 'open' | 'closed' | {
+    mode?: 'open' | 'closed';
+    delegatesFocus?: boolean;
+    slotAssignment?: 'named' | 'manual';
+};
+type Schema = Record<string, PropDeclaration<unknown>>;
+/**
+ * `HTMLElement` in a browser. On a server there is none, and a module declaring
+ * `class X extends HTMLReactiveElement` is still imported by code that renders there, so
+ * the base is an inert stand-in: the class can be declared, nothing is ever defined.
+ */
+declare const BaseElement: typeof HTMLElement;
+export declare class HTMLReactiveElement extends BaseElement {
+    #private;
+    /** The declared properties, and the attributes that mirror them. Inherited and merged. */
+    static props?: Schema;
+    /**
+     * `false` (the default) renders into the element itself. `'open'`, `'closed'`, `true` or an
+     * options object attach a shadow root, which is what native `<slot>` needs. Light DOM is the default: a
+     * component that inherits the page's styles is usually what an app wants, and it is the
+     * mode that survives a server render without declarative shadow DOM.
+     */
+    static shadow?: ShadowOption;
+    /**
+     * Adopted by the shadow root, one parsed sheet shared by every instance. CSS text, a
+     * `CSSStyleSheet`, or a list: `[super.styles, '…']` keeps the parent's. A class meant to be
+     * extended declares it as `static styles: ElementStyles = …`, since a bare string narrows
+     * the type and a subclass's list no longer fits. Ignored in light DOM, which has no scope.
+     */
+    static styles?: ElementStyles;
+    /**
+     * The attributes of every declared prop. A mixin in between that observes its own
+     * extends this with `super.observedAttributes`; a subclass need not touch it.
+     */
+    static get observedAttributes(): string[];
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** Another document, the same scope: nothing reactive depends on which document holds the node. */
+    adoptedCallback(): void;
+    attributeChangedCallback(name: string, previous: string | null, value: string | null): void;
+    /**
+     * What the element shows. Runs once, on the first connect, inside the element's reactive
+     * scope; bindings keep it current after that. It is never re-run, so read a prop inside a
+     * binding (`() => this.step`), not in the body, to follow it.
+     */
+    protected render(): unknown;
+    /**
+     * Give `context` to the elements inside this one, and to `useContext` in the components it
+     * renders. A value or an accessor; subscribed consumers follow the accessor. Call in `render()`.
+     */
+    protected provide<T>(context: ElementContext<T>, value: T | Accessor<T>): void;
+    /**
+     * The nearest value of `context` above this element, as an accessor: an element providing
+     * it, else the Fluixi app the element was rendered in, else the default. Call in `render()`.
+     */
+    protected consume<T>(context: ElementContext<T>, options?: ConsumeOptions): Accessor<T>;
+    /**
+     * Dispatch a `CustomEvent`, bubbling and composed by default. False when cancelled.
+     *
+     * The name goes out lowercased: a JSX handler listens for the name after `on`, lowercased,
+     * so `emit('signOut')` reaches `onSignOut`, and a listener added by hand uses `signout`.
+     */
+    protected emit<T>(type: string, detail?: T, init?: DispatchInit): boolean;
+    /** Elements inside this one, by `data-target`, scoped to its render root. */
+    protected get targets(): Targets;
+    /** Where `render()` output goes: the shadow root, or the element itself in light DOM. */
+    protected get renderRoot(): ShadowRoot | HTMLElement;
+    /**
+     * The children the author wrote between the tags, in light DOM. Empty under shadow DOM,
+     * where the browser projects them through `<slot>` and they were never the element's to place.
+     */
+    protected get authoredChildren(): readonly ChildNode[];
+    /**
+     * The element's `ElementInternals`, attached on first use: ARIA defaults, custom states,
+     * and with `static formAssociated = true`, taking part in a `<form>`.
+     */
+    protected get internals(): ElementInternals;
+    /**
+     * Render a light DOM element's content into its server node, under the page's owner so its
+     * context and resources are the page's. Props come from what @fluixi/dom recorded on the
+     * node; the ones with no attribute form ride along as JSON for the client. Shadow DOM
+     * elements are left to the client until declarative shadow roots are emitted.
+     */
+    static [RENDER_ON_SERVER](this: typeof HTMLReactiveElement, node: ServerNodeLike): void;
+}
+/**
+ * `HTMLReactiveElement` with the declared props typed on the instance:
+ * `class Counter extends typedElement(props)` gives `this.step` its type. Static props alone
+ * work at runtime; this is only the type.
+ */
+export declare function typedElement<S extends Schema>(props: S): TypedElementClass<S>;
+/**
+ * What `typedElement` returns: the base class, with the props typed on the instance and on
+ * the static side, so a subclass can write `static props = { ...Parent.props, extra }`.
+ */
+export type TypedElementClass<S extends Schema> = (abstract new () => HTMLReactiveElement & PropValues<S>) & Omit<typeof HTMLReactiveElement, 'prototype' | 'props'> & {
+    props: S;
+};
+/**
+ * What a mixin extends: an element class, instance and statics. Constrain a mixin's base to it,
+ * `function Toggle<B extends ElementBase>(Base: B)`, and `super.observedAttributes` is typed.
+ */
+export type ElementBase = (abstract new (...args: any[]) => HTMLReactiveElement) & {
+    readonly observedAttributes: string[];
+    props?: Schema;
+    shadow?: ShadowOption;
+    styles?: ElementStyles;
+};
+/**
+ * A class-to-class mixin, applied over `HTMLReactiveElement` in the function form. Generic over
+ * `ElementBase`, or written against `HTMLReactiveElement` itself.
+ */
+export type ElementMixin = ((base: ElementBase) => ElementBase) | ((base: typeof HTMLReactiveElement) => typeof HTMLReactiveElement);
+export interface ElementOptions<S extends Schema> {
+    /** Declared properties and the attributes that mirror them. */
+    props?: S;
+    /** See `HTMLReactiveElement.shadow`. */
+    shadow?: ShadowOption;
+    /** See `HTMLReactiveElement.styles`. */
+    styles?: ElementStyles;
+    /** Passed through to `customElements.define`. */
+    define?: DefineOptions;
+    /**
+     * Mixins applied over `HTMLReactiveElement`, in order, the way a class writes
+     * `extends B(A(HTMLReactiveElement))`. A mixin that implements a platform callback calls
+     * `super` and runs before this element's own work.
+     */
+    mixins?: ElementMixin[];
+}
+/**
+ * The constructor the function form hands back, carrying the element's properties.
+ *
+ * `new Counter().step` is a number rather than an error, and
+ * `HTMLElementTagNameMap['fx-counter'] = InstanceType<typeof Counter>` is the whole
+ * declaration a consumer writes.
+ */
+export interface ElementConstructor<S extends Schema> extends CustomElementConstructor {
+    new (): HTMLReactiveElement & PropValues<S>;
+    readonly observedAttributes: string[];
+}
+/** What a setup function is handed. */
+export interface Host<S extends Schema> {
+    /** The custom element. For focus, measurement, and anything DOM-level. */
+    readonly el: HTMLElement;
+    /** Reactive reads of the declared properties. */
+    readonly props: PropAccessors<S>;
+    /** Write a property from inside. Reflects too, when the declaration says so. */
+    set<K extends keyof S>(name: K, value: S[K] extends PropDeclaration<infer T> ? T : never): void;
+    /** Emit a `CustomEvent`. False when a listener cancelled it. */
+    readonly dispatch: Dispatch;
+    /** Elements inside this one, by `data-target`. */
+    readonly targets: Targets;
+    /** The children the author wrote between the tags, in light DOM. Empty under shadow DOM. */
+    children(): ChildNode[];
+    /** See `HTMLReactiveElement.provide`. */
+    provide<T>(context: ElementContext<T>, value: T | Accessor<T>): void;
+    /** See `HTMLReactiveElement.consume`. */
+    consume<T>(context: ElementContext<T>, options?: ConsumeOptions): Accessor<T>;
+}
+export type Setup<S extends Schema> = (host: Host<S>) => unknown;
+export declare function createElementClass<S extends Schema>(setup: Setup<S>, options?: ElementOptions<S>): ElementConstructor<S>;
+/**
+ * Define a Fluixi component as a custom element.
+ *
+ * Returns the constructor, so a caller can subclass it or hand it to a lazy loader. On a
+ * server it builds the class and registers nothing, which keeps the module importable from
+ * code that also runs during a server render.
+ */
+export declare function defineElement<S extends Schema>(name: string, setup: Setup<S>, options?: ElementOptions<S>): ElementConstructor<S>;
+export {};
+//# sourceMappingURL=element.d.ts.map

package/dist/element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.d.ts","sourceRoot":"","sources":["../src/element.ts"],"names":[],"mappings":"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"}