@webjsdev/core 0.7.8 → 0.7.10

package/index.d.ts

@@ -61,7 +61,7 @@ export { renderToString, renderToStream } from './src/render-server.js';
 export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
 export { notFound, redirect, isNotFound, isRedirect } from './src/nav.js';
-export { expose, getExposed } from './src/expose.js';
+export { expose, getExposed, validateInput } from './src/expose.js';
 export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';

package/index.js

@@ -15,7 +15,7 @@ export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
 export { notFound, redirect, isNotFound, isRedirect } from './src/nav.js';
 export { cspNonce, setCspNonceProvider } from './src/csp-nonce.js';
-export { expose, getExposed } from './src/expose.js';
+export { expose, getExposed, validateInput } from './src/expose.js';
 export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "type": "module",
   "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
   "types": "./index.d.ts",

package/src/expose.js

@@ -22,10 +22,22 @@
  *   - For methods with a body (POST/PUT/PATCH/DELETE), the parsed JSON body
  *     is merged on top of params/query. The function receives ONE argument:
  *     the merged object.
- *   - If `opts.validate` is provided, it runs BEFORE the function and can
- *     transform / reject the input. Throw to fail (→ 400 response). Return
- *     value replaces the input. Works cleanly with zod, valibot, or any
- *     parser that throws: `expose('...', fn, { validate: Schema.parse })`.
+ *   - If `opts.validate` is provided, it runs BEFORE the function on EVERY
+ *     call path (the REST path here AND the internal RPC path), so a single
+ *     validator declared once guards both. The framework calls `validate(input)`
+ *     and interprets the return (see the validator contract below):
+ *       - a `{ success: true, data? }` envelope passes (the action receives
+ *         `data` when present, else the original input);
+ *       - a `{ success: false, fieldErrors, message? }` envelope FAILS with a
+ *         structured field-error result (422), without calling the action;
+ *       - a THROW fails (→ 400 on REST, sanitized error on RPC), preserving the
+ *         classic `Schema.parse`-style contract;
+ *       - any OTHER returned plain value is treated as the transformed input
+ *         (back-compat with the `validate: Schema.parse` transform style).
+ *     The zod adapter is three lines and keeps the framework zod-free:
+ *       `validate: (i) => { const r = Schema.safeParse(i);
+ *          return r.success ? { success: true, data: r.data }
+ *            : { success: false, fieldErrors: r.error.flatten().fieldErrors }; }`
  *   - Return value becomes a JSON `Response`; throw or return a `Response`
  *     directly for full control.
  *
@@ -84,6 +96,84 @@ function normaliseCors(c) {
   };
 }
 
+/**
+ * Attach an input validator to a server action WITHOUT exposing it as a REST
+ * endpoint. The validator runs SERVER-SIDE before the action body on BOTH call
+ * paths: the internal RPC path (a client component importing the action) AND
+ * the `expose()` REST path (if the action is also exposed). This is the shared,
+ * declare-once validation surface (#245).
+ *
+ * It reuses the EXACT same `__webjsHttp` storage `expose()` writes, so the
+ * action index's `getExposed(fn)` already surfaces the validator with no new
+ * plumbing. The action stays a plain callable function (a direct unit-test
+ * import still works, just without the framework running validate).
+ *
+ * If the action is already `expose()`d, prefer passing `{ validate }` to
+ * `expose()` directly; calling both keeps the LAST validator attached.
+ *
+ * ```js
+ * // actions/posts.server.js
+ * 'use server';
+ * import { validateInput } from '@webjsdev/core';
+ *
+ * export const createPost = validateInput(
+ *   async ({ title }) => { ... },
+ *   (input) => {
+ *     const errs = {};
+ *     if (!input?.title?.trim()) errs.title = 'Title is required';
+ *     return Object.keys(errs).length
+ *       ? { success: false, fieldErrors: errs }
+ *       : { success: true };
+ *   },
+ * );
+ * ```
+ *
+ * The validator contract (the framework calls `validate(input)`):
+ *   - returns `{ success: true, data? }` → valid; the action is called with
+ *     `data` if present, else the original input;
+ *   - returns `{ success: false, fieldErrors, message? }` (an object with a
+ *     boolean `success` of `false`, or with a `fieldErrors`) → FAILED; the
+ *     framework returns a structured `ActionResult`
+ *     `{ success: false, fieldErrors, error: message?, status: 422 }` without
+ *     calling the action body;
+ *   - THROWS → mapped to a sanitized failure result (the classic
+ *     `Schema.parse` contract);
+ *   - returns ANY OTHER plain value → treated as the validated/coerced input
+ *     and passed to the action (the `validate: Schema.parse` transform style).
+ *
+ * Disambiguation: a return is a result-envelope ONLY when it is an object with
+ * a boolean `success` property OR a `fieldErrors` property; otherwise it is a
+ * transformed input value. Caveat: if your validator returns the input
+ * VERBATIM (the bare-transform style) and that input can itself carry a
+ * `success` boolean or a `fieldErrors` key, it would be misread as an envelope.
+ * Return the explicit `{ success: true, data }` envelope in that case (the zod
+ * adapter and the recommended hand-rolled form already do, so they never
+ * collide).
+ *
+ * Server-side only; import inside `.server.{js,ts}` files. The bare
+ * `@webjsdev/core` specifier resolves to the browser entry, which excludes
+ * `validateInput` (like `expose`), so an import from client-bound code reads
+ * `undefined`. The validator itself lives in the `.server` file and never
+ * reaches the client.
+ *
+ * @template {Function} F
+ * @param {F} fn the async action implementation
+ * @param {(input: any) => any} validate the validator (a plain function or a
+ *   zod-`safeParse` adapter)
+ * @returns {F} the same function, tagged with the validator
+ */
+export function validateInput(fn, validate) {
+  if (typeof fn !== 'function') {
+    throw new Error('validateInput(): first argument must be the action function');
+  }
+  if (typeof validate !== 'function') {
+    throw new Error('validateInput(): second argument must be a validator function');
+  }
+  const existing = /** @type any */ (fn).__webjsHttp || {};
+  /** @type any */ (fn).__webjsHttp = { ...existing, validate };
+  return fn;
+}
+
 /** @param {unknown} fn */
 export function getExposed(fn) {
   return fn && typeof fn === 'function' ? /** @type any */ (fn).__webjsHttp || null : null;

package/src/metadata.d.ts

@@ -152,6 +152,14 @@ export type AppleWebAppMetadata =
  */
 export type JsonLd = Record<string, unknown>;
 
+/**
+ * A `metadata.preconnect` / `metadata.dnsPrefetch` hint. A bare URL string,
+ * or an object form. `crossorigin` (preconnect only) emits the `crossorigin`
+ * attribute; `true` / `''` -> a bare `crossorigin`, a string -> its value
+ * (e.g. `'anonymous'`, `'use-credentials'`).
+ */
+export type PreconnectHint = string | { url: string; crossorigin?: string | boolean };
+
 /** A `metadata.preload` link descriptor (emitted as `<link rel="preload">`). */
 export interface PreloadDescriptor {
   href: MetadataUrl;
@@ -247,6 +255,23 @@ export interface Metadata {
   /** `<link rel="preload">` hints (fonts, images, etc.). */
   preload?: PreloadDescriptor[];
 
+  /**
+   * `<link rel="preconnect">` hints: warm DNS + TLS + TCP to a cross-origin
+   * the page is about to talk to (an API host, a font / image CDN). Each
+   * entry is a URL string or `{ url, crossorigin? }` (a font CDN needs
+   * `crossorigin`). A single value or an array. webjs ALSO auto-emits one
+   * preconnect to the resolved vendor CDN origin for an unpinned app (deduped
+   * against an author-declared one).
+   */
+  preconnect?: PreconnectHint | PreconnectHint[];
+
+  /**
+   * `<link rel="dns-prefetch">` hints: resolve a cross-origin's DNS ahead of
+   * use (a lighter-weight precursor to `preconnect`). A URL string,
+   * `{ url }`, or an array.
+   */
+  dnsPrefetch?: PreconnectHint | PreconnectHint[];
+
   /**
    * JSON-LD structured data (schema.org), emitted as one or more
    * `<script type="application/ld+json">` blocks in `<head>`. A single

package/src/testing.js

@@ -57,6 +57,60 @@ export async function fixture(template) {
   return el;
 }
 
+/**
+ * Server-render a template THEN hydrate it in the same browser session,
+ * awaiting the element's native `updateComplete` so the post-hydration DOM
+ * is observable deterministically.
+ *
+ * This is the SSR + hydrate entry, distinct from `fixture()`. `fixture()`
+ * server-renders and parses the HTML into the container, but it only waits
+ * two macrotasks and never awaits the real update cycle. `ssrFixture()`
+ * renders the SAME SSR markup (with DSD), lets the browser upgrade the
+ * custom element, then awaits the element's `updateComplete` promise (the
+ * actual render-cycle resolution), not a timer.
+ *
+ * **What it proves.** The SSR'd markup and the post-hydration DOM agree.
+ * Because the returned element is the live, hydrated element, a hydration
+ * mismatch (the server rendered one thing, the client rendered another) is
+ * observable: compare the SSR'd inner HTML against `el.innerHTML` /
+ * `el.shadowRoot.innerHTML` after this resolves and a divergence shows up.
+ *
+ * **When to use (AI hint):** Use `ssrFixture()` when the test is about the
+ * SSR-then-hydrate round-trip (does the server paint survive hydration, does
+ * a `.prop` decode back, does a signal-backed render match). Use the plain
+ * `fixture()` for a quick mount where the SSR-vs-hydrate distinction does not
+ * matter.
+ *
+ * Requires a real DOM (the WTR Chromium session). The component class must
+ * already be registered (the test imports its module, same as `fixture()`).
+ *
+ * @param {import('./html.js').TemplateResult | string} template
+ *   Either a `html\`…\`` result or a raw HTML string.
+ * @returns {Promise<Element>} The hydrated root element.
+ */
+export async function ssrFixture(template) {
+  const container = getContainer();
+  if (typeof template === 'string') {
+    container.innerHTML = template;
+  } else if (template && typeof template === 'object' && template._$webjs === 'template') {
+    const { renderToString } = await import('./render-server.js');
+    const html = await renderToString(template, { ssr: true });
+    container.innerHTML = html;
+  } else {
+    throw new Error('ssrFixture() expects an html`…` template or an HTML string');
+  }
+
+  const el = container.firstElementChild;
+  if (!el) throw new Error('ssrFixture() produced no element');
+
+  // Drive the real update cycle. The browser upgrades the SSR'd custom
+  // element on innerHTML assignment; its connectedCallback queues the first
+  // render. Awaiting the native updateComplete promise (not a timer) is the
+  // whole point: the test observes the post-hydration DOM deterministically.
+  await flushUpdate(el);
+  return el;
+}
+
 /**
  * Wait for a component's next render cycle to complete.
  *
@@ -65,17 +119,105 @@ export async function fixture(template) {
  * subscribes to, any change that triggers a re-render. The re-render
  * is async (microtask-batched), so you need to await before asserting.
  *
+ * Awaits the element's native `updateComplete` promise when present (the
+ * real render-cycle resolution), falling back to a microtask flush for a
+ * plain element that has no `updateComplete` (back-compatible).
+ *
  * @param {Element} el  The component element.
  * @returns {Promise<void>}
  */
 export async function waitForUpdate(el) {
-  // WebComponent batches via queueMicrotask, so two microtask yields
-  // is sufficient: one for the scheduling microtask, one for any
-  // cascading updates.
+  await flushUpdate(el);
+}
+
+/**
+ * Await the real update cycle of an element. For a WebComponent this awaits
+ * the native `updateComplete` promise; for anything else it yields two
+ * macrotasks (the legacy behaviour) so cascading updates settle.
+ *
+ * @param {Element} el
+ * @returns {Promise<void>}
+ */
+async function flushUpdate(el) {
+  const uc = el && /** @type {any} */ (el).updateComplete;
+  if (uc && typeof uc.then === 'function') {
+    await uc;
+    // A microtask yield lets any cascading child update flush too.
+    await Promise.resolve();
+    return;
+  }
   await new Promise((r) => setTimeout(r, 0));
   await new Promise((r) => setTimeout(r, 0));
 }
 
+/**
+ * Assert an element's subtree has no accessibility violations, using the
+ * axe-core engine in the real browser. OPT-IN: nothing calls this for you,
+ * it is never a forced gate.
+ *
+ * axe-core is a TEST-ONLY peer: it is imported dynamically here, so it is
+ * NOT a hard dependency of `@webjsdev/core`. An app that does not do a11y
+ * testing never needs it. Install it where you run the test:
+ * `npm install -D axe-core`.
+ *
+ * On a violation it throws an Error whose message lists each violation's id,
+ * impact, a short help string, and the failing nodes' selectors, so the test
+ * failure is actionable. On zero violations it resolves.
+ *
+ * ```js
+ * import { ssrFixture, assertNoA11yViolations } from '@webjsdev/core/testing';
+ * const el = await ssrFixture(html`<my-form></my-form>`);
+ * await assertNoA11yViolations(el);
+ * // tune rules: await assertNoA11yViolations(el, { rules: { 'color-contrast': { enabled: false } } });
+ * ```
+ *
+ * @param {Element} el  The element (subtree root) to scan.
+ * @param {object} [opts]  Options passed through to `axe.run` (e.g. `rules`).
+ * @returns {Promise<void>}
+ */
+export async function assertNoA11yViolations(el, opts) {
+  if (!el || typeof el !== 'object') {
+    throw new Error('assertNoA11yViolations() expects a DOM element');
+  }
+  let axe;
+  try {
+    const mod = await import('axe-core');
+    // axe-core ships a UMD bundle. Depending on how the test runner / bundler
+    // wraps it, the engine may sit on the namespace, on `.default`, on a
+    // nested `.default.default`, or only as the `window.axe` side-effect the
+    // UMD installs. Probe in that order for a `run` function.
+    const candidates = [mod, mod && mod.default, mod && mod.default && mod.default.default,
+      typeof globalThis !== 'undefined' ? globalThis.axe : undefined];
+    axe = candidates.find((c) => c && typeof c.run === 'function');
+  } catch {
+    throw new Error(
+      'assertNoA11yViolations needs axe-core. Install it: npm install -D axe-core'
+    );
+  }
+  if (!axe || typeof axe.run !== 'function') {
+    throw new Error(
+      'assertNoA11yViolations needs axe-core. Install it: npm install -D axe-core'
+    );
+  }
+
+  const results = await axe.run(el, opts || {});
+  const violations = results.violations || [];
+  if (violations.length === 0) return;
+
+  const lines = violations.map((v) => {
+    const targets = (v.nodes || [])
+      .map((n) => (n.target || []).join(' '))
+      .filter(Boolean)
+      .join(', ');
+    return `  - [${v.id}] (${v.impact || 'unknown'}) ${v.help}${targets ? ` -> ${targets}` : ''}`;
+  });
+  const err = new Error(
+    `a11y: ${violations.length} accessibility violation(s) found:\n${lines.join('\n')}`
+  );
+  err.name = 'AssertionError';
+  throw err;
+}
+
 /**
  * Simulate a click event on an element.
  *