@webjsdev/core 0.7.65 → 0.9.0

package/src/converters.js

@@ -0,0 +1,38 @@
+/**
+ * Lit's `defaultConverter` and `notEqual` (#1686), exported under the same
+ * names so a component written from Lit's docs (a custom converter that
+ * delegates to the default, or `hasChanged: (v, old) => notEqual(v, old)`)
+ * imports them from `@webjsdev/core` as it would from `lit`.
+ *
+ * The semantics are Lit's, line for line: a Boolean attribute is on when
+ * present, a Number parses with `Number()`, an Object or Array round-trips
+ * through JSON (an unparseable value reads `null`, as in Lit), and anything
+ * else is the string.
+ *
+ * @module
+ */
+
+/** @type {{ toAttribute(value: unknown, type?: unknown): unknown, fromAttribute(value: string | null, type?: unknown): unknown }} */
+export const defaultConverter = {
+  toAttribute(value, type) {
+    if (type === Boolean) return value ? '' : null;
+    if (type === Object || type === Array) return value == null ? value : JSON.stringify(value);
+    return value;
+  },
+  fromAttribute(value, type) {
+    if (type === Boolean) return value !== null;
+    if (type === Number) return value === null ? null : Number(value);
+    if (type === Object || type === Array) {
+      try { return JSON.parse(/** @type {string} */ (value)); } catch { return null; }
+    }
+    return value;
+  },
+};
+
+/**
+ * Lit's default change check: true when `value` differs from `old`, by
+ * `Object.is` (so `NaN` equals `NaN`).
+ * @param {unknown} value @param {unknown} old
+ * @returns {boolean}
+ */
+export const notEqual = (value, old) => !Object.is(value, old);

package/src/css.d.ts

@@ -1,9 +1,35 @@
-export interface CSSResult {
-  _$webjsCss: true;
-  text: string;
+/** The value `css` and `unsafeCSS` return (Lit's `CSSResult`). */
+export declare class CSSResult {
+  private constructor(cssText: string);
+  readonly _$webjsCss: true;
+  /** The style text. */
+  readonly cssText: string;
+  /** The style text, an alias of `cssText`. */
+  readonly text: string;
+  /** A shared constructed stylesheet in the browser; undefined on the server. */
+  readonly styleSheet: CSSStyleSheet | undefined;
+  toString(): string;
 }
 
-export function css(strings: TemplateStringsArray | string[], ...values: unknown[]): CSSResult;
+/** A `css` result or a constructed stylesheet (Lit's `CSSResultOrNative`). */
+export type CSSResultOrNative = CSSResult | CSSStyleSheet;
+
+/** Arbitrarily nested arrays of styles (Lit's `CSSResultArray`). */
+export interface CSSResultArray extends Array<CSSResultOrNative | CSSResultArray> {}
+
+/** What `static styles` accepts (Lit's `CSSResultGroup`). */
+export type CSSResultGroup = CSSResultOrNative | CSSResultArray;
+
+/**
+ * Tagged template producing a `CSSResult`. A hole may hold another `css`
+ * result or a number; anything else throws (wrap a trusted string in
+ * `unsafeCSS()`).
+ */
+export function css(strings: TemplateStringsArray | string[], ...values: (CSSResult | number)[]): CSSResult;
+/** Wrap a trusted string as a `CSSResult`. Never pass user input. */
+export function unsafeCSS(value: unknown): CSSResult;
 export function isCSS(x: unknown): x is CSSResult;
-export function adoptStyles(root: ShadowRoot | Document, styles: CSSResult[]): void;
-export function stylesToString(styles: CSSResult[]): string;
+/** Flatten `static styles` into the list both renderers apply (Lit's `finalizeStyles`). */
+export function finalizeStyles(styles?: CSSResultGroup | null): CSSResultOrNative[];
+export function adoptStyles(root: ShadowRoot | Document, styles: CSSResultOrNative[]): void;
+export function stylesToString(styles: CSSResultOrNative[]): string;

package/src/css.js

@@ -1,7 +1,88 @@
 /**
- * Tagged template literal producing a {@link CSSResult}.
+ * The `css` tag and the style plumbing both renderers share.
  *
- * @typedef {{ _$webjsCss: true, text: string }} CSSResult
+ * Portions derived from Lit (`@lit/reactive-element` css-tag.ts and
+ * reactive-element.ts `finalizeStyles`), Copyright Google LLC,
+ * BSD-3-Clause.
+ */
+
+/**
+ * The value `css` and `unsafeCSS` return, Lit's `CSSResult`. `cssText` is the
+ * style text; `styleSheet` is a constructed `CSSStyleSheet` built on first
+ * read in the browser (undefined on the server), cached per result so every
+ * element adopting it shares one sheet.
+ *
+ * The `_$webjsCss` brand, not `instanceof`, is what identifies a result:
+ * `@webjsdev/core` resolves to a bundle while a subpath resolves to source, so
+ * two copies of this class can meet in one page.
+ */
+
+/** Held by `css` and `unsafeCSS` only, Lit's `constructionToken`. */
+const constructionToken = Symbol();
+
+/**
+ * The shared sheet per hole-free `css` template, keyed by its strings array.
+ * @type {WeakMap<readonly string[], CSSStyleSheet>}
+ */
+const sheetCache = new WeakMap();
+
+export class CSSResult {
+  /**
+   * Not constructable from outside this module, as in Lit: `css` and
+   * `unsafeCSS` are the only ways to make one, so arbitrary text cannot pass
+   * for a checked `css` result without going through `unsafeCSS` by name.
+   * @param {string} cssText
+   * @param {readonly string[] | undefined} strings the `css` template, keying the shared sheet
+   * @param {symbol} safeToken
+   */
+  constructor(cssText, strings, safeToken) {
+    if (safeToken !== constructionToken) {
+      throw new Error('[webjs] CSSResult is not constructable. Use `css` or `unsafeCSS` instead.');
+    }
+    /** @type {true} */
+    this._$webjsCss = true;
+    /** @type {string} */
+    this.cssText = cssText;
+    /** @type {CSSStyleSheet | undefined} */
+    this._styleSheet = undefined;
+    this._strings = strings;
+  }
+
+  /** The style text, also readable as `cssText` (Lit's name). */
+  get text() {
+    return this.cssText;
+  }
+
+  /**
+   * A constructed stylesheet for `adoptedStyleSheets`, or undefined where
+   * there is none (the server). A `css` template with no holes always yields
+   * the same text, so every result from it shares one sheet, as in Lit.
+   */
+  get styleSheet() {
+    if (this._styleSheet === undefined && typeof CSSStyleSheet !== 'undefined') {
+      const strings = this._strings;
+      const cacheable = strings !== undefined && strings.length === 1;
+      let sheet = cacheable ? sheetCache.get(strings) : undefined;
+      if (sheet === undefined) {
+        sheet = new CSSStyleSheet();
+        sheet.replaceSync(this.cssText);
+        if (cacheable) sheetCache.set(strings, sheet);
+      }
+      this._styleSheet = sheet;
+    }
+    return this._styleSheet;
+  }
+
+  toString() {
+    return this.cssText;
+  }
+}
+
+/**
+ * Tagged template literal producing a {@link CSSResult}, Lit's `css`. A hole
+ * may hold another `css` result (composed in as text) or a number. Anything
+ * else throws: a string in a hole is how untrusted text reaches a stylesheet,
+ * so it has to go through `unsafeCSS()` on purpose, as in Lit.
  *
  * @param {TemplateStringsArray | string[]} strings
  * @param {...unknown} values
@@ -10,9 +91,39 @@
 export function css(strings, ...values) {
   let text = strings[0];
   for (let i = 1; i < strings.length; i++) {
-    text += String(values[i - 1] ?? '') + strings[i];
+    text += cssValue(values[i - 1]) + strings[i];
   }
-  return { _$webjsCss: true, text };
+  return new CSSResult(text, strings, constructionToken);
+}
+
+/** @param {unknown} value */
+function cssValue(value) {
+  if (isCSS(value)) return /** @type {any} */ (value).cssText ?? /** @type {any} */ (value).text;
+  if (typeof value === 'number') return String(value);
+  throw new Error(
+    `[webjs] Value passed to 'css' must be a 'css' result or a number, got ${describe(value)}. ` +
+      `Compose another css\`...\` result, or wrap a trusted string in unsafeCSS() from '@webjsdev/core'. ` +
+      `Never pass user input through unsafeCSS().`,
+  );
+}
+
+/** @param {unknown} value */
+function describe(value) {
+  if (value === null) return 'null';
+  if (typeof value === 'string') return JSON.stringify(value.length > 40 ? value.slice(0, 40) + '...' : value);
+  return typeof value;
+}
+
+/**
+ * Wrap a string (or any value, stringified) as a {@link CSSResult}, Lit's
+ * `unsafeCSS`. The text is used as is, so only pass trusted values: CSS from
+ * user input can exfiltrate data through `url()` and attribute selectors.
+ *
+ * @param {unknown} value
+ * @returns {CSSResult}
+ */
+export function unsafeCSS(value) {
+  return new CSSResult(typeof value === 'string' ? value : String(value), undefined, constructionToken);
 }
 
 /** @param {unknown} x @returns {x is CSSResult} */
@@ -21,34 +132,87 @@ export function isCSS(x) {
 }
 
 /**
- * Apply an array of CSSResults to a shadow root (client-side only).
- * Uses adoptedStyleSheets when available, falls back to <style>.
+ * Lit's `finalizeStyles`: turn a class's `static styles` (a result, a sheet,
+ * or arbitrarily nested arrays of them) into the flat list both renderers
+ * apply. A style included twice keeps its LAST position, so a later override
+ * still wins the cascade, as in Lit.
+ *
+ * @param {unknown} styles
+ * @returns {(CSSResult | CSSStyleSheet)[]}
+ */
+export function finalizeStyles(styles) {
+  /** @type {(CSSResult | CSSStyleSheet)[]} */
+  const out = [];
+  if (Array.isArray(styles)) {
+    const unique = new Set(styles.flat(Infinity).reverse());
+    for (const s of unique) if (isStyle(s)) out.unshift(/** @type {any} */ (s));
+  } else if (isStyle(styles)) {
+    out.push(/** @type {any} */ (styles));
+  }
+  return out;
+}
+
+/** @param {unknown} s */
+function isStyle(s) {
+  return isCSS(s) || (typeof CSSStyleSheet !== 'undefined' && s instanceof CSSStyleSheet);
+}
+
+/**
+ * Apply styles to a shadow root (client-side only). Uses adoptedStyleSheets
+ * when available, falls back to a <style> element.
  *
  * @param {ShadowRoot | Document} root
- * @param {CSSResult[]} styles
+ * @param {(CSSResult | CSSStyleSheet)[]} styles
  */
 export function adoptStyles(root, styles) {
   if (!styles || !styles.length) return;
   if ('adoptedStyleSheets' in root && typeof CSSStyleSheet !== 'undefined') {
-    const sheets = styles.map((s) => {
+    /** @type {any} */ (root).adoptedStyleSheets = styles.map((s) => {
+      if (s instanceof CSSStyleSheet) return s;
+      const shared = /** @type {any} */ (s).styleSheet;
+      if (shared) return shared;
       const sheet = new CSSStyleSheet();
-      sheet.replaceSync(s.text);
+      sheet.replaceSync(styleText(s));
       return sheet;
     });
-    /** @type {any} */ (root).adoptedStyleSheets = sheets;
   } else {
     const host = /** @type {any} */ (root);
     const el = document.createElement('style');
-    el.textContent = styles.map((s) => s.text).join('\n');
+    el.textContent = styles.map(styleText).join('\n');
     host.appendChild(el);
   }
 }
 
+/** @param {any} s @returns {string} */
+function styleText(s) {
+  if (isCSS(s)) return s.cssText ?? s.text;
+  if (s && s.cssRules) return Array.from(s.cssRules, (r) => /** @type {any} */ (r).cssText).join('\n');
+  return '';
+}
+
 /**
- * Serialise styles to a <style> tag string (server-side).
- * @param {CSSResult[]} styles
+ * Serialise styles to a <style> tag string (server-side). A constructed
+ * `CSSStyleSheet` has no server equivalent, so only `css` results render.
+ * @param {(CSSResult | CSSStyleSheet)[]} styles
  */
 export function stylesToString(styles) {
   if (!styles || !styles.length) return '';
-  return `<style>${styles.map((s) => s.text).join('\n')}</style>`;
+  const text = styles.filter(isCSS).map(styleText);
+  return text.length ? `<style>${text.join('\n')}</style>` : '';
+}
+
+/**
+ * The error a light-DOM component with `static styles` gets: the styles are
+ * adopted into a shadow root, and the component has none. One string, used by
+ * the server renderer (logged during SSR) and by the browser element, so the
+ * two cannot drift. Internal: not re-exported from the package.
+ * @param {string} tag
+ * @returns {string}
+ */
+export function lightDomStylesMessage(tag) {
+  return (
+    `[webjs] <${tag}> declares static styles but renders into light DOM, so the styles are never applied. ` +
+    `Add \`static shadow = true\` to scope them in a shadow root, or style the light-DOM markup with Tailwind ` +
+    `utilities or a global stylesheet (prefix custom class selectors with the tag name).`
+  );
 }

package/src/directive.d.ts

@@ -0,0 +1,58 @@
+/** lit's `PartType`: the kind of part a directive is bound to. */
+export const PartType: {
+  readonly ATTRIBUTE: 1;
+  readonly CHILD: 2;
+  readonly PROPERTY: 3;
+  readonly BOOLEAN_ATTRIBUTE: 4;
+  readonly EVENT: 5;
+  readonly ELEMENT: 6;
+};
+export type PartType = (typeof PartType)[keyof typeof PartType];
+
+/** lit's `PartInfo`: where a directive instance is used. */
+export interface PartInfo {
+  readonly type: PartType;
+  readonly name?: string;
+  readonly tagName?: string;
+  readonly strings?: readonly string[];
+}
+
+/** The part handed to `update()` on the client (a lit-shaped facade). */
+export interface Part {
+  readonly type: PartType;
+  readonly options: { readonly host: unknown };
+  /** Element, attribute, property, boolean and event parts. */
+  readonly element?: Element;
+  readonly name?: string;
+  readonly strings?: readonly string[];
+  /** Child parts. */
+  readonly parentNode?: Node | null;
+  readonly startNode?: Node | null;
+  readonly endNode?: Node | null;
+}
+
+/** lit's `Directive`: subclass it, implement `render()`, optionally `update()`. */
+export abstract class Directive {
+  constructor(partInfo: PartInfo);
+  abstract render(...props: unknown[]): unknown;
+  update(part: Part, props: unknown[]): unknown;
+}
+
+/** The value a `directive()` function returns; rendered by both renderers. */
+export interface DirectiveResult<C extends abstract new (...args: any[]) => Directive = abstract new (...args: any[]) => Directive> {
+  readonly _$webjs: 'directive';
+  readonly ctor: C;
+  readonly values: unknown[];
+}
+
+/** The arguments of a directive class's `render()`. */
+export type DirectiveParameters<C extends Directive> = Parameters<C['render']>;
+
+/** lit's `directive()`: the template-facing function for a directive class. */
+export function directive<C extends new (partInfo: PartInfo) => Directive>(
+  c: C,
+): (...values: DirectiveParameters<InstanceType<C>>) => DirectiveResult<C>;
+
+export function isDirectiveResult(x: unknown): x is DirectiveResult;
+/** lit's `getDirectiveClass`. */
+export function getDirectiveClass(x: unknown): (abstract new (...args: any[]) => Directive) | undefined;

package/src/directive.js

@@ -0,0 +1,119 @@
+/**
+ * Custom directive authoring, lit's `lit/directive.js` under a WebJs path:
+ * `@webjsdev/core/directive`.
+ *
+ * Portions derived from Lit, Copyright Google LLC, BSD-3-Clause.
+ *
+ * ```js
+ * import { directive, Directive, PartType } from '@webjsdev/core/directive';
+ *
+ * class Uppercase extends Directive {
+ *   constructor(partInfo) {
+ *     super(partInfo);
+ *     if (partInfo.type !== PartType.CHILD) throw new Error('uppercase() is a child directive');
+ *   }
+ *   render(text) { return String(text).toUpperCase(); }
+ * }
+ * export const uppercase = directive(Uppercase);
+ *
+ * html`<p>${uppercase(name)}</p>`;
+ * ```
+ *
+ * The contract is lit's. One directive INSTANCE lives per template part (per
+ * piece of an interpolated attribute) for as long as the same directive class
+ * renders there; a different class (or a plain value) replaces it. On the
+ * client every render calls `update(part, values)`, whose default forwards to
+ * `render(...values)`; on the server only `render(...values)` runs, because
+ * there is no DOM to hand `update`. Whatever either returns is rendered at the
+ * part like any other value (`noChange` keeps the last commit, `nothing`
+ * clears it), so a directive may return a template or another directive.
+ *
+ * The result is a plain object branded `_$webjs: 'directive'`. Both renderers
+ * recognise it by that brand, never by `instanceof`, so a directive built
+ * against one loaded copy of this module renders through another (this
+ * subpath is source while the root import may be the built bundle).
+ *
+ * @module directive
+ */
+
+/**
+ * The kind of template part a directive instance is bound to, lit's values.
+ * @type {Readonly<{ ATTRIBUTE: 1, CHILD: 2, PROPERTY: 3, BOOLEAN_ATTRIBUTE: 4, EVENT: 5, ELEMENT: 6 }>}
+ */
+export const PartType = Object.freeze({
+  ATTRIBUTE: 1,
+  CHILD: 2,
+  PROPERTY: 3,
+  BOOLEAN_ATTRIBUTE: 4,
+  EVENT: 5,
+  ELEMENT: 6,
+});
+
+/**
+ * Base class for a custom directive. Subclass it, implement `render()`, and
+ * optionally override `update()` for DOM access on the client.
+ */
+export class Directive {
+  /**
+   * @param {{ type: number, name?: string, tagName?: string, strings?: readonly string[] }} _partInfo
+   *   Where the directive is used: `type` is a {@link PartType}; an attribute
+   *   part also carries `name`, `tagName` and, when the attribute is
+   *   interpolated, its static `strings`.
+   */
+  constructor(_partInfo) {}
+
+  /**
+   * Produce the value to render. Called on the server, and on the client by
+   * the default `update()`.
+   * @param {...unknown} _values the arguments the directive function was called with
+   * @returns {unknown}
+   */
+  render(..._values) {
+    return undefined;
+  }
+
+  /**
+   * Called on the client on every render with the part (a lit-shaped facade:
+   * `type`, `options.host`, and `element` / `name` / `strings` for an element
+   * or attribute part, `parentNode` / `startNode` / `endNode` for a child
+   * part) and the arguments as an array. The default calls `render()`.
+   * @param {unknown} _part
+   * @param {unknown[]} values
+   * @returns {unknown}
+   */
+  update(_part, values) {
+    return this.render(...values);
+  }
+}
+
+/**
+ * Turn a {@link Directive} subclass into the function templates call, lit's
+ * `directive()`. Each call returns a marker carrying the class and its
+ * arguments; the renderer owns the instance.
+ *
+ * @template {new (partInfo: any) => Directive} C
+ * @param {C} c
+ * @returns {(...values: unknown[]) => { _$webjs: 'directive', ctor: C, values: unknown[] }}
+ */
+export function directive(c) {
+  return (...values) => ({ _$webjs: 'directive', ctor: c, values });
+}
+
+/**
+ * Whether `x` is the result of calling a `directive()` function.
+ * @param {unknown} x
+ * @returns {x is { _$webjs: 'directive', ctor: any, values: unknown[] }}
+ */
+export function isDirectiveResult(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'directive';
+}
+
+/**
+ * The directive class a directive result was made from, lit's
+ * `getDirectiveClass`.
+ * @param {unknown} x
+ * @returns {Function | undefined}
+ */
+export function getDirectiveClass(x) {
+  return isDirectiveResult(x) ? x.ctor : undefined;
+}

package/src/directives.d.ts

@@ -1,8 +1,12 @@
+import type { nothing, noChange } from './sentinels.js';
 export { repeat, isRepeat } from './repeat.js';
+export type { RepeatDirective } from './repeat.js';
 
 export interface UnsafeHTMLDirective {
   _$webjs: 'unsafe-html';
   value: string;
+  /** Set by `unsafeSVG` / `unsafeMathML`: the namespace the client parses the markup in. */
+  ns?: 'svg' | 'mathml';
 }
 
 export interface LiveDirective<T = unknown> {
@@ -63,8 +67,12 @@ export interface WatchDirective<T = unknown> {
   signal: { get(): T; __isSignal: true };
 }
 
-export function unsafeHTML(htmlString: string | null | undefined): UnsafeHTMLDirective;
+export function unsafeHTML(htmlString: string | null | undefined | typeof nothing | typeof noChange): UnsafeHTMLDirective;
 export function isUnsafeHTML(x: unknown): x is UnsafeHTMLDirective;
+/** lit's `unsafeSVG`: trusted SVG markup, parsed in the SVG namespace on the client. */
+export function unsafeSVG(svgString: string | null | undefined | typeof nothing | typeof noChange): UnsafeHTMLDirective;
+/** lit's `unsafeMathML`: trusted MathML markup, parsed in the MathML namespace on the client. */
+export function unsafeMathML(mathString: string | null | undefined | typeof nothing | typeof noChange): UnsafeHTMLDirective;
 export function live<T>(value: T): LiveDirective<T>;
 export function isLive(x: unknown): x is LiveDirective;
 export function keyed<T>(key: unknown, template: T): KeyedDirective<T>;
@@ -96,3 +104,34 @@ export function asyncReplace<T>(
 export function isAsyncReplace(x: unknown): x is AsyncReplaceDirective;
 export function watch<T>(sig: { get(): T; __isSignal: true }): WatchDirective<T>;
 export function isWatch(x: unknown): x is WatchDirective;
+
+type Falsy = null | undefined | false | 0 | -0 | 0n | '';
+
+/** lit's `when`: the case functions receive the condition value. */
+export function when<C, T, F = undefined>(
+  condition: C,
+  trueCase: (c: Exclude<C, Falsy>) => T,
+  falseCase?: (c: Extract<C, Falsy>) => F,
+): C extends Falsy ? F : T;
+/** lit's `choose`: the case whose key is `===` to `value`, else the default. */
+export function choose<T, V, K extends T = T>(
+  value: T,
+  cases: Array<[K, () => V]>,
+  defaultCase?: () => V,
+): V | undefined;
+/** lit's `map`: a lazy generator over `items`, renderable anywhere an array is. */
+export function map<T, U>(
+  items: Iterable<T> | undefined,
+  f: (value: T, index: number) => U,
+): Generator<U, void, unknown>;
+/** lit's `join`: `items` with `joiner` (or `joiner(index)`) between each pair. */
+export function join<I, J>(
+  items: Iterable<I> | undefined,
+  joiner: J | ((index: number) => J),
+): Generator<I | J, void, unknown>;
+/** lit's `range`: `range(end)`, `range(start, end)` or `range(start, end, step)`. */
+export function range(end: number): Generator<number, void, unknown>;
+export function range(start: number, end: number, step?: number): Generator<number, void, unknown>;
+
+export { classMap, styleMap, ifDefined } from './attribute-directives.js';
+export type { ClassMapDirective, StyleMapDirective } from './attribute-directives.js';