@mapled/vanilla 0.0.1 → 0.1.0

package/dist/runtime.d.ts

@@ -0,0 +1,84 @@
+/** The runtime of Mapled attributes (§19.2): finds what a page declared
+    with `data-mapled-*`, reads the release that is live, fills the page,
+    and says what it couldn't fill. The page's own HTML is the fallback —
+    nothing is touched before its replacement is in hand, and every run
+    starts again from what the author wrote.
+
+    What a page may declare:
+
+      data-mapled-bind="home.headline"        the element's content — text;
+                                              on <img>, the picture
+      data-mapled-format="markdown"           …as rich text; or "date",
+                                              "datetime", "number"
+      data-mapled-bind-href="home.cta-link"   an attribute: href, src, alt,
+                                              title, aria-label,
+                                              placeholder, datetime
+      data-mapled-link="/post.html?slug={slug}"  an address from a template
+      data-mapled-show / data-mapled-hide     shown while there is a value
+      data-mapled-list="posts"                a <template> inside, once per
+                                              record: data-mapled-sort,
+                                              -limit, -filter, -expand
+      data-mapled-each="features"             the same for the items of a
+                                              repeatable group
+      data-mapled-record="posts"              one record for what is inside:
+                                              data-mapled-slug, or
+                                              data-mapled-slug-param="slug"
+      <form data-mapled-form="contact">       posted to Mapled's form
+
+    Paths start at a single from the document (`home.headline`) and at the
+    record inside a list, an each or a record (`title`, `author.name`). */
+import { type MapledClient } from "@mapled/client";
+/** Why a place wasn't filled. `missing` — no such single, record or
+    collection in the release; `empty` — the record is there, a value at
+    this path isn't; `failed` — the read didn't come back; `bad-path` —
+    the page's attribute isn't a path, a key or an option Mapled reads;
+    the rest are the sinks' refusals. */
+export declare const ISSUE_REASONS: readonly ["missing", "empty", "failed", "bad-path", "unsafe-url", "type", "refused-element", "unsupported"];
+export type IssueReason = (typeof ISSUE_REASONS)[number];
+/** A place the runtime couldn't fill: the page's own path, why, and the
+    element as the page names it. Never a value. */
+export type Issue = {
+    path: string;
+    reason: IssueReason;
+    on: string;
+};
+export type Report = {
+    /** ready — filled from Mapled; unpublished — nothing is published yet;
+        fallback — Mapled couldn't be reached, the page is as written */
+    state: "ready" | "unpublished" | "fallback";
+    release: number | null;
+    preview: boolean;
+    /** places filled */
+    bound: number;
+    issues: Issue[];
+};
+export type MountOptions = {
+    /** The project's delivery key — the one key that is safe in a page. */
+    key: string;
+    apiUrl?: string;
+    /** Mapled's app — where an expired preview link sends the person. */
+    appUrl?: string;
+    /** Where to look for attributes (default: the whole document). */
+    root?: Element;
+    /** Fill the page again when a publish lands while it is open: true
+        (a check a minute), or the seconds between checks — at least 15.
+        Every check is a request of the key's budget. */
+    live?: boolean | number;
+    fetch?: typeof fetch;
+};
+export type MapledPage = {
+    /** The first fill: resolves with its report, never rejects. */
+    ready: Promise<Report>;
+    /** The last report, once there is one. */
+    readonly report: Report | null;
+    /** Read and fill again — after the page changed its own DOM. */
+    refresh: () => Promise<Report>;
+    /** Leave preview and show what is published. */
+    endPreview: () => Promise<Report>;
+    /** Stop live updates. */
+    stop: () => void;
+    client: MapledClient;
+};
+/** Every attribute the runtime reads or writes, besides `bind-…`. */
+export declare const NAMES: Set<string>;
+export declare function mount(options: MountOptions): MapledPage;