@lo-tek/interfaces 0.0.0-stage → 0.37.0

package/src/diagnostics/core.ts

@@ -0,0 +1,210 @@
+/**
+ * The core: LO-TEK's check and theme generator, written in Rust and built to
+ * a single WebAssembly module.
+ *
+ * The same module runs here, in VS Code, on the JVM (Chicory) and in
+ * IntelliJ, and gives the same answer everywhere. The module has no imports,
+ * so it needs no glue: the loader writes the text in as UTF-8 and reads the
+ * answer out as JSON, as every host language does.
+ *
+ * The core carries no data. The vocabulary and the colour contract are given
+ * to it with `loadManifest` and `loadContract`, from the files in the package.
+ *
+ * `diagnoseMarkup` and `diagnosePage` in `index.ts` load the module and the
+ * files from the package themselves. `loadCore` is for anyone who has the
+ * module some other way, such as an extension that bundles it, or a browser:
+ *
+ * ```ts
+ * const core = loadCore(await WebAssembly.compileStreaming(fetch(url)))
+ * core.loadManifest(await (await fetch(manifestUrl)).text())
+ * core.diagnosePage(html)
+ * ```
+ *
+ * Synchronous, because Node, Bun and VS Code allow it. In the browser the
+ * module must be compiled with `WebAssembly.compile` first, and the compiled
+ * module passed here.
+ */
+
+export type Severity = "error" | "warning"
+
+/** One edit in a fix: replace the text from `start` to `end` with `text`. */
+export type Edit = {
+  start: number
+  end: number
+  text: string
+}
+
+/**
+ * A fix the editor can offer: one or more edits that belong together, such
+ * as `id` on the field and `for` on the label. They are in text order and do
+ * not overlap; apply them from the end, so the positions hold. `preferred`
+ * marks the safe one, such as `onlinetext` to `online-text`: the same
+ * letters, only written differently. A suggestion at a distance is a
+ * suggestion.
+ */
+export type Fix = {
+  title: string
+  edits: Edit[]
+  preferred?: boolean
+}
+
+export type Finding = {
+  /** Where the finding starts, as an index into the text (UTF-16, like a `string`). */
+  start: number
+  end: number
+  /** The line the finding starts on, from 1. */
+  line: number
+  /** The column the finding starts at, from 1, in UTF-16 units. */
+  column: number
+  message: string
+  severity: Severity
+  /** The name of the rule, such as `unknown-class`. That is what `lotek-ignore-next` takes. */
+  rule: string
+  /** The component page, as a link in the message. */
+  link: string
+  fix?: Fix
+}
+
+export type CoreVersion = {
+  /** The version of the core. */
+  core: string
+  /** The version of `@lo-tek/interfaces` the manifest was written from, or `null` without a manifest. */
+  manifest: string | null
+  /** The manifest format the core understands. */
+  schemaVersion: number
+}
+
+/** A promise in the colour contract that does not hold. */
+export type Violation = {
+  family: string
+  promise: string
+  ratio: number
+  required: number
+}
+
+/** The theme `buildTheme` returns: the tokens per appearance, the promises that break, and the CSS. */
+export type CoreTheme = {
+  light: Record<string, string>
+  dark: Record<string, string>
+  /** Promises that do not hold. Empty when the theme is sound. */
+  violations: Violation[]
+  css: string
+}
+
+/** What `inspectTheme` found in a theme the consumer has written by hand. */
+export type CoreThemeReport = {
+  problems: { selector: string; message: string }[]
+  /** Blocks that were actually read. */
+  blocks: number
+  /** Values the consumer wrote, and that were understood. */
+  declarations: number
+  /** Promises that were actually checked. */
+  promises: number
+}
+
+/** What `inspectStyles` found in a stylesheet. */
+export type CoreStyles = {
+  /** Every class that appears in a selector. */
+  classes: string[]
+  /** Every class with an attribute, and the value when the selector requires one. */
+  attributes: { class: string; attribute: string; value?: string }[]
+  /** The URLs in `@import`. */
+  imports: string[]
+}
+
+export type Core = {
+  /** Checks a template or a fragment. Throws without a manifest. */
+  diagnoseMarkup(html: string): Finding[]
+  /** Checks a whole page, including the wiring. Throws without a manifest. */
+  diagnosePage(html: string): Finding[]
+  /** Gives the core the vocabulary. Throws with the core's explanation if it cannot be read. */
+  loadManifest(json: string): void
+  /** Gives the core the colour contract. Throws with the core's explanation if it cannot be read. */
+  loadContract(json: string): void
+  version(): CoreVersion
+  /** Builds a theme from the recipe. Throws without a colour contract, or when the recipe cannot be used. */
+  buildTheme(recipe: unknown): CoreTheme
+  /** Checks every promise in a theme written as CSS. Throws without a colour contract. */
+  inspectTheme(css: string): CoreThemeReport
+  /** The classes and attribute values a stylesheet styles, read with the core's CSS reader. */
+  inspectStyles(css: string): CoreStyles
+  /**
+   * The check with the stylesheets as well: a class none of them styles, and
+   * a value without a rule. `page` checks as `diagnosePage`, otherwise as
+   * `diagnoseMarkup`. Throws without a manifest.
+   */
+  diagnoseStyled(html: string, css: string[], page: boolean): Finding[]
+}
+
+type Exports = {
+  memory: WebAssembly.Memory
+  alloc(length: number): number
+  diagnose_markup_raw(pointer: number, length: number): number
+  diagnose_page_raw(pointer: number, length: number): number
+  load_manifest_raw(pointer: number, length: number): number
+  load_contract_raw(pointer: number, length: number): number
+  version_raw(): void
+  build_theme_raw(pointer: number, length: number): number
+  inspect_theme_raw(pointer: number, length: number): number
+  inspect_styles_raw(pointer: number, length: number): void
+  diagnose_styled_raw(pointer: number, length: number): number
+  result_ptr(): number
+  result_len(): number
+}
+
+/** Loads the core from the module's bytes or an already compiled module. */
+export function loadCore(source: BufferSource | WebAssembly.Module): Core {
+  const module =
+    source instanceof WebAssembly.Module
+      ? source
+      : new WebAssembly.Module(source)
+  const e = new WebAssembly.Instance(module, {}).exports as unknown as Exports
+  const encoder = new TextEncoder()
+  const decoder = new TextDecoder()
+
+  /** Writes the text into the module's memory and returns the pointer and length. */
+  const write = (text: string): [number, number] => {
+    const bytes = encoder.encode(text)
+    const pointer = e.alloc(bytes.length)
+    // The memory can grow on every call, so the view is created after `alloc`.
+    new Uint8Array(e.memory.buffer, pointer, bytes.length).set(bytes)
+    return [pointer, bytes.length]
+  }
+  const read = <T>(): T =>
+    JSON.parse(
+      decoder.decode(
+        new Uint8Array(e.memory.buffer, e.result_ptr(), e.result_len()),
+      ),
+    ) as T
+  /** The answer from a call that can be rejected: the value, or the core's explanation as an error. */
+  const answer = <T>(status: number): T => {
+    if (status !== 0) throw new Error(read<{ error: string }>().error)
+    return read<T>()
+  }
+
+  return {
+    diagnoseMarkup: (html) => answer(e.diagnose_markup_raw(...write(html))),
+    diagnosePage: (html) => answer(e.diagnose_page_raw(...write(html))),
+    loadManifest: (json) => {
+      answer(e.load_manifest_raw(...write(json)))
+    },
+    loadContract: (json) => {
+      answer(e.load_contract_raw(...write(json)))
+    },
+    version: () => {
+      e.version_raw()
+      return read()
+    },
+    buildTheme: (recipe) =>
+      answer(e.build_theme_raw(...write(JSON.stringify(recipe)))),
+    inspectTheme: (css) => answer(e.inspect_theme_raw(...write(css))),
+    inspectStyles: (css) => {
+      e.inspect_styles_raw(...write(css))
+      return read()
+    },
+    diagnoseStyled: (html, css, page) =>
+      answer(
+        e.diagnose_styled_raw(...write(JSON.stringify({ html, css, page }))),
+      ),
+  }
+}

package/src/diagnostics/default-core.ts

@@ -0,0 +1,81 @@
+/**
+ * The core from the package itself, loaded the first time it is needed, with
+ * the package's manifest and colour contract, which sit next to the module.
+ *
+ * Both the check (`@lo-tek/interfaces/diagnostics`) and the theme
+ * (`@lo-tek/interfaces/theme` and `theme-check`) use the same instance.
+ */
+
+import { type Core, loadCore } from "./core.js"
+
+/** The files in the package, seen from both `src/diagnostics/` and `dist/diagnostics/`. */
+const MODULE = new URL("../../core/lotek-core.wasm", import.meta.url)
+const MANIFEST = new URL("../../manifest/manifest.json", import.meta.url)
+const CONTRACT = new URL(
+  "../../src/tokens/color-contract.json",
+  import.meta.url,
+)
+
+let core: Core | undefined
+
+/*
+ * Loaded the first time it is needed, not when the module is imported:
+ * anyone who only wants the types, or `loadCore`, should not pay for it.
+ *
+ * `node:fs` is fetched with `process.getBuiltinModule` instead of an import,
+ * so the file can be bundled for the browser without the bundler looking
+ * for `fs`.
+ */
+export function defaultCore(): Core {
+  if (core) return core
+  const fs = globalThis.process?.getBuiltinModule?.("node:fs") as
+    | typeof import("node:fs")
+    | undefined
+  if (!fs) {
+    // `getBuiltinModule` arrived in Node 20.16 and 22.3, so Node 21 and 22.0
+    // to 22.2 are excluded even though they are newer than 20.16. `engines`
+    // in package.json says the same. A Node without it is still Node, and
+    // should be told that the version is wrong, with both limits, so Node
+    // 22.1 is not told it is older than 20.16.
+    const node = globalThis.process?.versions?.node
+    throw new Error(
+      node
+        ? `LO-TEK requires Node 20.16 or later in the 20 series, or Node 22.3 or later, and this is Node ${node}.`
+        : "LO-TEK reads the core from the package, which requires Node, Bun or Deno. In the browser, load lotek-core.wasm yourself, pass it to loadCore, and give the core manifest.json with loadManifest and color-contract.json with loadContract.",
+    )
+  }
+  let bytes: Uint8Array
+  try {
+    bytes = fs.readFileSync(MODULE)
+  } catch {
+    throw new Error(
+      `Could not find the core at ${MODULE.pathname}. In the repository it is built with "bun run core" in interfaces/, which requires Rust.`,
+    )
+  }
+  // The manifest is only needed by the check, and the colour contract only
+  // by the theme. Each is read the first time a call needs it.
+  const loaded = loadCore(bytes)
+  let manifest = false
+  let contract = false
+  const withManifest = () => {
+    if (!manifest) loaded.loadManifest(fs.readFileSync(MANIFEST, "utf8"))
+    manifest = true
+    return loaded
+  }
+  const withContract = () => {
+    if (!contract) loaded.loadContract(fs.readFileSync(CONTRACT, "utf8"))
+    contract = true
+    return loaded
+  }
+  core = {
+    ...loaded,
+    diagnoseMarkup: (html) => withManifest().diagnoseMarkup(html),
+    diagnosePage: (html) => withManifest().diagnosePage(html),
+    diagnoseStyled: (html, css, page) =>
+      withManifest().diagnoseStyled(html, css, page),
+    version: () => withManifest().version(),
+    buildTheme: (recipe) => withContract().buildTheme(recipe),
+    inspectTheme: (css) => withContract().inspectTheme(css),
+  }
+  return core
+}

package/src/diagnostics/index.ts

@@ -0,0 +1,150 @@
+/**
+ * Checks markup against LO-TEK, outside the browser.
+ *
+ * `diagnoseMarkup(html)` is the same check the editor extensions run while
+ * you type, and that `lotek check` runs on the command line. It is here
+ * because markup produced without JavaScript, in a Go template, a Kotlin
+ * string or a Razor view, has no compiler looking at the attributes. A test
+ * in the app can then run it over the HTML the server actually sends:
+ *
+ * ```ts
+ * import { diagnosePage } from "@lo-tek/interfaces/diagnostics"
+ *
+ * expect(diagnosePage(html)).toEqual([])
+ * ```
+ *
+ * The check is the core, written in Rust and built to WebAssembly (see
+ * `core.ts`). The module ships with the package, and is loaded the first
+ * time one of the functions is called, in Node, Bun and Deno. In the
+ * browser, or where the module is bundled some other way, `loadCore` loads
+ * it.
+ */
+
+import type { Finding } from "./core.js"
+
+export type { Manifest } from "../vocabulary/types.js"
+
+import { defaultCore } from "./default-core.js"
+
+export {
+  type Core,
+  type CoreStyles,
+  type CoreTheme,
+  type CoreThemeReport,
+  type CoreVersion,
+  type Finding,
+  type Fix,
+  loadCore,
+  type Severity,
+  type Violation,
+} from "./core.js"
+
+/** Options for the check. */
+export type DiagnoseOptions = {
+  /**
+   * The stylesheets the page loads, as text. With them the check also
+   * reports a class none of them styles, as when the component's stylesheet
+   * is not loaded, and a value without a rule, such as a variant added to a
+   * taken-over component without the CSS getting it.
+   */
+  css?: string[]
+}
+
+/** Every finding in the text: the vocabulary, for a template or a fragment of a page. */
+export function diagnoseMarkup(
+  text: string,
+  options: DiagnoseOptions = {},
+): Finding[] {
+  return options.css
+    ? defaultCore().diagnoseStyled(text, options.css, false)
+    : defaultCore().diagnoseMarkup(text)
+}
+
+/**
+ * Every finding on a whole page: what `diagnoseMarkup` finds, and also that
+ * every `for`, `aria-describedby`, `aria-labelledby` and `aria-controls`
+ * points to an id that exists, that no id appears twice, and that every
+ * LO-TEK field and every help text and error text is wired.
+ *
+ * Use it on the HTML the server sends, not on a template: in a template split
+ * into pieces, the id can be in another file.
+ *
+ * ```ts
+ * const html = await (await fetch("http://localhost:8080/form")).text()
+ * expect(diagnosePage(html)).toEqual([])
+ * ```
+ */
+export function diagnosePage(
+  text: string,
+  options: DiagnoseOptions = {},
+): Finding[] {
+  return options.css
+    ? defaultCore().diagnoseStyled(text, options.css, true)
+    : defaultCore().diagnosePage(text)
+}
+
+/** What `diagnoseRendered` needs from a page: `evaluate`, as in Playwright. */
+export type RenderedPage = {
+  evaluate<T>(script: () => Promise<T>): Promise<T>
+}
+
+/**
+ * Reads the rendered page in the browser: the DOM as it stands now, and the
+ * text of every stylesheet, with what they import. A stylesheet from another
+ * origin, such as a CDN, cannot be read through the CSSOM without
+ * `crossorigin`, and is then fetched again with `fetch`.
+ *
+ * The function runs in the browser, and cannot use anything outside itself.
+ */
+export const READ_RENDERED_PAGE = async (): Promise<{
+  html: string
+  css: string[]
+}> => {
+  const sheets: CSSStyleSheet[] = [
+    ...document.styleSheets,
+    ...document.adoptedStyleSheets,
+  ]
+  const css: string[] = []
+  const read = async (sheet: CSSStyleSheet): Promise<void> => {
+    let rules: CSSRuleList
+    try {
+      rules = sheet.cssRules
+    } catch {
+      if (!sheet.href) return
+      const answer = await fetch(sheet.href)
+      if (!answer.ok)
+        throw new Error(
+          `The stylesheet ${sheet.href} could not be read, and answered ${answer.status} when it was fetched again.`,
+        )
+      css.push(await answer.text())
+      return
+    }
+    for (const rule of rules)
+      if (rule instanceof CSSImportRule && rule.styleSheet)
+        await read(rule.styleSheet)
+    css.push([...rules].map((rule) => rule.cssText).join("\n"))
+  }
+  for (const sheet of sheets) await read(sheet)
+  const doctype = document.doctype ? `<!DOCTYPE ${document.doctype.name}>` : ""
+  return { html: doctype + document.documentElement.outerHTML, css }
+}
+
+/**
+ * Checks the page as the browser has rendered it, with the stylesheets it
+ * has loaded: what `diagnosePage` finds, and what the stylesheets do not
+ * style. Markup the web components have added, and a class JavaScript has
+ * set, are included.
+ *
+ * ```ts
+ * import { diagnoseRendered } from "@lo-tek/interfaces/diagnostics"
+ *
+ * await page.goto("http://localhost:8080/form")
+ * expect(await diagnoseRendered(page)).toEqual([])
+ * ```
+ *
+ * `page` is a Playwright page, or anything with `evaluate`.
+ */
+export async function diagnoseRendered(page: RenderedPage): Promise<Finding[]> {
+  const { html, css } = await page.evaluate(READ_RENDERED_PAGE)
+  return defaultCore().diagnoseStyled(html, css, true)
+}

package/src/dom.ts

@@ -0,0 +1,185 @@
+/**
+ * Applying the attributes to an element in the plain DOM.
+ *
+ * In JSX you spread the object straight onto the element. Without JSX you
+ * would have to loop through it yourself, and take care to remove attributes
+ * from the previous state. When a field goes from invalid to valid, the
+ * builder function leaves out `data-state`, and a `setAttribute` alone would
+ * have left the old value in place.
+ */
+
+import { managedNames } from "./components/css/shared.js"
+
+/**
+ * What gets cleaned up for a set without a builder function behind it.
+ *
+ * A handwritten or spread set is not in the map of what it manages, and then
+ * the `data-*` names are the only ones the function can safely remove: they
+ * belong to the system. A set straight from a builder function does not use
+ * this list. It cleans up exactly what the builder function manages, so
+ * `lt.popover().trigger` on a secondary button leaves `data-variant` alone.
+ */
+const SAFE_FOR_UNKNOWN = [
+  "data-variant",
+  "data-state",
+  "data-color",
+  "data-size",
+  "data-picker",
+  "data-required",
+  "data-optional",
+  "data-interactive",
+  "data-hoverable",
+  "data-selectable",
+  "data-autofocus",
+] as const
+
+/**
+ * Names that are never removed, not even when the builder function manages
+ * them.
+ *
+ * `id` and `for` are connections other elements point to. `lt.errorSummary()`
+ * takes an optional `id`, and a call without it removed the id the consumer
+ * had written on the box: every link and every `aria-*` pointing there broke.
+ */
+const NEVER_REMOVED: readonly string[] = ["id", "for"]
+
+let warnedAboutUnknownSet = false
+
+/** The classes that belong to the system. The consumer's classes are kept. */
+const IS_SYSTEM_CLASS = /^lt-/
+
+/**
+ * The values a builder function can output.
+ *
+ * `true` and `false` are included because several of them are boolean HTML
+ * attributes: `disabled` on a switch, `multiple` on a file field, `hidden` on
+ * an error text. In HTML such an attribute is true as long as it exists,
+ * whatever its value, so `true` is set as the empty string and `false`
+ * removes it.
+ */
+export type Attributes = Record<string, string | boolean | undefined>
+
+/**
+ * Sets the attributes from an `lt` function on an element.
+ *
+ * ```ts
+ * import { lt } from "@lo-tek/interfaces"
+ *
+ * const field = document.querySelector("input")
+ * lt.setAttributes(field, lt.input({ type: "email", state: "invalid" }))
+ * ```
+ *
+ * Call it again to change state. What the builder function manages and is
+ * not in the new set is removed, and the `lt-` classes are replaced. A
+ * builder function manages the attributes it has an option for:
+ * `lt.spinner()` has `label`, and so manages `role` and `aria-label`. What it
+ * has no option for stays as it is: `lt.button()` has never written
+ * `disabled`, so a disabled button is still disabled afterwards. `id` and
+ * `for` are never removed.
+ *
+ * When two sets go on the same element, pass them separately, not spread
+ * together:
+ *
+ * ```ts
+ * lt.setAttributes(field, lt.input({ type: "email" }), wiring.control)
+ * ```
+ *
+ * A spread object is a new object, and then the function does not know which
+ * builder function it came from. It is set correctly, but only `data-*` is
+ * cleaned up. An explicit `false` in a handwritten set removes the attribute.
+ *
+ * It accepts `null`, and then does nothing. `document.querySelector()`
+ * returns `Element | null`, so without that every call site in a `strict` app
+ * would need a guard or an exclamation mark around a lookup that almost
+ * always succeeds. It is the same trade-off as `element?.classList`.
+ */
+export function setAttributes(
+  element: Element | null | undefined,
+  ...sets: Attributes[]
+): void {
+  if (!element || sets.length === 0) return
+
+  const merged: Attributes = {}
+  const removable = new Set<string>()
+  const classes: string[] = []
+
+  for (const set of sets) {
+    const names = managedNames(set)
+    if (names) {
+      for (const name of names) removable.add(name)
+    } else {
+      for (const name of SAFE_FOR_UNKNOWN) removable.add(name)
+      warnAboutUnknownSet(set)
+    }
+    for (const [name, value] of Object.entries(set)) {
+      if (name === "class") {
+        if (typeof value === "string") classes.push(...value.split(/\s+/))
+      } else if (value === false) {
+        // An explicit `false` in a handwritten set is a request.
+        merged[name] = false
+        removable.add(name)
+      } else if (value !== undefined) {
+        // `undefined` does not override an earlier set: the builder functions
+        // drop such keys themselves, and a handwritten set must not be able to
+        // take `aria-invalid` from `lt.input()` by naming it without a value.
+        merged[name] = value
+      }
+    }
+  }
+  for (const name of NEVER_REMOVED) removable.delete(name)
+
+  if (classes.length > 0) {
+    const ownClasses = [...element.classList].filter(
+      (token) => !IS_SYSTEM_CLASS.test(token),
+    )
+    // `setAttribute` and not `className`: on an `<svg>`, `className` is a
+    // read-only `SVGAnimatedString`, and `lt.icon()` belongs on an svg.
+    element.setAttribute(
+      "class",
+      [...new Set([...classes, ...ownClasses])].filter(Boolean).join(" "),
+    )
+  }
+
+  for (const name of removable) {
+    if (name === "class") continue
+    setOrRemove(element, name, merged[name])
+  }
+
+  for (const [name, value] of Object.entries(merged)) {
+    if (removable.has(name)) continue
+    if (value === undefined || value === false) continue
+    element.setAttribute(name, value === true ? "" : value)
+  }
+}
+
+/**
+ * Warns, once, about a set that looks like two spread together.
+ *
+ * `{ ...lt.input(), ...field.control }` is set correctly, but is a new object
+ * without a builder function behind it. The next call then does not remove
+ * `aria-invalid` when the field becomes valid, and nothing else would have
+ * said so.
+ */
+function warnAboutUnknownSet(set: Attributes): void {
+  if (warnedAboutUnknownSet) return
+  if (typeof set.class !== "string" || !/(^|\s)lt-/.test(set.class)) return
+  warnedAboutUnknownSet = true
+  console.warn(
+    "lt.setAttributes(): the set does not come straight from a builder " +
+      "function, so only the data attributes are cleaned up. Pass the sets " +
+      "separately instead of spreading them: " +
+      "lt.setAttributes(element, lt.input(), field.control).",
+  )
+}
+
+function setOrRemove(
+  element: Element,
+  name: string,
+  value: string | boolean | undefined,
+): void {
+  if (value === undefined || value === false) {
+    element.removeAttribute(name)
+  } else {
+    element.setAttribute(name, value === true ? "" : value)
+  }
+}