@xoong/core 0.0.39 → 0.0.42

package/package.json

@@ -1,14 +1,26 @@
 {
   "name": "@xoong/core",
-  "version": "0.0.39",
+  "version": "0.0.42",
   "description": "xoong core: signals, Light DOM custom elements, html templates. Zero dependencies.",
   "type": "module",
   "main": "src/index.js",
   "exports": {
-    ".": "./src/index.js",
-    "./signals": "./src/signals.js",
-    "./closest": "./src/closest.js",
-    "./syntax": "./src/syntax.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./signals": {
+      "types": "./src/signals.d.ts",
+      "default": "./src/signals.js"
+    },
+    "./closest": {
+      "types": "./src/closest.d.ts",
+      "default": "./src/closest.js"
+    },
+    "./syntax": {
+      "types": "./src/syntax.d.ts",
+      "default": "./src/syntax.js"
+    }
   },
   "sideEffects": false,
   "license": "MIT",
@@ -30,7 +42,7 @@
   "bugs": {
     "url": "https://github.com/fpt-duongtx/xoong/issues"
   },
-  "homepage": "https://github.com/fpt-duongtx/xoong#readme",
+  "homepage": "https://fpt-duongtx.github.io/xoong/",
   "publishConfig": {
     "access": "public"
   },

package/src/closest.d.ts

@@ -0,0 +1,7 @@
+// Types for @xoong/core/closest: "did you mean" helpers.
+
+/** Edit distance (Levenshtein) between two strings. */
+export function distance(a: string, b: string): number;
+
+/** The candidate closest to `ref` (case-insensitive), or undefined when nothing is close enough. */
+export function nearest(ref: string, candidates: Iterable<string>): string | undefined;

package/src/control.d.ts

@@ -0,0 +1,101 @@
+// Types for XoControl, the base class of form-associated custom elements.
+import { XoElement } from './element.js';
+
+/** The validity state of a control: the same names as the native `ValidityState`, as a plain object. */
+export interface XoValidity {
+  readonly valid: boolean;
+  readonly valueMissing: boolean;
+  readonly customError: boolean;
+  readonly badInput: boolean;
+  readonly typeMismatch: boolean;
+  readonly patternMismatch: boolean;
+  readonly rangeOverflow: boolean;
+  readonly rangeUnderflow: boolean;
+  readonly stepMismatch: boolean;
+  readonly tooLong: boolean;
+  readonly tooShort: boolean;
+}
+
+/**
+ * Base class for custom form controls. It behaves like a native input in a `<form>`: it submits `name` and `value` through ElementInternals,
+ * takes part in constraint validation, resets with the form, is disabled with its fieldset, and tracks `dirty`, `touched` and `pristine`.
+ * Subclass it, render the inner UI, and call `userInput(value)` when the person changes the value.
+ *
+ *     class StarRating extends XoControl {
+ *       static props = { ...XoControl.props, max: Number };
+ *       declare max: number;
+ *       render() { return html`<button @click=${() => this.userInput(Number(this.value) + 1)}>+</button>`; }
+ *       validate(value: unknown) { return Number(value) > this.max ? 'Too many stars' : ''; }
+ *     }
+ *     define('star-rating', StarRating);
+ */
+export class XoControl extends XoElement {
+  static formAssociated: boolean;
+  static props: { name: StringConstructor; required: BooleanConstructor; disabled: BooleanConstructor; readonly: BooleanConstructor };
+
+  constructor();
+
+  /** The form field name. */
+  name: string;
+  required: boolean;
+  disabled: boolean;
+  readonly: boolean;
+
+  // ---- value
+  /** The value. A string by default; a subclass may hold anything and override `serialize`. Reading it is tracked. */
+  get value(): any;
+  set value(v: any);
+  /** Set the value programmatically (like `input.value = x`: no events). Before the control has started, it also becomes the initial value. */
+  setValue(v: any): void;
+  /** The person changed the value: sets it and fires `input`. */
+  userInput(v: any): void;
+  /** The person finished a change: fires `change`. */
+  userChange(): void;
+  /** What the form submits for a value: a string, a File, FormData, or null for nothing. Override for structured values. */
+  serialize(v: any): string | File | FormData | null;
+  /** Whether a value counts as "nothing entered" for `required`. Override for structured values. */
+  isEmpty(v: any): boolean;
+  /** Validation hook: return an error message for an invalid value, a falsy value when it is valid. Runs on every change. */
+  validate(value: any): string | null | undefined | false;
+
+  // ---- state (reading these inside a template or an effect is tracked)
+  /** The value the control started with (what `reset` goes back to and `dirty` compares with). */
+  get initialValue(): any;
+  get dirty(): boolean;
+  get pristine(): boolean;
+  get touched(): boolean;
+  /** True when there is no validation error. */
+  get valid(): boolean;
+  get invalid(): boolean;
+  /** Mark the control as visited (blur does this). */
+  markTouched(): void;
+
+  // ---- validation
+  /** The message to show, or '' when valid. */
+  get validationMessage(): string;
+  /** Disabled by its own attribute or by a disabled fieldset. */
+  get isDisabled(): boolean;
+  get willValidate(): boolean;
+  get validity(): XoValidity;
+  /** Set your own error (cross-field rules, server errors). An empty string clears it. */
+  setCustomValidity(message: string | null | undefined): void;
+  /** True when valid (or not validated); otherwise fires a cancelable `invalid` event and returns false. */
+  checkValidity(): boolean;
+  /** Like `checkValidity`, and on failure marks the control touched and focuses `focusTarget`. */
+  reportValidity(): boolean;
+  /** The element inside that takes focus (and anchors the validation bubble). */
+  get focusTarget(): HTMLElement | null;
+
+  // ---- reset
+  /** Back to the initial value, untouched. The form calls this on reset. */
+  reset(): void;
+  /** Make the current value the new baseline, as after a successful save: `dirty` becomes false. */
+  markPristine(): void;
+
+  // ---- form-associated callbacks
+  formResetCallback(): void;
+  formDisabledCallback(disabled: boolean): void;
+  formStateRestoreCallback(state: any): void;
+  /** The form this control belongs to (through ElementInternals, else the closest `<form>`). */
+  get form(): HTMLFormElement | null;
+}

package/src/element.d.ts

@@ -0,0 +1,57 @@
+// Types for XoElement and define.
+import type { Signal } from './signals.js';
+import type { TemplateResult } from './html.js';
+
+/** The attribute types a prop can have; the attribute is converted to it (Boolean: present and not "false"). */
+export type XoPropType = StringConstructor | NumberConstructor | BooleanConstructor;
+
+/**
+ * Light DOM base element.
+ *
+ * `static props` declares attributes that are also properties and signals; `define` installs the accessors, so TypeScript needs to be told about them.
+ * Declare each one in the subclass with `declare` (it emits nothing):
+ *
+ *     class UserCard extends XoElement {
+ *       static props = { name: String, age: Number };
+ *       declare name: string;
+ *       declare age: number;
+ *       render() { return html`<h3>${() => this.name}</h3>`; }
+ *     }
+ *     define('user-card', UserCard);
+ */
+export class XoElement extends HTMLElement {
+  /** Attributes <-> signals. The attribute is the kebab-case of the name (`maxSize` is `max-size`). */
+  static props: Record<string, XoPropType>;
+  static get observedAttributes(): string[];
+
+  constructor();
+
+  /** The signal behind a prop (reading `this.name` already tracks it). */
+  _sig(name: string): Signal<any>;
+
+  attributeChangedCallback(attr: string, oldValue: string | null, value: string | null): void;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+
+  /**
+   * Implement it only if the element OWNS its content: the result is rendered into the element when it connects.
+   * To enhance server-rendered HTML in place, implement `connected()` instead.
+   */
+  render?(): TemplateResult | null | undefined | void;
+  /** Runs after `render()` when the element is connected. */
+  connected?(): void;
+  /** Runs after the element's effects and rendering were disposed, when it is disconnected. */
+  disconnected?(): void;
+
+  /** Resolves with the element when its children are there: at once once the document is parsed, else after the parser reached the end. Await it in `connected()`. */
+  ready(): Promise<this>;
+
+  /** A side effect bound to this element's lifetime: disposed on disconnect. */
+  effect(fn: () => void | (() => void)): void;
+
+  /** Dispatch a bubbling, composed CustomEvent. */
+  emit<T = unknown>(name: string, detail?: T): void;
+}
+
+/** Register a custom element (idempotent: a tag that is already defined is left alone). The tag must contain a hyphen. */
+export function define(tag: string, cls: typeof XoElement): void;

package/src/html.d.ts

@@ -0,0 +1,21 @@
+// Types for the `html` template and `render` of @xoong/core.
+
+/** What `html` returns: the strings and values of one template call. Nothing touches the DOM until `render` (or an element's `render()`) uses it. */
+export class TemplateResult {
+  constructor(strings: TemplateStringsArray, values: unknown[]);
+  readonly strings: TemplateStringsArray;
+  readonly values: unknown[];
+}
+
+/**
+ * Tagged template with fine-grained reactive bindings (Light DOM, no virtual DOM). A function in a child or attribute position is reactive.
+ *
+ *     html`<h3 class=${() => cls.value}>${() => name.value}</h3><button @click=${() => save()}>Save</button>`
+ *
+ * `name=${v}` sets an attribute (null/false removes it), `?name=${v}` a boolean attribute, `.name=${v}` a DOM property, `@event=${fn}` a listener,
+ * `style:--x=${v}` a CSS custom property through the CSS object model.
+ */
+export function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
+
+/** Render a template result into `container`, replacing its children. Returns the dispose function. */
+export function render(result: TemplateResult, container: Element | DocumentFragment): () => void;

package/src/index.d.ts

@@ -0,0 +1,10 @@
+// Types for @xoong/core. The runtime is plain JavaScript; these files describe it (one per source module).
+export { signal, computed, effect, batch, untracked, disposeComputed, Signal } from './signals.js';
+export type { ReadonlySignal } from './signals.js';
+export { html, render, TemplateResult } from './html.js';
+export { XoElement, define } from './element.js';
+export type { XoPropType } from './element.js';
+export { XoControl } from './control.js';
+export type { XoValidity } from './control.js';
+export { text, setTextProvider } from './text.js';
+export type { TextProvider } from './text.js';

package/src/signals.d.ts

@@ -0,0 +1,39 @@
+// Types for @xoong/core/signals. The runtime is plain JavaScript; this file describes it.
+
+/** A readable reactive value. Reading `value` inside a computed, an effect or a template function is tracked. */
+export interface ReadonlySignal<T> {
+  readonly value: T;
+  /** Read without tracking. */
+  peek(): T;
+}
+
+/** A writable reactive value. Writing a different value (by `Object.is`) runs the effects that read it. */
+export class Signal<T> implements ReadonlySignal<T> {
+  constructor(value: T);
+  get value(): T;
+  set value(next: T);
+  /** Read without tracking. */
+  peek(): T;
+  /** Set the value from the previous one. */
+  update(fn: (previous: T) => T): void;
+}
+
+export function signal<T>(value: T): Signal<T>;
+
+/** A value derived from other signals; it recomputes lazily, when something it read has changed. */
+export function computed<T>(fn: () => T): ReadonlySignal<T>;
+
+/** Let a computed release its subscriptions when its owner is discarded. */
+export function disposeComputed(c: { detach?: () => void }): void;
+
+/**
+ * Run `fn` now and again whenever a signal it read changes. `fn` may return a cleanup callback, which runs before the next run and on dispose.
+ * Returns the dispose function. For side effects only: never fetch data in an effect, declare the operation on a view instead.
+ */
+export function effect(fn: () => void | (() => void)): () => void;
+
+/** Group writes: effects run once, after the outermost batch ends. Returns what `fn` returns. */
+export function batch<T>(fn: () => T): T;
+
+/** Read signals inside `fn` without subscribing to them. */
+export function untracked<T>(fn: () => T): T;

package/src/syntax.d.ts

@@ -0,0 +1,14 @@
+// Types for @xoong/core/syntax: the names of xoong's declarative HTML syntax (what `xoong check` validates against).
+
+/** Attributes understood inside `<xo-view>`. */
+export const XO_ATTRIBUTES: string[];
+/** Custom elements shipped by xoong. */
+export const XO_ELEMENTS: string[];
+/** Attributes that come with @xoong/ui (the admin set). */
+export const XO_UI_ATTRIBUTES: string[];
+/** Elements that come with @xoong/ui. */
+export const XO_UI_ELEMENTS: string[];
+/** Attributes of @xoong/controls and @xoong/richtext. */
+export const XO_CONTROL_ATTRIBUTES: string[];
+/** Elements of @xoong/controls and @xoong/richtext. */
+export const XO_CONTROL_ELEMENTS: string[];

package/src/syntax.js

@@ -15,5 +15,5 @@ export const XO_UI_ATTRIBUTES = ['xo-open', 'xo-close', 'xo-route', 'xo-layout',
 export const XO_UI_ELEMENTS = ['xo-table', 'xo-form', 'xo-dialog', 'xo-toast', 'xo-router'];
 
 /** Attributes and elements of @xoong/controls and @xoong/richtext. */
-export const XO_CONTROL_ATTRIBUTES = ['xo-tab', 'xo-menu-trigger', 'xo-tooltip'];
-export const XO_CONTROL_ELEMENTS = ['xo-tabs', 'xo-menu', 'xo-combobox', 'xo-tags', 'xo-richtext', 'xo-carousel', 'xo-switch', 'xo-date', 'xo-time', 'xo-slider', 'xo-stepper', 'xo-password', 'xo-copy', 'xo-image'];
+export const XO_CONTROL_ATTRIBUTES = ['xo-tab', 'xo-menu-trigger', 'xo-tooltip', 'xo-consent-open'];
+export const XO_CONTROL_ELEMENTS = ['xo-tabs', 'xo-menu', 'xo-combobox', 'xo-tags', 'xo-richtext', 'xo-carousel', 'xo-switch', 'xo-date', 'xo-time', 'xo-slider', 'xo-stepper', 'xo-password', 'xo-copy', 'xo-image', 'xo-theme-toggle', 'xo-accordion', 'xo-popover', 'xo-consent', 'xo-file', 'xo-command', 'xo-chart', 'xo-range-slider', 'xo-segmented', 'xo-split-button', 'xo-textarea', 'xo-stat', 'xo-otp', 'xo-avatar', 'xo-avatars', 'xo-progress', 'xo-spinner', 'xo-steps', 'xo-inline-edit'];

package/src/text.d.ts

@@ -0,0 +1,14 @@
+// Types for the text hook of @xoong/core.
+
+/** A provider answers with the translated message for a key, or undefined when it has none. `@xoong/i18n` installs one. */
+export type TextProvider = (key: string, args?: Record<string, any>) => string | undefined;
+
+/** Install (or remove, with null) the provider that translates the framework's own texts. */
+export function setTextProvider(fn: TextProvider | null): void;
+
+/**
+ * The text for a stable key such as "xoong.table.next": the provider's translation, else the English `fallback`
+ * (`{name}` placeholders and the simple `{n, plural, one {# thing} other {# things}}` form are filled from `args`).
+ * Applications use `t()` from @xoong/i18n instead.
+ */
+export function text(key: string, fallback: string, args?: Record<string, any>): string;