@xoong/ui 0.0.0-stage → 0.0.34

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duong Tran Xuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @xoong/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The admin set of xoong: design tokens in cascade layers, `<xo-table>`, a form generated from the request schema, `<xo-dialog>`, toasts, confirm dialogs and `<xo-router>`.
+
+## Install
+
+```bash
+npm install @xoong/ui
+```
+
+## Use
+
+```js
+import '@xoong/ui';
+```
+```html
+<link rel="stylesheet" href="/@xoong/ui/src/xoong.css">
+<link rel="stylesheet" href="/@xoong/ui/src/mist.css">   <!-- optional: the Mist look (the Rainlet design system), one self-sufficient file -->
+<xo-view get="listPeople">
+  <xo-table columns="name,email:E-mail,role" sortable filters="name:Search" page-size="10"></xo-table>
+</xo-view>
+```
+
+## More
+
+* Documentation and demos: https://github.com/fpt-duongtx/xoong#readme
+* Source: https://github.com/fpt-duongtx/xoong/tree/main/packages/ui
+* All packages share one version number and are released together: https://github.com/fpt-duongtx/xoong/releases
+* xoong is a working prototype (0.0.x): the HTML syntax is still Draft.
+
+MIT licence.

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@xoong/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.34",
+  "description": "xoong admin set: xoong.css tokens, <xo-table>, <xo-form>, <xo-dialog>, toast, confirm and a declarative History-API router. Depends on @xoong/core, @xoong/data and @xoong/forms.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./table": "./src/table.js",
+    "./form": "./src/form.js",
+    "./dialog": "./src/dialog.js",
+    "./toast": "./src/toast.js",
+    "./router": "./src/router.js",
+    "./xoong.css": "./src/xoong.css",
+    "./mist.css": "./src/mist.css"
+  },
+  "sideEffects": true,
+  "license": "MIT",
+  "dependencies": {
+    "@xoong/core": "0.0.34",
+    "@xoong/data": "0.0.34",
+    "@xoong/forms": "0.0.34"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "xoong",
+    "web-framework",
+    "openapi",
+    "custom-elements"
+  ],
+  "author": "Duong Tran Xuan <duongtx1505@icloud.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fpt-duongtx/xoong.git",
+    "directory": "packages/ui"
+  },
+  "bugs": {
+    "url": "https://github.com/fpt-duongtx/xoong/issues"
+  },
+  "homepage": "https://github.com/fpt-duongtx/xoong#readme",
+  "types": "./src/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12"
+  }
+}

package/src/confirm.js

@@ -0,0 +1,53 @@
+// @ts-check
+/**
+ * The confirmation dialog behind `xo-confirm="Delete {title}?"` (and the leave-page question of a dirty form): a native modal <dialog>,
+ * created on first use. Escape or Cancel answers no, Confirm answers yes; the focus starts on Cancel, the safe choice for a
+ * destructive action. Replaces the browser's confirm() as soon as @xoong/ui is imported.
+ *
+ *   // from the package entry: confirm(message, { ok, cancel }) resolves true or false
+ *   if (await confirm('Discard the draft?', { ok: 'Discard' })) ...
+ */
+import { setConfirm } from '@xoong/data/view';
+import { text } from '@xoong/core';
+
+/** The button texts; replace them for another wording or language. */
+export const labels = { ok: 'Confirm', cancel: 'Cancel' };
+
+/** @type {HTMLDialogElement | null} */
+let dialog = null;
+
+/** @param {string} message @param {{ ok?: string, cancel?: string }} [options] @returns {Promise<boolean>} */
+export function confirm(message, options = {}) {
+  return new Promise((resolve) => {
+    dialog?.remove();
+    const d = document.createElement('dialog');
+    d.className = 'xo-confirm';
+    d.setAttribute('aria-labelledby', 'xo-confirm-text');
+    const body = document.createElement('p');
+    body.id = 'xo-confirm-text';
+    body.textContent = message;
+    const cancel = document.createElement('button');
+    cancel.type = 'button';
+    cancel.textContent = options.cancel ?? (labels.cancel === 'Cancel' ? text('xoong.confirm.cancel', 'Cancel') : labels.cancel);
+    const ok = document.createElement('button');
+    ok.type = 'button';
+    ok.className = 'xo-confirm-ok';
+    ok.textContent = options.ok ?? (labels.ok === 'Confirm' ? text('xoong.confirm.ok', 'Confirm') : labels.ok);
+    const row = document.createElement('div');
+    row.className = 'xo-confirm-actions';
+    row.append(cancel, ok);
+    d.append(body, row);
+    let answer = false;
+    const finish = () => { d.remove(); if (dialog === d) dialog = null; resolve(answer); };
+    cancel.addEventListener('click', () => { answer = false; d.close ? d.close() : finish(); });
+    ok.addEventListener('click', () => { answer = true; d.close ? d.close() : finish(); });
+    d.addEventListener('close', finish); // Escape closes a native dialog: that answers no
+    d.addEventListener('cancel', () => { answer = false; });
+    document.body.append(d);
+    dialog = d;
+    if (d.showModal) d.showModal(); else d.setAttribute('open', ''); // DOMs without <dialog> support (tests)
+    cancel.focus();
+  });
+}
+
+setConfirm((message) => confirm(message));

package/src/dialog.js

@@ -0,0 +1,71 @@
+// @ts-check
+/**
+ * <xo-dialog id="add"> ...content... </xo-dialog>
+ * <button xo-open="#add">Add</button>        opens it (modal, on a native <dialog>)
+ * <button xo-close>Cancel</button>           closes the dialog it is in
+ *
+ * The dialog also closes when a form inside it succeeds (`xo-done`). Escape, focus trapping and the
+ * backdrop come from the browser's <dialog>; nothing is reimplemented.
+ */
+import { XoElement, define } from '@xoong/core';
+
+class XoDialog extends XoElement {
+  /** @type {HTMLDialogElement | null} */ #dialog = null;
+
+  connected() {
+    // Children may not exist yet when the element is connected (HTML parser): wrap them once the tree is complete.
+    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', () => this.#wrap(), { once: true });
+    else queueMicrotask(() => this.#wrap());
+  }
+
+  #wrap() {
+    if (this.#dialog || !this.isConnected) return;
+    const dialog = document.createElement('dialog');
+    dialog.append(...this.childNodes);
+    this.append(dialog);
+    this.#dialog = dialog;
+    this.addEventListener('xo-done', () => this.close());
+  }
+
+  get dialog() { return this.#dialog; }
+  show() {
+    const d = this.#dialog;
+    if (!d || d.open) return;
+    if (d.showModal) d.showModal(); else d.setAttribute('open', ''); // DOMs without <dialog> support (tests)
+  }
+  /** Open it and wait for the answer: resolves with the `returnValue` when it closes (`xo-close value="ok"`, `close('ok')`, or '' for Escape and Cancel). */
+  open() {
+    const d = this.#dialog;
+    if (!d) return Promise.resolve('');
+    return new Promise((resolve) => {
+      d.addEventListener('close', () => resolve(d.returnValue), { once: true });
+      this.show();
+    });
+  }
+  close(/** @type {string | undefined} */ value) {
+    const d = this.#dialog;
+    if (!d?.open) return;
+    if (d.close) d.close(value); else { d.returnValue = value ?? ''; d.removeAttribute('open'); d.dispatchEvent(new Event('close')); }
+  }
+}
+define('xo-dialog', XoDialog);
+
+// One delegated listener for the page (the module runs once): buttons do not need wiring.
+{
+  document.addEventListener('click', (event) => {
+    const target = /** @type {Element} */ (event.target);
+    const opener = target.closest?.('[xo-open]');
+    if (opener) {
+      const selector = opener.getAttribute('xo-open') ?? '';
+      try {
+        const dialog = document.querySelector(selector);
+        if (dialog instanceof XoDialog) dialog.show();
+        else console.error(`xoong: xo-open="${selector}" matches no <xo-dialog>`);
+      } catch {
+        console.error(`xoong: xo-open="${selector}" is not a valid selector (use an id such as #add)`);
+      }
+    }
+    const closer = target.closest?.('[xo-close]');
+    if (closer) closer.closest('xo-dialog')?.close(closer.getAttribute('value') ?? undefined);
+  });
+}

package/src/form.js

@@ -0,0 +1,148 @@
+// @ts-check
+/**
+ * <xo-form op="updateArticle" submit="Save"></xo-form>: the markup of a form, written for you from the operation's request schema
+ * (`bodySchema` in operations.json). The same binder as for a hand-written `<form xo-submit>` does the rest (ADR-0009): prefill, validation,
+ * dirty tracking, errors, payload. Nothing here is a second code path: it only emits the markup you would have written.
+ *
+ *  - simple fields: one labelled control; enums are selects, booleans checkboxes, formats choose the input type;
+ *  - nested objects: a fieldset; arrays of values or objects: rows with add, remove, up and down buttons;
+ *  - unions (oneOf with a tag): one "Add <variant>" button per variant, and each row shows the fields of its variant;
+ *  - hints (`xoong.hints.json` / the schema): `label`, `hint`, `placeholder`, `widget` (textarea, password, url, email, color, date, datetime,
+ *    or the tag of any custom element that extends XoControl), `order`, `readOnly`, `hidden` (kept in the model, not drawn), `group` (a fieldset
+ *    with a legend). `title` / `description` of the schema are the label and the hint.
+ * Without a `bodySchema` (a multipart body) the flat `bodyFields` are used as before.
+ */
+import { defineTemplate } from '@xoong/data/view';
+
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+const label = (name) => /^[a-z]{2}(-[A-Za-z]{2})?$/.test(name) ? String(name).replace(/^[a-z]{2}/, (c) => c.toUpperCase()) : String(name).replace(/[_-]+/g, ' ').replace(/([a-z])([A-Z])/g, '$1 $2').replace(/^./, (c) => c.toUpperCase());
+const TYPES = { email: 'email', password: 'password', date: 'date', 'date-time': 'datetime-local', uri: 'url', url: 'url' }; // the flat generator (bodyFields only)
+const TYPE_OF_WIDGET = { password: 'password', url: 'url', email: 'email', color: 'color', date: 'date', datetime: 'datetime-local', time: 'time' };
+const PRIMITIVE = new Set(['string', 'integer', 'number', 'boolean']);
+
+/** Fields in display order: by `order`, then as declared. Hidden ones are not drawn. */
+function ordered(props) {
+  return Object.entries(props ?? {})
+    .map(([name, node], i) => ({ name, node, i }))
+    .filter(({ node }) => !node.hidden && !node.readOnly)
+    .sort((a, b) => (a.node.order ?? 1e9) - (b.node.order ?? 1e9) || a.i - b.i);
+}
+
+/** One simple control with its label, hint and widget. */
+function control(node, name, text) {
+  const attrs = `name="${esc(name)}"${node.readOnly ? ' readonly' : ''}`;
+  const widget = node.widget;
+  let input;
+  if (widget && widget.includes('-')) input = `<${esc(widget)} ${attrs}></${esc(widget)}>`; // a custom XoControl: the binder gives it its schema node, hints and the form model
+  else if (widget === 'textarea') input = `<textarea ${attrs}></textarea>`;
+  else if (node.enum || widget === 'select') input = `<select ${attrs}></select>`;
+  else if (node.t === 'boolean') input = `<input type="checkbox" ${attrs}>`;
+  else input = `<input${TYPE_OF_WIDGET[widget] ? ` type="${TYPE_OF_WIDGET[widget]}"` : ''} ${attrs}>`;
+  const hint = node.description ? `<small class="xo-hint">${esc(node.description)}</small>` : '';
+  const caption = `<span>${esc(node.title ?? text)}</span>`;
+  return `<label class="xo-field">${node.t === 'boolean' ? `${input}${caption}` : `${caption}${input}`}${hint}</label>`;
+}
+
+/** The fields of an object node, grouped by `group`. `rowPath(name)` gives the name a child gets. */
+function fields(node, path, depth, skip = []) {
+  const groups = new Map();
+  for (const f of ordered(node.props)) {
+    if (skip.includes(f.name)) continue;
+    const key = f.node.group ?? '';
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(f);
+  }
+  return [...groups].map(([group, list]) => {
+    const html = list.map((f) => field(f.node, path ? `${path}.${f.name}` : f.name, f.name, depth)).join('');
+    return group ? `<fieldset class="xo-group"><legend>${esc(group)}</legend>${html}</fieldset>` : html;
+  }).join('');
+}
+
+/** The heading of an array row: its number and, for unions, the variant. */
+const rowTitle = (text) => `<span class="xo-row-title"><span class="xo-row-no">{$n}.</span>${text ? ` <strong>${esc(text)}</strong>` : ''}</span>`;
+
+/** Buttons of an array row. */
+const rowButtons = (path) => `<span class="xo-row-actions"><span class="xo-handle" xo-drag="${path}" aria-hidden="true">⋮⋮</span><button type="button" xo-move="${path}:up" aria-label="Move up" xo-t="aria-label:xoong.form.moveUp">↑</button><button type="button" xo-move="${path}:down" aria-label="Move down" xo-t="aria-label:xoong.form.moveDown">↓</button><button type="button" xo-remove="${path}" aria-label="Remove" xo-t="aria-label:xoong.form.remove">×</button></span>`;
+
+function field(node, path, name, depth) {
+  const text = label(name);
+  if (node.widget?.includes('-') && !PRIMITIVE.has(node.t)) return control(node, path, text); // a custom control owns a whole array, object or union (tags, a block picker)
+  if (PRIMITIVE.has(node.t)) return control(node, path, text);
+  if (node.t === 'object') return `<fieldset class="xo-object"><legend>${esc(node.title ?? text)}</legend>${fields(node, path, depth)}</fieldset>`;
+  if (node.t === 'array') return array(node, path, text, depth);
+  if (node.t === 'union') return `<fieldset class="xo-object"><legend>${esc(node.title ?? text)}</legend>${variants(node, path, depth)}</fieldset>`;
+  return ''; // `any`: not drawn
+}
+
+/** A union that is a plain property: choose the variant, then show its fields. */
+function variants(node, path, depth) {
+  const key = node.key;
+  const options = Object.keys(node.map).map((v) => `<option value="${esc(v)}">${esc(label(v))}</option>`).join('');
+  return `<label class="xo-field"><span>${esc(label(key))}</span><select name="${esc(path)}.${esc(key)}"><option value=""></option>${options}</select></label>`
+    + Object.entries(node.map).map(([v, n]) => `<div xo-if="${esc(path)}.${esc(key)}=${esc(v)}">${fields(n, path, depth, [key])}</div>`).join('');
+}
+
+/** An array: a row per item with its controls and buttons, and add buttons below. */
+function array(node, path, text, depth) {
+  const item = node.items;
+  const at = `{$i${depth}}`; // the row index in names; the generator knows the nesting depth, so inner arrays can name outer rows
+  const rowPath = `${path}[${at}]`;
+  let row;
+  let adds;
+  if (item.t === 'union') {
+    row = Object.entries(item.map).map(([v, n]) => `<div class="xo-variant" xo-if="type=${esc(v)}">${rowTitle(n.title ?? label(v))}${fields(n, rowPath, depth + 1, [item.key])}</div>`).join('');
+    adds = Object.keys(item.map).map((v) => `<button type="button" xo-add="${esc(path)}" xo-with="${esc(item.key)}=${esc(v)}">Add ${esc(label(item.map[v].title ?? v))}</button>`).join('');
+  } else {
+    row = PRIMITIVE.has(item.t) ? control({ ...item, title: item.title ?? `${text} item` }, rowPath, text) : item.t === 'object' ? rowTitle(item.title ?? '') + fields(item, rowPath, depth + 1) : '';
+    adds = `<button type="button" xo-add="${esc(path)}" xo-t="xoong.form.add">Add</button>`;
+  }
+  return `<fieldset class="xo-array"><legend>${esc(node.title ?? text)}</legend>${node.description ? `<small class="xo-hint">${esc(node.description)}</small>` : ''}`
+    + `<div class="xo-row" xo-each="${esc(path)}">${row}${rowButtons(rowPath)}</div><div class="xo-array-add">${adds}</div></fieldset>`;
+}
+
+defineTemplate('xo-form', (el, { client }) => {
+  const ref = el.getAttribute('op') ?? '';
+  const op = client.op(ref); // unknown operations throw with the closest valid name
+  const form = document.createElement('form');
+  form.setAttribute('xo-submit', ref);
+  form.className = 'xo-form';
+  if (op.bodySchema) { // the schema-driven generator: nested objects, arrays, unions, hints
+    const submit = el.getAttribute('submit');
+    form.innerHTML = fields(op.bodySchema, '', 0) + (submit ? `<button class="xo-submit">${esc(submit)}</button>` : '<button class="xo-submit" xo-t="xoong.form.save">Save</button>');
+    return form;
+  }
+  const flat = op.bodyFields ?? [];
+  const missing = (op.bodySkipped ?? []).filter((s) => s.required);
+  if (missing.length) console.warn(`xoong: <xo-form op="${ref}"> cannot generate the required field(s) ${missing.map((m) => `${m.name} (${m.type})`).join(', ')}: the server will refuse this form. Write those fields by hand or wait for nested form support.`);
+  if (!flat.length) console.error(`xoong: <xo-form op="${ref}">: the request body has no simple fields to generate (see docs/admin.md)`);
+  for (const f of flat) {
+    const wrap = document.createElement('label');
+    wrap.className = 'xo-field';
+    const text = document.createElement('span');
+    text.textContent = f.title ?? label(f.name);
+    let input;
+    if (f.enum) {
+      input = document.createElement('select');
+      for (const v of f.required ? f.enum : ['', ...f.enum]) {
+        const option = document.createElement('option');
+        option.value = option.textContent = String(v);
+        input.append(option);
+      }
+    } else {
+      input = document.createElement('input');
+      input.type = f.type === 'file' ? 'file' : f.type === 'boolean' ? 'checkbox' : f.type === 'integer' || f.type === 'number' ? 'number' : TYPES[f.format] ?? 'text';
+      if (f.type === 'number') input.step = 'any';
+      if (f.maxLength) input.maxLength = f.maxLength;
+      if (input.type === 'text' || input.type === 'email') input.autocomplete = 'off';
+    }
+    input.name = f.name;
+    if (f.required && f.type !== 'boolean') input.required = true;
+    if (f.type === 'boolean') wrap.append(input, text); else wrap.append(text, input);
+    form.append(wrap);
+  }
+  const button = document.createElement('button');
+  button.className = 'xo-submit';
+  button.textContent = el.getAttribute('submit') || 'Save';
+  form.append(button);
+  return form;
+});

package/src/index.d.ts

@@ -0,0 +1,33 @@
+export interface RouteLocation {
+  /** The path without the router's `base`, e.g. "/users/3". */
+  path: string;
+  /** Path parameters of the matched route: { id: "3" }. */
+  params: Record<string, string>;
+  query: URLSearchParams;
+  /** Path, query and hash as in the address bar. */
+  url: string;
+  /** The matched route template, or null when nothing matched (a 404). */
+  route: { pattern: string; layout: string | null; title: string; template: HTMLTemplateElement } | null;
+}
+
+/** true or undefined: continue. false: cancel. A string: redirect to that path. */
+export type GuardResult = boolean | string | void;
+
+/** What a confirmation is about: an `xo-confirm` action, or leaving a page that has unsaved changes. */
+export interface ConfirmContext { kind: 'action' | 'leave'; element?: Element; forms?: Element[] }
+/** Replace the native confirmation dialog (for `xo-confirm` and the leave guard) with your own; resolve to true to go on. */
+export function setConfirm(fn: (message: string, context?: ConfirmContext) => boolean | Promise<boolean>): void;
+/** Ask with the dialog that is installed. */
+export function confirm(message: string, options?: { ok?: string; cancel?: string }): Promise<boolean>;
+/** Show a notice in <xo-toast>. */
+export const toast: { show(notice: { message: string; kind?: string; action?: { label: string; run: () => unknown }; timeout?: number }): void };
+
+export const router: {
+  /** Go to a path relative to the base. Resolves with true when the navigation happened. */
+  navigate(path: string, options?: { replace?: boolean }): Promise<boolean>;
+  /** Run before every navigation; returns a function that removes the guard. */
+  guard(fn: (to: RouteLocation, from: RouteLocation | null) => GuardResult | Promise<GuardResult>): () => void;
+  /** Run before leaving the current location (links, back/forward, navigate); return false to stay. */
+  beforeNavigate(fn: (to: RouteLocation, from: RouteLocation | null, type: 'link' | 'api' | 'popstate') => boolean | void | Promise<boolean | void>): () => void;
+  readonly current: RouteLocation | null;
+};

package/src/index.js

@@ -0,0 +1,10 @@
+// Importing the package registers every element of the admin set.
+import '@xoong/forms'; // every <form xo-submit> (and <xo-form>) uses the schema-driven form model
+import './table.js';
+import './form.js';
+import './dialog.js';
+import './toast.js';
+export { router } from './router.js';
+export { toast } from './toast.js';
+export { confirm, labels as confirmLabels } from './confirm.js';
+export { setConfirm } from '@xoong/data/view';