@abide/abide 0.58.0 → 0.101.0

package/src/shared/Attributes.ts

@@ -0,0 +1,339 @@
+// 33.23 — WHAT AN ELEMENT TAKES, AS A COMPONENT'S PROPS, for a component that spreads the rest of its
+// props onto one: `props<{ size?: Size } & Attributes<'button'>>()` holds a caller to the attributes
+// a `<button>` has, and types `onclick`'s event.
+//
+// DERIVED FROM THE DOM TYPES TypeScript ships rather than written out per element, so it moves when
+// they do: every writable property of the element that is not a method or a node is an attribute,
+// under its HTML spelling. What the DOM types say and what an attribute is part company in four
+// places, and each is named below rather than guessed — a value is written as text (32.37), so the
+// property's type is widened to what writes the same attribute; and an attribute with no property,
+// or a property that is not the attribute, is added by hand.
+
+import type { BooleanAttribute } from './BOOLEAN_ATTRIBUTES.ts'
+
+/**
+ * The element's properties an attribute sets: writable, and neither a method nor a node.
+ *
+ * NAMED KEYS ONLY. A form indexes its controls by name and a select its options by position, and an
+ * index signature mapped as an attribute typed every attribute a caller passed as whatever it held.
+ * Taken through a remapping, which keeps the named keys where `keyof` alone collapses them into the
+ * index's `string`.
+ */
+type Reflected<Element> = {
+    [Key in Named<Element>]-?: Element[Key] extends (
+        ...given: never[]
+    ) => unknown
+        ? never
+        : Element[Key] extends
+                | Node
+                | NodeList
+                | HTMLCollection
+                | DOMTokenList
+                | CSSStyleDeclaration
+                | DOMStringMap
+                | readonly Element[]
+                | null
+          ? never
+          : (<Same>() => Same extends { [K in Key]: Element[Key] }
+                  ? 1
+                  : 2) extends <Same>() => Same extends {
+                  -readonly [K in Key]: Element[Key]
+              }
+                  ? 1
+                  : 2
+            ? Key
+            : never
+}[Named<Element>]
+
+/** `Element`'s keys without its index signatures. */
+type Named<Element> = keyof {
+    [Key in keyof Element as string extends Key
+        ? never
+        : number extends Key
+          ? never
+          : Key]: Element[Key]
+}
+
+/** The properties whose attribute is not their name lowercased. */
+type Renamed = {
+    className: 'class'
+    htmlFor: 'for'
+    httpEquiv: 'http-equiv'
+    acceptCharset: 'accept-charset'
+}
+
+/** A property's attribute: renamed, `ariaLabel` as `aria-label`, or lowercased. */
+type AttributeName<Key> = Key extends keyof Renamed
+    ? Renamed[Key]
+    : Key extends `aria${infer Rest}`
+      ? `aria-${Lowercase<Rest>}`
+      : Lowercase<Key & string>
+
+/**
+ * What writes the attribute a property's type stands for (32.37).
+ *
+ * An attribute HTML reads by presence takes a boolean. Every other boolean is written as its text,
+ * so `"true"` and `"false"` write it too, and a number is written as its digits. `aria-*` is text
+ * the DOM types spell as a string, which a boolean or a number writes as well. `autocomplete`'s
+ * token list is suggested rather than enforced: it is open-ended by the standard.
+ */
+type Written<Name, Value> = Name extends `aria-${string}`
+    ? string | number | boolean
+    : Name extends 'autocomplete'
+      ? Value | (string & {})
+      : [Value] extends [boolean]
+        ? Name extends BooleanAttribute
+            ? boolean
+            : boolean | 'true' | 'false'
+        : [Value] extends [number]
+          ? number | `${number}`
+          : Value
+
+/** Attributes some element has that no writable property of it reflects. */
+type Unreflected<Tag> = (Tag extends
+    | 'button'
+    | 'fieldset'
+    | 'input'
+    | 'object'
+    | 'output'
+    | 'select'
+    | 'textarea'
+    ? { form?: string }
+    : unknown) &
+    (Tag extends 'input' ? { list?: string } : unknown)
+
+/**
+ * The attributes element `Tag` takes, typed as a component's props: a caller passing them is held to
+ * what the element takes, and its listeners are handed that element's events.
+ *
+ * 33.26 — AN SVG ELEMENT TAKES THE SVG ATTRIBUTES. A tag both namespaces name — `a`, `script`,
+ * `style`, `title` — is the HTML element, which is what it is outside an `<svg>`.
+ */
+export type Attributes<
+    Tag extends keyof HTMLElementTagNameMap | keyof SVGElementTagNameMap,
+> = Tag extends keyof HTMLElementTagNameMap
+    ? HtmlAttributes<Tag>
+    : Tag extends keyof SVGElementTagNameMap
+      ? SvgAttributes<Tag>
+      : never
+
+/** An HTML element's attributes, derived from what its DOM type reflects. */
+type HtmlAttributes<Tag extends keyof HTMLElementTagNameMap> = {
+    [Key in Reflected<HTMLElementTagNameMap[Tag]> as Key extends `on${string}`
+        ? never
+        : AttributeName<Key>]?: Written<
+        AttributeName<Key>,
+        NonNullable<HTMLElementTagNameMap[Tag][Key]>
+    > | null
+} & {
+    [Event in keyof HTMLElementEventMap as `on${Event}`]?: (
+        event: HTMLElementEventMap[Event] & {
+            currentTarget: HTMLElementTagNameMap[Tag]
+        },
+    ) => unknown
+} & Unreflected<Tag> &
+    Global & {
+        itemscope?: boolean
+        itemtype?: string
+        itemprop?: string
+        itemid?: string
+        itemref?: string
+    }
+
+/**
+ * An SVG element's attributes: one set for every SVG element, as written out below.
+ *
+ * WRITTEN OUT RATHER THAN DERIVED. An SVG element's DOM type reflects its attributes as read-only
+ * animated values — `cx` is an `SVGAnimatedLength` — so the derivation an HTML element is typed by
+ * finds almost none of them. One set for every element is what the SVG specification's own
+ * presentation attributes are, and the geometry a given element ignores is harmless where it is
+ * written. A length or a number is written as its text (32.37), so each takes either.
+ */
+type SvgAttributes<Tag extends keyof SVGElementTagNameMap> = {
+    [Name in SvgAttribute]?: string | number | null
+} & {
+    [Event in keyof SVGElementEventMap as `on${Event}`]?: (
+        event: SVGElementEventMap[Event] & {
+            currentTarget: SVGElementTagNameMap[Tag]
+        },
+    ) => unknown
+} & Global & {
+        id?: string
+        lang?: string
+        tabindex?: number | `${number}` | null
+        role?: string
+    }
+
+/** Attributes every element takes that no reflected property types. */
+type Global = {
+    class?: string
+    style?: string
+    [data: `data-${string}`]: unknown
+    [aria: `aria-${string}`]: string | number | boolean | null | undefined
+}
+
+/** The SVG attributes, presentation attributes included, under the names SVG spells them. */
+type SvgAttribute =
+    // Presentation attributes, which a stylesheet can set as well.
+    | 'alignment-baseline'
+    | 'baseline-shift'
+    | 'clip-path'
+    | 'clip-rule'
+    | 'color'
+    | 'color-interpolation'
+    | 'color-interpolation-filters'
+    | 'cursor'
+    | 'direction'
+    | 'display'
+    | 'dominant-baseline'
+    | 'fill'
+    | 'fill-opacity'
+    | 'fill-rule'
+    | 'filter'
+    | 'flood-color'
+    | 'flood-opacity'
+    | 'font-family'
+    | 'font-size'
+    | 'font-size-adjust'
+    | 'font-stretch'
+    | 'font-style'
+    | 'font-variant'
+    | 'font-weight'
+    | 'image-rendering'
+    | 'letter-spacing'
+    | 'lighting-color'
+    | 'marker-end'
+    | 'marker-mid'
+    | 'marker-start'
+    | 'mask'
+    | 'mask-type'
+    | 'opacity'
+    | 'overflow'
+    | 'paint-order'
+    | 'pointer-events'
+    | 'shape-rendering'
+    | 'stop-color'
+    | 'stop-opacity'
+    | 'stroke'
+    | 'stroke-dasharray'
+    | 'stroke-dashoffset'
+    | 'stroke-linecap'
+    | 'stroke-linejoin'
+    | 'stroke-miterlimit'
+    | 'stroke-opacity'
+    | 'stroke-width'
+    | 'text-anchor'
+    | 'text-decoration'
+    | 'text-rendering'
+    | 'transform'
+    | 'transform-origin'
+    | 'unicode-bidi'
+    | 'vector-effect'
+    | 'visibility'
+    | 'white-space'
+    | 'word-spacing'
+    | 'writing-mode'
+    // The document and its viewport.
+    | 'xmlns'
+    | 'version'
+    | 'viewBox'
+    | 'preserveAspectRatio'
+    | 'focusable'
+    // Geometry.
+    | 'x'
+    | 'y'
+    | 'x1'
+    | 'y1'
+    | 'x2'
+    | 'y2'
+    | 'cx'
+    | 'cy'
+    | 'r'
+    | 'rx'
+    | 'ry'
+    | 'fx'
+    | 'fy'
+    | 'fr'
+    | 'width'
+    | 'height'
+    | 'd'
+    | 'points'
+    | 'pathLength'
+    | 'href'
+    // Text.
+    | 'dx'
+    | 'dy'
+    | 'rotate'
+    | 'textLength'
+    | 'lengthAdjust'
+    | 'startOffset'
+    | 'method'
+    | 'spacing'
+    // Paint servers, clips, masks and markers.
+    | 'offset'
+    | 'gradientUnits'
+    | 'gradientTransform'
+    | 'spreadMethod'
+    | 'patternUnits'
+    | 'patternContentUnits'
+    | 'patternTransform'
+    | 'clipPathUnits'
+    | 'maskUnits'
+    | 'maskContentUnits'
+    | 'markerUnits'
+    | 'markerWidth'
+    | 'markerHeight'
+    | 'refX'
+    | 'refY'
+    | 'orient'
+    // Filters.
+    | 'filterUnits'
+    | 'primitiveUnits'
+    | 'in'
+    | 'in2'
+    | 'result'
+    | 'mode'
+    | 'type'
+    | 'values'
+    | 'operator'
+    | 'stdDeviation'
+    | 'k1'
+    | 'k2'
+    | 'k3'
+    | 'k4'
+    | 'scale'
+    | 'xChannelSelector'
+    | 'yChannelSelector'
+    | 'baseFrequency'
+    | 'numOctaves'
+    | 'seed'
+    | 'stitchTiles'
+    | 'surfaceScale'
+    | 'diffuseConstant'
+    | 'specularConstant'
+    | 'specularExponent'
+    | 'azimuth'
+    | 'elevation'
+    | 'tableValues'
+    | 'slope'
+    | 'intercept'
+    | 'amplitude'
+    | 'exponent'
+    // Animation.
+    | 'attributeName'
+    | 'begin'
+    | 'dur'
+    | 'end'
+    | 'repeatCount'
+    | 'repeatDur'
+    | 'restart'
+    | 'from'
+    | 'to'
+    | 'by'
+    | 'keyTimes'
+    | 'keySplines'
+    | 'calcMode'
+    | 'additive'
+    | 'accumulate'
+    | 'path'
+    | 'keyPoints'

package/src/shared/BOOLEAN_ATTRIBUTES.ts

@@ -0,0 +1,41 @@
+/**
+ * The attributes HTML reads by presence, written present or absent by the value's truthiness.
+ *
+ * 32.37 — THE ATTRIBUTES HTML READS BY PRESENCE, whose value is never looked at:
+ * `disabled="false"` is a disabled button. So these, and only these, are written present or absent
+ * by the value's truthiness. Every other attribute is written as its text — `aria-expanded="false"`
+ * and `spellcheck="false"` mean something their absence does not. A leaf, because the compiler's
+ * markup and the client's bindings both read it.
+ */
+const NAMES = [
+    'allowfullscreen',
+    'async',
+    'autofocus',
+    'autoplay',
+    'checked',
+    'controls',
+    'default',
+    'defer',
+    'disabled',
+    'formnovalidate',
+    'hidden',
+    'inert',
+    'ismap',
+    'itemscope',
+    'loop',
+    'multiple',
+    'muted',
+    'nomodule',
+    'novalidate',
+    'open',
+    'playsinline',
+    'readonly',
+    'required',
+    'reversed',
+    'selected',
+] as const
+
+/** 33.23 — one of them, for `Attributes` to type by presence. */
+export type BooleanAttribute = (typeof NAMES)[number]
+
+export const BOOLEAN_ATTRIBUTES: ReadonlySet<string> = new Set(NAMES)

package/src/shared/CHILDREN.ts

@@ -0,0 +1,11 @@
+/**
+ * The prop name a caller's between-the-tags content is passed under.
+ *
+ * 33.16 — `children` is always accepted and never declared, so a component reads it through
+ * `<slot/>` (32.18) rather than through `props<T>()`.
+ *
+ * A LEAF, because the two lanes have to agree about it exactly: the server emitter puts a markup
+ * thunk under this name and the child's `<slot/>` reads it back, and the client emitter puts the
+ * markup-and-mount pair under it for the same position to read.
+ */
+export const CHILDREN = 'children'

package/src/shared/CURRENT_ROUTER.ts

@@ -0,0 +1,25 @@
+/**
+ * What a router offers `navigate`: a way to go to a URL.
+ *
+ * Named for what it DOES rather than what it is: `Navigator` is a DOM global, and a routing file
+ * is the one place a reader would take the two for each other.
+ */
+export type Navigable = {
+    go(url: URL | string, options: NavigateOptions): Promise<void>
+}
+
+export type NavigateOptions = { replace?: boolean; keepScroll?: boolean }
+
+/**
+ * The router this document has, or null.
+ *
+ * 30.7's `navigate` takes a URL and nothing else, so the router it drives cannot be an argument —
+ * and a document has exactly one, which is what makes a single slot the honest shape rather than a
+ * registry keyed on something.
+ *
+ * A LEAF, and that is what keeps `#ui` out of `#shared`'s graph: the client router WRITES this on
+ * start and `navigate` READS it, so the app-facing name resolves through the shared seam while the
+ * implementation stays on the side that has a document. On a server it is null and `navigate`
+ * says so.
+ */
+export const CURRENT_ROUTER: { current: Navigable | null } = { current: null }

package/src/shared/CopyOptions.ts

@@ -0,0 +1,19 @@
+/**
+ * What a `GET`'s browser copy has to behave by, as the build writes it into the wrapper.
+ *
+ * 18.4 — WHAT A `GET`'s VALUE DECLARES THAT ITS BROWSER COPY HAS TO BEHAVE BY, as the build reads
+ * it off the declaration and writes it into the wrapper: data, because it crosses as text.
+ * `structural` is named rather than carried, being abide's own comparator on both sides; an app's
+ * own has no serialisation and stays the server's, as a function `by` or `tags` does.
+ */
+export type CopyOptions = {
+    by?: string
+    tags?: string[]
+    identity?: 'structural'
+    /**
+     * The handler is an async generator, so its answer is a stream the copy reads as it lands.
+     *
+     * 16.32.
+     */
+    stream?: true
+}

package/src/shared/DEBUG_META.ts

@@ -0,0 +1,6 @@
+/**
+ * The `<meta>` the server writes `DEBUG` into, and a browser reads it back from.
+ *
+ * 28.11.
+ */
+export const DEBUG_META = 'abide-debug'

package/src/shared/EARLY_CALLS.ts

@@ -0,0 +1,8 @@
+/**
+ * The global a page's early-call script leaves its started calls on.
+ *
+ * 41.20 — where a page's early-call script leaves each call it started, keyed by `rpcRequest`'s
+ * `key`, for the browser's own `wire` to take. A global because the script runs before any module
+ * does, and a leaf because the server writes the name into the script and the browser reads it.
+ */
+export const EARLY_CALLS = '__abideCalls'

package/src/shared/FAILURE_STATUS_TEXT.ts

@@ -0,0 +1,48 @@
+/**
+ * The reason phrase a failure status carries when nothing named one.
+ *
+ * 17.8 — RFC 9110's, plus the registered codes outside it. Bun answers `statusText` empty, so
+ * without this a refusal crosses the wire with nothing to read but the number.
+ */
+export const FAILURE_STATUS_TEXT: Readonly<Record<number, string>> = {
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    402: 'Payment Required',
+    403: 'Forbidden',
+    404: 'Not Found',
+    405: 'Method Not Allowed',
+    406: 'Not Acceptable',
+    407: 'Proxy Authentication Required',
+    408: 'Request Timeout',
+    409: 'Conflict',
+    410: 'Gone',
+    411: 'Length Required',
+    412: 'Precondition Failed',
+    413: 'Content Too Large',
+    414: 'URI Too Long',
+    415: 'Unsupported Media Type',
+    416: 'Range Not Satisfiable',
+    417: 'Expectation Failed',
+    418: "I'm a teapot",
+    421: 'Misdirected Request',
+    422: 'Unprocessable Content',
+    423: 'Locked',
+    424: 'Failed Dependency',
+    425: 'Too Early',
+    426: 'Upgrade Required',
+    428: 'Precondition Required',
+    429: 'Too Many Requests',
+    431: 'Request Header Fields Too Large',
+    451: 'Unavailable For Legal Reasons',
+    500: 'Internal Server Error',
+    501: 'Not Implemented',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+    504: 'Gateway Timeout',
+    505: 'HTTP Version Not Supported',
+    506: 'Variant Also Negotiates',
+    507: 'Insufficient Storage',
+    508: 'Loop Detected',
+    510: 'Not Extended',
+    511: 'Network Authentication Required',
+}

package/src/shared/Failed.ts

@@ -0,0 +1,146 @@
+// THE ONE REFUSAL TYPE, in-process and over a wire alike. RULEBOOK 15.1: a refusal is a
+// declared VALUE, not a status code and not a transport concern — so the same object a
+// `transform` returns (4.6) is the one a handler answers with (16.40) and the one a client
+// narrows on (3.1), with nothing converting between three spellings on the way.
+//
+// IT IS AN `Error` AND IT IS NEVER THROWN, which is the pairing that takes the most
+// explaining. 15.5 makes RETURNING one the refusal and 15.4 makes constructing one inert,
+// so the `Error` base is not there to be thrown — it is there for the stack, for
+// `console` rendering it as a failure rather than as a bag, and so that a `catch` that
+// caught one from somewhere else still finds the shape it expects.
+
+import { FAILURE_STATUS_TEXT } from './FAILURE_STATUS_TEXT.ts'
+
+/**
+ * A refusal: a named, status-carrying `Error` that is returned, never thrown.
+ *
+ * `Data` IS UNCONSTRAINED, and that is the registry row rather than an oversight here.
+ * `refuse.named` is where `JsonValue` binds, because that is the factory whose refusals
+ * cross a wire — and `Issues<T>` is the case that proves the two must differ: it is
+ * `Partial<Record<…, string[]>>`, whose members are `string[] | undefined`, so it is a
+ * perfectly good refusal payload that `JsonValue` does not describe.
+ */
+export type Failed<Name extends string = string, Data = undefined> = Error & {
+    name: Name
+    status: number
+    message: string
+    data: Data
+}
+
+/**
+ * Whether a value is a refusal: a string `name`, a number `status` and a string `message`.
+ *
+ * 15.6: STRUCTURAL, and the clause is load-bearing rather than a preference. A `Failed`
+ * that crossed a wire was rebuilt from JSON by whatever revived it, so it is not
+ * `instanceof Error` and carries no brand this side put on it — a nominal check would
+ * answer false for the case the type exists to serve.
+ *
+ * THE THREE FIELDS ARE THE TEST, and `data` is not one of them: a refusal declaring no
+ * data has `undefined` there, and `JSON.stringify` drops an `undefined` member entirely,
+ * so requiring the key would fail exactly the values that made the trip.
+ *
+ * WHAT IT ADMITS is anything carrying a name, a status and a message — an error object
+ * from some other library that happens to have all three. That is 15.6 working as written
+ * rather than a hole in it: the clause says what a refusal IS, and something with all
+ * three is one.
+ */
+export function isFailed(value: unknown): value is Failed<string, unknown> {
+    if (value === null || typeof value !== 'object') return false
+    const held = value as {
+        name?: unknown
+        status?: unknown
+        message?: unknown
+    }
+    return (
+        typeof held.name === 'string' &&
+        typeof held.status === 'number' &&
+        typeof held.message === 'string'
+    )
+}
+
+/**
+ * Builds a `Failed` with all four fields enumerable.
+ *
+ * The one place a `Failed` is built, so the four fields are written in one order and
+ * nothing downstream meets two shapes. 15.4: INERT. Nothing here throws, nothing is
+ * registered, and no caller is told — a `Failed` nobody returns is an object nobody reads,
+ * which is what makes 15.10 a compile-time rule rather than a runtime one.
+ *
+ * `message` IS ASSIGNED RATHER THAN LEFT TO THE CONSTRUCTOR. `new Error(m)` writes an
+ * own property that is NOT enumerable, so `JSON.stringify` of a refusal dropped it — the wire
+ * carried `{"name":"HttpError","status":503}` and `isFailed` answered FALSE for what came back,
+ * because the message is one of the three fields 15.6 tests. The type's whole point is surviving
+ * that trip. `name`, `status` and `data` are ordinary assignments and already enumerable.
+ */
+export function failed<Name extends string, Data>(
+    name: Name,
+    status: number,
+    message: string,
+    data: Data,
+): Failed<Name, Data> {
+    // Constructed with NO argument the `Error` installs no own `message` at all, so the
+    // assignment below is the first writer and lands enumerable like the other three —
+    // where redefining the constructor's own property reconfigures a property already there.
+    const refusal = new Error() as Failed<Name, Data>
+    refusal.message = message
+    refusal.name = name
+    refusal.status = status
+    refusal.data = data
+    return refusal
+}
+
+/**
+ * A refusal as it crosses a wire: a Problem Details object (RFC 9457).
+ *
+ * 15.1 — `type` is the refusal's name, or `about:blank` for an undeclared one, whose `title` is then
+ * its status's reason phrase; `detail` is the message, and `data` rides as an extension member.
+ */
+export type Problem = {
+    type: string
+    title: string
+    status: number
+    detail: string
+    data?: unknown
+}
+
+/**
+ * The Problem Details a refusal crosses a wire as.
+ *
+ * 15.1 — whatever else the refusal carried is dropped. `isFailed` admits another library's error,
+ * whose `message` the constructor left unenumerable, so the fields are read rather than spread.
+ */
+export function problemOf(failure: Failed<string, unknown>): Problem {
+    const undeclared = failure.name === 'HttpError'
+    const problem: Problem = {
+        type: undeclared ? 'about:blank' : failure.name,
+        title: undeclared
+            ? (FAILURE_STATUS_TEXT[failure.status] ?? failure.name)
+            : failure.name,
+        status: failure.status,
+        detail: failure.message,
+    }
+    if (failure.data !== undefined) problem.data = failure.data
+    return problem
+}
+
+/** Whether a value read off a wire is Problem Details: a `type` and a numeric `status`. */
+export function isProblem(value: unknown): value is Problem {
+    if (value === null || typeof value !== 'object') return false
+    const held = value as { type?: unknown; status?: unknown }
+    return typeof held.type === 'string' && typeof held.status === 'number'
+}
+
+/** The refusal Problem Details names, rebuilt: `about:blank` is an undeclared `HttpError`. */
+export function failedFrom(problem: Problem): Failed<string, unknown> {
+    return failed(
+        problem.type === 'about:blank' ? 'HttpError' : problem.type,
+        problem.status,
+        problem.detail ?? problem.title ?? '',
+        problem.data,
+    )
+}
+
+/** Whether a value is the refusal of that name: `Rpc.isError` and a value's alike (3.1). */
+export function isFailedNamed(error: unknown, name: string): boolean {
+    return isFailed(error) && error.name === name
+}

package/src/shared/GLOBAL_GETS.ts

@@ -0,0 +1,13 @@
+/**
+ * Every `GET` declared over a `global` value, to the value it is serving for some args.
+ *
+ * 21.8, 18.5 — `at(key(args))` is `undefined` where no entry holds the args. The answer reads its
+ * `max-age` off it (`deadlineOf`) and its version (`versionOf`), and the mux feeds a follower from
+ * it. THE KEY IS ITS OWN STEP so each side takes it once: an answer once a request, a follower once
+ * as it subscribes — and the mux files its followers by it, so an entry answered reaches the
+ * followers of its own args and walks no other (18.8). An unkeyed value has one entry, under `''`.
+ */
+export const GLOBAL_GETS = new WeakMap<
+    object,
+    { key(args: unknown): string; at(key: string): unknown }
+>()