@lo-tek/interfaces 0.0.0 → 0.38.0

package/src/vocabulary/types.ts

@@ -0,0 +1,228 @@
+/**
+ * The shape of the vocabulary: the elements and classes LO-TEK has.
+ *
+ * `elements.ts` and `classes.ts` next to this file are generated by
+ * `scripts/generate-vocabulary.ts`, and are the source the manifest is
+ * written from (`scripts/generate-manifest.ts`). The core and all the tools
+ * read the manifest, not these files, so they are not part of the package's
+ * API.
+ */
+
+export type Attribute = (
+  | { type: "flag" | "text" | "number" }
+  | { type: "values"; values: readonly string[] }
+) & { description?: string }
+
+/**
+ * A part of an element, such as the control in `<lt-field>`. `selector` is
+ * the one the component finds the part with, relative to the element.
+ * `content` is what the part takes: `text` is text and phrasing without
+ * interactive elements, `free` free content, `parts` only the other parts,
+ * and `none` no text: the part is a control, such as a `<select>` with its
+ * `<option>` elements, or an element the component fills. Without `multiple`
+ * the first one applies, and with `unique` another part of the same kind is
+ * an error, not ordinary content. Without `optional` the element needs the
+ * part.
+ */
+export type Part = {
+  selector: string
+  description: string
+  content: "text" | "free" | "parts" | "none"
+  multiple?: true
+  /** Another part of the same kind is an error, not ordinary content. */
+  unique?: true
+  optional?: true
+  /** The part must have an id from the server; the component never writes one. */
+  stableId?: true
+  /** LO-TEK demands a name for the part. */
+  name?: Name
+}
+
+/**
+ * A name LO-TEK demands where WAI-ARIA does not, or one the component gives
+ * itself. WAI-ARIA's own demands, by role, are in the core, and `lotek check`
+ * reports an element the markup gives no name (`without-name`).
+ *
+ * `after` is the part the component points `aria-labelledby` at when the
+ * markup has neither `aria-label` nor `aria-labelledby`, such as the heading
+ * of a dialog; then that part's name is enough. With `id` the part must have
+ * an id from the template, since the component does not write one. With
+ * `component` the component names it itself, after what the other rules
+ * check, such as the list in a suggestion field after the label, and no
+ * rule judges its name in the markup.
+ *
+ * Each of them is held to the component by a contract in
+ * `interfaces/scripts/accessibility/contracts.ts`: a mutation that takes the name away
+ * must fail in the browsers, and `lotek check` must report it.
+ */
+export type Name = { after?: string; id?: true; component?: true }
+
+/**
+ * An event an element dispatches, such as `dialog-toggle`. `detail` is the
+ * fields in `event.detail` with their types, and is absent when the event
+ * has none.
+ */
+export type ElementEvent = {
+  detail?: Record<string, "boolean" | "string" | "number">
+}
+
+export type Element = {
+  link: string
+  description?: string
+  attributes: Record<string, Attribute>
+  /** Empty for the elements that create all of their content themselves. */
+  parts?: Record<string, Part>
+  events?: Record<string, ElementEvent>
+  /** LO-TEK demands a name for the element itself. */
+  name?: Name
+  /** The texts the element writes itself, by their name in `DEFAULT_TEXTS`. */
+  texts?: Record<string, DefaultText>
+  /** Attributes that have been removed, with what applies instead. */
+  removed?: Record<string, string>
+}
+
+/**
+ * A text the element writes itself when nobody has given it another, from
+ * `DEFAULT_TEXTS`. `replacedBy` is the attributes that replace it; any one
+ * of them is enough, and `lotek check` warns when none is there on a page in
+ * another language than the text's.
+ */
+export type DefaultText = { text: string; replacedBy: readonly string[] }
+
+/**
+ * A text the stylesheet shows in `::after` on an element with the class and
+ * `attribute`, with `value` when the selector requires one, and none of the
+ * attributes in `unless`. `variable` is the CSS variable that replaces it.
+ */
+export type CssText = {
+  variable: string
+  text: string
+  attribute: string
+  value?: string
+  unless?: readonly string[]
+}
+
+/** The content of `elements.ts`: tag to element. */
+export type Elements = Record<string, Element>
+
+/**
+ * An attribute a class takes, such as `data-variant` on `lt-button`.
+ *
+ * `flag` is an attribute that works by being present, such as
+ * `data-interactive` on `lt-card`. The stylesheet only asks whether it
+ * exists, so it has no values.
+ */
+export type ClassAttribute = {
+  values: readonly string[]
+  default?: string
+  flag?: true
+}
+
+export type ClassInfo = {
+  /** The path of the component page, such as `button`. */
+  component: string
+  title: string
+  description: string
+  link: string
+  /** What the element with the class takes as content, in the same words as the parts. */
+  content: Part["content"]
+  /**
+   * The class this one is part of, when it is only part of another
+   * component's markup, such as `lt-card__title` in `lt-card`. The parent has
+   * a part that matches it.
+   */
+  partOf?: string
+  /** The parts the markup consists of, for the classes with a fixed structure. */
+  parts?: Record<string, Part>
+  /** LO-TEK demands a name for the element with the class. */
+  name?: Name
+  /** The texts the stylesheet shows on it. */
+  texts?: readonly CssText[]
+  attributes: Record<string, ClassAttribute>
+}
+
+/** The content of `classes.ts`: class name to class. */
+export type Classes = Record<string, ClassInfo>
+
+/**
+ * The tokens in the manifest: what a stylesheet outside the package can
+ * build on. The colours are listed as axes with what they are for, not as
+ * values, since a theme can have values other than LO-TEK's defaults.
+ * `components` is the component variables per component, with the fallback
+ * in the stylesheet as the value.
+ */
+export type ManifestTokens = {
+  /** The spacing scale, name to value. */
+  spacing: Record<string, string>
+  breakpoints: Record<string, string>
+  containers: Record<string, string>
+  colors: {
+    /** The families, with what each is for. */
+    families: Record<string, string>
+    /** The roles as they are written in CSS, with what each is for. */
+    roles: Record<string, string>
+    /** The layers only the neutral family has. */
+    layers: Record<string, string>
+    /** Every `--lt-color-*` name the package ships. */
+    tokens: readonly string[]
+  }
+  /** Component to variable name to default value. */
+  components: Record<string, Record<string, string>>
+}
+
+/** What an option of a builder function takes. */
+export type BuilderOptionType =
+  | { kind: "values"; values: readonly string[] }
+  | { kind: "flag" | "text" | "number" | "textList" }
+
+/** The shape of what a builder function returns. */
+export type BuilderReturns = { optional?: boolean } & (
+  | { kind: "attributes" | "text" }
+  | { kind: "values"; values: readonly string[] }
+  | { kind: "list"; of: BuilderReturns }
+  | { kind: "group"; fields: Record<string, BuilderReturns> }
+)
+
+/**
+ * A builder function in `lt`, such as `button`, with its options and the
+ * shape of its result. `table`, which the generator behind the Kotlin
+ * version uses, is left out here.
+ */
+export type Builder = {
+  name: string
+  options: {
+    name: string
+    required: boolean
+    type: BuilderOptionType
+    description?: string
+  }[]
+  returns: BuilderReturns
+}
+
+/**
+ * The shape of `manifest.json`, as `manifest.schema.json` describes it. The
+ * elements are the same as in `elements.ts`. A class attribute in the
+ * manifest is either a list of values or a flag, and a flag has no values,
+ * unlike `classes.ts`, where the flag has an empty list.
+ */
+export type Manifest = {
+  schemaVersion: number
+  version: string
+  elements: Elements
+  tokens: ManifestTokens
+  builders: Builder[]
+  classes: Record<
+    string,
+    Omit<ClassInfo, "attributes"> & {
+      attributes: Record<
+        string,
+        {
+          values?: readonly string[]
+          default?: string
+          flag?: true
+          description?: string
+        }
+      >
+    }
+  >
+}

package/src/wasi-host.ts

@@ -0,0 +1,155 @@
+/// <reference types="node" />
+/**
+ * The host for the command line in Node: runs the WASI module `lotek.wasm`
+ * with Node's own `node:wasi`. Used by `cli.ts`, and by the VS Code
+ * extension, which starts the language server, `lotek lsp`, this way.
+ *
+ * The commands are written once, in Rust (`cli/`). The same code is the
+ * executable from `cargo install` and what `java -jar` runs, so the answers
+ * are the same everywhere. The host does only what WASI cannot:
+ *
+ * - opens the folders the module reads and writes in, the working directory
+ *   and the rest of the file system, so both relative and absolute paths work;
+ * - fetches the addresses `lotek check` gets, since WASI has no network, and
+ *   gives the page to the module as a file (see `cli/src/fetch.rs`);
+ * - says when standard input is a terminal, which WASI cannot see.
+ */
+
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { isatty } from "node:tty"
+import { fileURLToPath } from "node:url"
+
+const windows = process.platform === "win32"
+
+/**
+ * A path as the WASI module sees it.
+ *
+ * On Windows every drive is opened as its own folder, `C:\` as `/c`, and
+ * the backslashes become slashes. Elsewhere the path is the same.
+ */
+function forWasi(path: string): string {
+  if (!windows) return path
+  const absolute = /^([A-Za-z]):[\\/](.*)$/.exec(path)
+  if (absolute)
+    return `/${absolute[1].toLowerCase()}/${absolute[2].replace(/\\/g, "/")}`
+  return path.replace(/\\/g, "/")
+}
+
+/** An argument for the WASI module: the path in a file or in a `--flag=value`. */
+function toModule(part: string): string {
+  const flag = /^(--[^=]+=)(.*)$/s.exec(part)
+  return flag ? flag[1] + forWasi(flag[2]) : forWasi(part)
+}
+
+/**
+ * Runs one command, like `["check", "form.html"]`, and gives the exit code.
+ * `module` is the path to `lotek.wasm`, and `packageDir` the folder with the
+ * package's files: the manifest, the colour contract, the rulebooks and the
+ * components. The command line carries none of them, and gets the folder as
+ * `LOTEK_PACKAGE`.
+ */
+export async function runCommandLine(
+  module: string | URL,
+  args: string[],
+  packageDir: string | URL,
+): Promise<number> {
+  /*
+   * The whole file system is opened, and the module is told where the working
+   * directory is and goes there itself. A WASI module otherwise starts in `/`,
+   * and a relative path was read from the root.
+   */
+  const preopens: Record<string, string> = {}
+  if (windows) {
+    // Only the drives that exist. A folder that cannot be opened stops
+    // `node:wasi` before the module starts, and most machines have only C:.
+    for (const letter of "abcdefghijklmnopqrstuvwxyz") {
+      const drive = `${letter.toUpperCase()}:\\`
+      if (existsSync(drive)) preopens[`/${letter}`] = drive
+    }
+  } else preopens["/"] = "/"
+
+  /*
+   * The addresses are fetched here and given to the module as files.
+   *
+   * The file has the address, the status code (0 when nobody answered), the
+   * content type or the reason, and the page, in that order. The module
+   * judges the answer: whether it is a page and whether the status code is
+   * fine.
+   */
+  let fetchedDir: string | undefined
+  const warn = process.emitWarning
+  try {
+    const address = /^https?:\/\//i
+    const moduleArgs: string[] = []
+    for (const [index, part] of args.entries()) {
+      if (args[0] !== "check" || index === 0 || !address.test(part)) {
+        moduleArgs.push(toModule(part))
+        continue
+      }
+      fetchedDir ??= mkdtempSync(join(tmpdir(), "lotek-"))
+      let answer: string
+      try {
+        // As in the executable: a server that never answers must not hang a
+        // CI job until it is killed.
+        const response = await fetch(part, {
+          signal: AbortSignal.timeout(30_000),
+        })
+        const type = response.headers.get("content-type") ?? ""
+        answer = `${part}\n${response.status}\n${type}\n${await response.text()}`
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error)
+        answer = `${part}\n0\n${reason.replace(/\n/g, " ")}\n`
+      }
+      const file = join(fetchedDir, `${index}.txt`)
+      writeFileSync(file, answer)
+      moduleArgs.push(`--fetched=${forWasi(file)}`)
+    }
+
+    // `node:wasi` is marked experimental, and says so in the console. That is
+    // nothing the user of the command line can do anything about.
+    process.emitWarning = ((warning: string | Error, ...rest: unknown[]) => {
+      if (String(warning).includes("WASI")) return
+      ;(warn as (...a: unknown[]) => void).call(process, warning, ...rest)
+    }) as typeof process.emitWarning
+
+    const { WASI } = await import("node:wasi")
+    const wasi = new WASI({
+      version: "preview1",
+      args: ["lotek", ...moduleArgs],
+      env: {
+        LOTEK_WORKDIR: forWasi(process.cwd()),
+        LOTEK_PACKAGE: forWasi(
+          packageDir instanceof URL ? fileURLToPath(packageDir) : packageDir,
+        ),
+        // So the messages show the paths as `C:\\…`, not as `/c/…`.
+        ...(windows ? { LOTEK_WINDOWS: "1" } : {}),
+        // `isatty(0)`, not `process.stdin.isTTY`: touching `process.stdin`
+        // puts a pipe in non-blocking mode, and the module then gave up
+        // reading before the writer was done, as in `curl … | lotek check`.
+        ...(isatty(0) ? { LOTEK_TERMINAL: "1" } : {}),
+      },
+      preopens,
+      returnOnExit: true,
+    })
+
+    const compiled = await WebAssembly.compile(readFileSync(module))
+    const instance = await WebAssembly.instantiate(
+      compiled,
+      wasi.getImportObject() as WebAssembly.Imports,
+    )
+    return wasi.start(instance)
+  } finally {
+    // Also when the module crashes: the fetched pages must not be left
+    // behind, and the warnings come back for the rest of the process.
+    process.emitWarning = warn
+    if (fetchedDir) rmSync(fetchedDir, { recursive: true, force: true })
+  }
+}