@lo-tek/interfaces 0.0.0 → 0.38.0

package/src/components/standalone/toast/toast.ts

@@ -0,0 +1,70 @@
+import { attributes } from "../../css/shared.js"
+import { DEFAULT_TEXTS } from "../../default-texts.js"
+
+/**
+ * The class on the host, that is, the region the messages are in.
+ *
+ * Until 0.28.0 this was the class on each message, and the region was styled
+ * by its element name. Registered under another name, with
+ * `defineLtToast("my-toast")`, it then lost its position.
+ */
+export const TOAST_CLASS = "lt-toast" as const
+export const TOAST_MESSAGE_CLASS = "lt-toast__message" as const
+export const TOAST_CLOSE_CLASS = "lt-toast__close" as const
+
+export type ToastOptions = {
+  /** Text that says what the region is. Becomes `aria-label`. */
+  label?: string
+  /**
+   * The screen reader name of the close button in each message. Default:
+   * "Close message". `closeLabel` in `show()` overrides it for one message.
+   */
+  closeLabel?: string
+}
+
+export type ToastAttributes = {
+  host: {
+    class: typeof TOAST_CLASS
+    role: "status"
+    "aria-live": "polite"
+    "aria-atomic": "false"
+    "aria-label": string
+    "close-label"?: string
+    "data-ignore-morph": ""
+  }
+  message: { class: typeof TOAST_MESSAGE_CLASS }
+  close: { class: typeof TOAST_CLOSE_CLASS }
+}
+
+/**
+ * The attributes for the toast region.
+ *
+ * The region is `role="status"` and not `role="alert"`. A message that comes
+ * because something went well should not interrupt what the screen reader is
+ * doing.
+ *
+ * `data-ignore-morph` is not optional. `<lt-toast>` creates and removes its
+ * message elements inside the region, and without the attribute the Datastar
+ * morph tears them away at the next patch, because the server's version of
+ * the region is empty. The attribute must be in the HTML the server sends:
+ * the component cannot set it on itself, since the morph reads it from the
+ * server's node.
+ */
+export const toast = ({
+  label = DEFAULT_TEXTS.toastRegion,
+  closeLabel,
+}: ToastOptions = {}): ToastAttributes => ({
+  host: attributes({
+    class: TOAST_CLASS,
+    role: "status" as const,
+    "aria-live": "polite" as const,
+    // `status` is atomic by default, and then the whole stack is announced
+    // again for every message that is added.
+    "aria-atomic": "false" as const,
+    "aria-label": label,
+    "close-label": closeLabel,
+    "data-ignore-morph": "" as const,
+  }),
+  message: attributes({ class: TOAST_MESSAGE_CLASS }),
+  close: attributes({ class: TOAST_CLOSE_CLASS }),
+})

package/src/diagnostics/core.ts

@@ -0,0 +1,227 @@
+/**
+ * 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
+  accessibility_tree_raw(pointer: number, length: number): number
+  accessibility_facts_raw(): void
+  accessibility_roles_raw(): void
+  accessibility_states_raw(): void
+  result_ptr(): number
+  result_len(): number
+}
+
+/**
+ * @internal Not part of the package's API.
+ *
+ * An instance of the core and the helpers every call goes through: the text
+ * written into the module's memory, and the answer read back. Not part of
+ * the package: `index.ts` exports `loadCore`. The tests reach the core's
+ * other functions, such as the accessibility tree, through this.
+ */
+export function instantiate(source: BufferSource | WebAssembly.Module) {
+  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 { e, write, read, answer }
+}
+
+/** Loads the core from the module's bytes or an already compiled module. */
+export function loadCore(source: BufferSource | WebAssembly.Module): Core {
+  const { e, write, read, answer } = instantiate(source)
+
+  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)
+}