@pfern/elements 0.1.11 → 0.2.1

package/types/mathml.d.ts

@@ -0,0 +1 @@
+export * from "./src/mathml.js";

package/types/src/core/elements.d.ts

@@ -0,0 +1,29 @@
+export * from "./types.js";
+export const DEBUG: boolean;
+export function render(vtree: import("./types.js").ElementsVNode, container?: HTMLElement | null, { replace }?: {
+    replace?: boolean;
+}): void;
+export function component<Args extends any[]>(fn: (...args: Args) => import("./types.js").ElementsVNode): (...args: Args) => import("./types.js").ElementsVNode;
+/**
+ * A map of supported HTML and SVG element helpers.
+ *
+ * Each helper is a function that accepts optional props as first argument
+ * and children as subsequent arguments.
+ *
+ * Example:
+ *
+ * ```js
+ * div({ id: 'foo' }, 'Hello World')
+ * ```
+ *
+ * Produces:
+ *
+ * ```js
+ * ['div', { id: 'foo' }, 'Hello World']
+ * ```
+ *
+ * The following helpers are included:
+ * `div`, `span`, `button`, `svg`, `circle`, etc.
+ */
+/** @type {import('./types.js').ElementsElementMap} */
+export const elements: import("./types.js").ElementsElementMap;

package/types/src/core/events.d.ts

@@ -0,0 +1,15 @@
+export function isEventProp(key: any, value: any): boolean;
+export function isFormEventProp(key: any): boolean;
+export function isSubmitEventProp(key: any): boolean;
+export function isValueEventProp(key: any): boolean;
+export function getNearestRoot(el: any, isRoot: any): any;
+export function createDeclarativeEventHandler(env: {
+    el: any;
+    key: string;
+    handler: Function;
+    isRoot: (el: any) => boolean;
+    renderTree: (node: any, isRoot?: boolean, namespaceURI?: string | null) => any;
+    getCurrentEventRoot: () => any;
+    setCurrentEventRoot: (el: any) => void;
+    debug: boolean;
+}): (...args: any[]) => any;

package/types/src/core/props.d.ts

@@ -0,0 +1,9 @@
+export function removeMissingProps(el: any, prevProps: Record<string, any>, nextProps: Record<string, any>): void;
+export function assignProperties(el: any, props: Record<string, any>, env: {
+    svgNS: string;
+    debug: boolean;
+    isRoot: (el: any) => boolean;
+    renderTree: (node: any, isRoot?: boolean, namespaceURI?: string | null) => any;
+    getCurrentEventRoot: () => any;
+    setCurrentEventRoot: (el: any) => void;
+}): void;

package/types/src/core/tags.d.ts

@@ -0,0 +1,4 @@
+/** @internal */
+export const htmlTagNames: readonly ["html", "head", "base", "link", "meta", "title", "body", "header", "hgroup", "nav", "main", "section", "article", "aside", "footer", "address", "h1", "h2", "h3", "h4", "h5", "h6", "p", "hr", "menu", "pre", "blockquote", "ol", "ul", "li", "dl", "dt", "dd", "figure", "figcaption", "div", "a", "abbr", "b", "bdi", "bdo", "br", "cite", "code", "data", "dfn", "em", "i", "kbd", "mark", "q", "rb", "rp", "rt", "rtc", "ruby", "s", "samp", "small", "span", "strong", "sub", "sup", "time", "u", "var", "wbr", "ins", "del", "img", "iframe", "embed", "object", "param", "video", "audio", "source", "track", "picture", "table", "caption", "thead", "tbody", "tfoot", "tr", "th", "td", "colgroup", "col", "form", "fieldset", "legend", "label", "input", "button", "select", "datalist", "optgroup", "option", "textarea", "output", "progress", "meter", "details", "search", "summary", "dialog", "slot", "template", "script", "noscript", "style", "canvas", "picture", "map", "area", "slot"];
+/** @internal */
+export const svgTagNames: readonly ["animate", "animateMotion", "animateTransform", "mpath", "set", "circle", "ellipse", "line", "path", "polygon", "polyline", "rect", "defs", "g", "marker", "mask", "pattern", "svg", "switch", "symbol", "use", "desc", "metadata", "title", "filter", "feBlend", "feColorMatrix", "feComponentTransfer", "feComposite", "feConvolveMatrix", "feDiffuseLighting", "feDisplacementMap", "feDistantLight", "feDropShadow", "feFlood", "feFuncA", "feFuncB", "feFuncG", "feFuncR", "feGaussianBlur", "feImage", "feMerge", "feMergeNode", "feMorphology", "feOffset", "fePointLight", "feSpecularLighting", "feSpotLight", "feTile", "feTurbulence", "linearGradient", "radialGradient", "stop", "image", "foreignObject", "text", "textPath", "tspan", "script", "style", "view"];

package/types/src/core/tick.d.ts

@@ -0,0 +1,5 @@
+export function isConnected(el: any): any;
+export function stopTickLoop(el: any): any;
+export function startTickLoop<Ctx>(el: Element, handler: (el: Element, ctx: any, dtMs: number) => (any | void), { ready }?: {
+    ready?: (el: Element) => boolean;
+}): void;

package/types/src/core/types.d.ts

@@ -0,0 +1,507 @@
+/**
+ * Primitive values that can be serialized as HTML/SVG attribute values.
+ *
+ * Note: the runtime assigns most props via `setAttribute`, so strings are the
+ * canonical representation. Numbers/booleans are accepted for convenience and
+ * are coerced by the DOM.
+ */
+export type ElementsAttributeValue = string | number | boolean | null | undefined;
+/**
+ * Inline style object applied via `Object.assign(el.style, style)`.
+ */
+export type ElementsStyleObject = Partial<CSSStyleDeclaration> & Record<string, string | number>;
+/**
+ * A vnode is a declarative array of the form:
+ *
+ * ```js
+ * [tag, props, ...children]
+ * ```
+ */
+export type ElementsVNode = [tag: string, props: ElementsProps, ...children: ElementsChild[]];
+/**
+ * Child nodes are plain values, nested arrays, or vnodes.
+ *
+ * Note: nested arrays are treated as children values (they are not
+ * automatically flattened).
+ */
+export type ElementsChild = ElementsVNode | string | number | boolean | null | undefined | any[];
+/**
+ * Props for the `ontick` animation hook.
+ *
+ * `ontick` is not a DOM event. It runs once per animation frame and can thread
+ * context across ticks:
+ *
+ * ```js
+ * ontick: (el, ctx = { t: 0 }, dt) => ({ ...ctx, t: ctx.t + dt })
+ * ```
+ *
+ * The handler must be synchronous; thrown errors stop ticking.
+ */
+export type ElementsOnTick = (el: Element, ctx: any, dtMs: number) => any | void;
+/**
+ * If an event handler returns a vnode array, the UI updates by replacing the
+ * nearest component boundary. Otherwise the event is treated as passive.
+ */
+export type ElementsEventResult = ElementsVNode | void | null | false | "" | 0;
+/**
+ * If an event handler returns a vnode array, the UI updates by replacing the
+ * nearest component boundary. Otherwise the event is treated as passive.
+ */
+export type ElementsMaybeAsyncEventResult = ElementsEventResult | Promise<ElementsEventResult>;
+export type ElementsEventHandler<Evt extends Event> = (event: Evt) => ElementsMaybeAsyncEventResult;
+/**
+ * Form event handlers receive `(elements, event)`.
+ */
+export type ElementsFormEventHandler<FormEvt extends Event> = (elements: any, event: FormEvt) => ElementsMaybeAsyncEventResult;
+/**
+ * Common global HTML attributes.
+ *
+ * This is a permissive shared set: some attributes only apply to certain
+ * elements in the HTML spec, but Elements.js accepts them everywhere because
+ * the underlying DOM will ignore irrelevant attributes.
+ *
+ * This is not exhaustive; `data-*` and `aria-*` are supported via template
+ * keys below.
+ */
+export type ElementsGlobalAttributes = {
+    id?: string;
+    class?: string;
+    title?: string;
+    role?: string;
+    name?: string;
+    part?: string;
+    slot?: string;
+    exportparts?: string;
+    nonce?: string;
+    elementtiming?: string;
+    contentsecuritypolicy?: string;
+    popovertarget?: string;
+    popovertargetaction?: "toggle" | "show" | "hide";
+    autocapitalize?: "none" | "sentences" | "words" | "characters" | "on" | "off";
+    enterkeyhint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send";
+    inputmode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search";
+    virtualkeyboardpolicy?: "auto" | "manual";
+    draggable?: boolean;
+    hidden?: boolean;
+    inert?: boolean;
+    spellcheck?: boolean;
+    tabindex?: number | string;
+    accesskey?: string;
+    translate?: "yes" | "no";
+    autocorrect?: "on" | "off";
+    autocomplete?: string;
+    lang?: string;
+    dir?: "ltr" | "rtl" | "auto";
+    is?: string;
+    writingsuggestions?: "true" | "false" | boolean;
+    contenteditable?: "true" | "false" | "plaintext-only" | boolean;
+    autofocus?: boolean;
+    popover?: "auto" | "manual";
+    label?: string;
+    itemscope?: boolean;
+    itemtype?: string;
+    itemid?: string;
+    itemprop?: string;
+    itemref?: string;
+    vocab?: string;
+    typeof?: string;
+    property?: string;
+    resource?: string;
+    prefix?: string;
+    href?: string;
+    hreflang?: string;
+    referrerpolicy?: string;
+    target?: string;
+    rel?: string;
+    download?: string;
+    ping?: string;
+    src?: string;
+    srcset?: string;
+    sizes?: string;
+    imagesrcset?: string;
+    imagesizes?: string;
+    alt?: string;
+    width?: number | string;
+    height?: number | string;
+    type?: string;
+    content?: string;
+    placeholder?: string;
+    required?: boolean;
+    readonly?: boolean;
+    minlength?: number | string;
+    maxlength?: number | string;
+    min?: number | string;
+    max?: number | string;
+    step?: number | string;
+    pattern?: string;
+    accept?: string;
+    for?: string;
+    action?: string;
+    method?: string;
+    enctype?: string;
+    novalidate?: boolean;
+    formaction?: string;
+    formenctype?: string;
+    formmethod?: string;
+    formnovalidate?: boolean;
+    formtarget?: string;
+    rows?: number | string;
+    cols?: number | string;
+    wrap?: string;
+    list?: string;
+    async?: boolean;
+    defer?: boolean;
+    nomodule?: boolean;
+    crossorigin?: "" | "anonymous" | "use-credentials";
+    integrity?: string;
+    fetchpriority?: "auto" | "high" | "low";
+    loading?: "lazy" | "eager";
+    decoding?: "sync" | "async" | "auto";
+    media?: string;
+    as?: string;
+    controls?: boolean;
+    controlslist?: string;
+    autoplay?: boolean;
+    loop?: boolean;
+    playsinline?: boolean;
+    preload?: "none" | "metadata" | "auto";
+    poster?: string;
+};
+export type ElementsDataAttributes = {
+    [key: `data-${string}`]: ElementsAttributeValue;
+};
+export type ElementsAriaAttributes = {
+    [key: `aria-${string}`]: ElementsAttributeValue;
+};
+/**
+ * Dash-cased attributes commonly used by custom elements and utilities.
+ */
+export type ElementsDashedAttributes = {
+    [key: `${string}-${string}`]: ElementsAttributeValue;
+};
+/**
+ * DOM event handler props.
+ */
+export type ElementsEventProps = Omit<{ [K in keyof GlobalEventHandlersEventMap as `on${K}`]?: ElementsEventHandler<GlobalEventHandlersEventMap[K]>; }, "oninput" | "onsubmit" | "onchange"> & {
+    oninput?: ElementsFormEventHandler<InputEvent | Event>;
+    onsubmit?: ElementsFormEventHandler<SubmitEvent | Event>;
+    onchange?: ElementsFormEventHandler<Event>;
+};
+/**
+ * Special (non-attribute) props supported by Elements.js.
+ *
+ * Note: some props are assigned as DOM properties (when present on the target
+ * element) rather than attributes: `value`, `checked`, `selected`, `disabled`,
+ * `multiple`, `muted`, `volume`, `currentTime`, `playbackRate`, `open`,
+ * `indeterminate`.
+ */
+export type ElementsSpecialProps = {
+    style?: ElementsStyleObject;
+    innerHTML?: string;
+    ontick?: ElementsOnTick;
+    value?: string | number;
+    checked?: boolean;
+    selected?: boolean;
+    disabled?: boolean;
+    multiple?: boolean;
+    muted?: boolean;
+    volume?: number;
+    currentTime?: number;
+    playbackRate?: number;
+    open?: boolean;
+    indeterminate?: boolean;
+};
+/**
+ * Props accepted by all Elements.js tag helpers.
+ */
+export type ElementsProps = ElementsGlobalAttributes & ElementsDataAttributes & ElementsAriaAttributes & ElementsDashedAttributes & ElementsEventProps & ElementsSpecialProps;
+export type ElementsElementHelper<P extends ElementsProps> = (propsOrChild?: P | ElementsChild, ...children: ElementsChild[]) => ElementsVNode;
+export type ElementsHtmlTagName = (typeof htmlTagNames)[number];
+export type ElementsSvgTagName = (typeof svgTagNames)[number];
+export type ElementsTagName = ElementsHtmlTagName | ElementsSvgTagName;
+/**
+ * Props for `<a>`.
+ */
+export type ElementsAnchorProps = ElementsProps & {
+    href?: string;
+    target?: string;
+    rel?: string;
+    download?: string;
+};
+/**
+ * Props for `<img>`.
+ */
+export type ElementsImgProps = ElementsProps & {
+    src?: string;
+    alt?: string;
+    loading?: "lazy" | "eager";
+    decoding?: "sync" | "async" | "auto";
+    referrerpolicy?: string;
+};
+/**
+ * Props for `<input>`.
+ */
+export type ElementsInputProps = ElementsProps & {
+    type?: string;
+    name?: string;
+    placeholder?: string;
+    required?: boolean;
+    readonly?: boolean;
+    minlength?: number | string;
+    maxlength?: number | string;
+    min?: number | string;
+    max?: number | string;
+    step?: number | string;
+    pattern?: string;
+    accept?: string;
+    autocomplete?: string;
+};
+/**
+ * Props for `<form>`.
+ */
+export type ElementsFormProps = ElementsProps & {
+    action?: string;
+    method?: string;
+    enctype?: string;
+    novalidate?: boolean;
+};
+/**
+ * Props for `<button>`.
+ */
+export type ElementsButtonProps = ElementsProps & {
+    type?: "button" | "submit" | "reset" | string;
+    name?: string;
+    value?: string | number;
+    disabled?: boolean;
+};
+/**
+ * Props for `<textarea>`.
+ */
+export type ElementsTextareaProps = ElementsProps & {
+    name?: string;
+    rows?: number | string;
+    cols?: number | string;
+    wrap?: string;
+    placeholder?: string;
+    required?: boolean;
+    readonly?: boolean;
+    minlength?: number | string;
+    maxlength?: number | string;
+};
+/**
+ * Props for `<select>`.
+ */
+export type ElementsSelectProps = ElementsProps & {
+    name?: string;
+    required?: boolean;
+    multiple?: boolean;
+};
+/**
+ * Props for `<option>`.
+ */
+export type ElementsOptionProps = ElementsProps & {
+    value?: string | number;
+    selected?: boolean;
+    disabled?: boolean;
+};
+/**
+ * Props for `<script>`.
+ */
+export type ElementsScriptProps = ElementsProps & {
+    src?: string;
+    type?: string;
+    async?: boolean;
+    defer?: boolean;
+    nomodule?: boolean;
+    crossorigin?: "" | "anonymous" | "use-credentials";
+    integrity?: string;
+};
+/**
+ * Props for `<link>`.
+ */
+export type ElementsLinkProps = ElementsProps & {
+    href?: string;
+    rel?: string;
+    as?: string;
+    type?: string;
+    media?: string;
+    crossorigin?: "" | "anonymous" | "use-credentials";
+    integrity?: string;
+    referrerpolicy?: string;
+    fetchpriority?: "auto" | "high" | "low";
+};
+/**
+ * Props for `<meta>`.
+ */
+export type ElementsMetaProps = ElementsProps & {
+    name?: string;
+    content?: string;
+    charset?: string;
+    "http-equiv"?: string;
+};
+/**
+ * Props for `<video>` and `<audio>`.
+ */
+export type ElementsMediaProps = ElementsProps & {
+    src?: string;
+    controls?: boolean;
+    controlslist?: string;
+    autoplay?: boolean;
+    loop?: boolean;
+    muted?: boolean;
+    playsinline?: boolean;
+    preload?: "none" | "metadata" | "auto";
+};
+/**
+ * Props for `<source>`.
+ */
+export type ElementsSourceProps = ElementsProps & {
+    src?: string;
+    type?: string;
+    srcset?: string;
+    sizes?: string;
+    media?: string;
+};
+/**
+ * Props for `<svg>`.
+ */
+export type ElementsSvgProps = ElementsProps & {
+    viewBox?: string;
+    xmlns?: string;
+    fill?: string;
+    stroke?: string;
+    "stroke-width"?: number | string;
+};
+/**
+ * Props for `<path>`.
+ */
+export type ElementsPathProps = ElementsProps & {
+    d?: string;
+    fill?: string;
+    stroke?: string;
+    "stroke-width"?: number | string;
+};
+/**
+ * Props for `<circle>`.
+ */
+export type ElementsCircleProps = ElementsProps & {
+    cx?: number | string;
+    cy?: number | string;
+    r?: number | string;
+    fill?: string;
+    stroke?: string;
+    "stroke-width"?: number | string;
+};
+/**
+ * Props for `<rect>`.
+ */
+export type ElementsRectProps = ElementsProps & {
+    x?: number | string;
+    y?: number | string;
+    rx?: number | string;
+    ry?: number | string;
+    width?: number | string;
+    height?: number | string;
+    fill?: string;
+    stroke?: string;
+    "stroke-width"?: number | string;
+};
+/**
+ * Props for `<line>`.
+ */
+export type ElementsLineProps = ElementsProps & {
+    x1?: number | string;
+    y1?: number | string;
+    x2?: number | string;
+    y2?: number | string;
+    stroke?: string;
+    "stroke-width"?: number | string;
+};
+/**
+ * Props for `<text>` (SVG).
+ *
+ * Note: X3D also has a `text` node; it is exported as `x3dtext` in `/3d`.
+ */
+export type ElementsSvgTextProps = ElementsProps & {
+    x?: number | string;
+    y?: number | string;
+    dx?: number | string;
+    dy?: number | string;
+    rotate?: number | string;
+    "text-anchor"?: string;
+};
+/**
+ * Props for `<label>`.
+ */
+export type ElementsLabelProps = ElementsProps & {
+    for?: string;
+    form?: string;
+};
+/**
+ * Props for `<dialog>`.
+ */
+export type ElementsDialogProps = ElementsProps & {
+    open?: boolean;
+};
+/**
+ * Props for `<details>`.
+ */
+export type ElementsDetailsProps = ElementsProps & {
+    open?: boolean;
+};
+/**
+ * Props for `<progress>`.
+ */
+export type ElementsProgressProps = ElementsProps & {
+    value?: number | string;
+    max?: number | string;
+};
+/**
+ * Props for `<meter>`.
+ */
+export type ElementsMeterProps = ElementsProps & {
+    value?: number | string;
+    min?: number | string;
+    max?: number | string;
+    low?: number | string;
+    high?: number | string;
+    optimum?: number | string;
+};
+/**
+ * Props for `<iframe>`.
+ */
+export type ElementsIframeProps = ElementsProps & {
+    src?: string;
+    srcdoc?: string;
+    name?: string;
+    allow?: string;
+    sandbox?: string;
+    referrerpolicy?: string;
+    loading?: "lazy" | "eager";
+    allowfullscreen?: boolean;
+};
+/**
+ * Props for `<canvas>`.
+ */
+export type ElementsCanvasProps = ElementsProps & {
+    width?: number | string;
+    height?: number | string;
+};
+export type ElementsPropsForTag<Tag extends ElementsTagName> = Tag extends "a" ? ElementsAnchorProps : Tag extends "img" ? ElementsImgProps : Tag extends "input" ? ElementsInputProps : Tag extends "form" ? ElementsFormProps : Tag extends "button" ? ElementsButtonProps : Tag extends "textarea" ? ElementsTextareaProps : Tag extends "select" ? ElementsSelectProps : Tag extends "option" ? ElementsOptionProps : Tag extends "script" ? ElementsScriptProps : Tag extends "link" ? ElementsLinkProps : Tag extends "meta" ? ElementsMetaProps : Tag extends "video" ? ElementsMediaProps : Tag extends "audio" ? ElementsMediaProps : Tag extends "source" ? ElementsSourceProps : Tag extends "svg" ? ElementsSvgProps : Tag extends "path" ? ElementsPathProps : Tag extends "circle" ? ElementsCircleProps : Tag extends "rect" ? ElementsRectProps : Tag extends "line" ? ElementsLineProps : Tag extends "text" ? ElementsSvgTextProps : Tag extends "label" ? ElementsLabelProps : Tag extends "dialog" ? ElementsDialogProps : Tag extends "details" ? ElementsDetailsProps : Tag extends "progress" ? ElementsProgressProps : Tag extends "meter" ? ElementsMeterProps : Tag extends "iframe" ? ElementsIframeProps : Tag extends "canvas" ? ElementsCanvasProps : ElementsProps;
+/**
+ * All tag helpers, with per-tag prop typing when known.
+ */
+export type ElementsElementMap = {
+    fragment: ElementsElementHelper<ElementsProps>;
+} & { [K in ElementsTagName]: ElementsElementHelper<ElementsPropsForTag<K>>; };
+/**
+ * Aliases (short names) for Types-as-Docs.
+ *
+ * These are convenience names for editor DX. The `Elements*` names remain the
+ * canonical internal names.
+ */
+export type ElementProps = ElementsProps;
+export type ElementHelper<P extends ElementProps> = ElementsElementHelper<P>;
+export type ElementMap = ElementsElementMap;
+import { htmlTagNames } from './tags.js';
+import { svgTagNames } from './tags.js';

package/types/src/helpers.d.ts

@@ -0,0 +1,5 @@
+export { toHtmlString } from "./ssr.js";
+export function navigate(path?: string, { replace }?: {
+    replace?: boolean;
+}): void;
+export { DEBUG, component, elements, render } from "./core/elements.js";