@mapled/vanilla 0.0.1 → 0.1.0

package/dist/sinks.js

@@ -0,0 +1,142 @@
+/** The sinks: the only places where a value from Mapled touches the
+    page. Each one is named by the page's author (an attribute of the
+    page), never by the value; each holds the value to its own rule of
+    DOM_SECURITY.md and, when the value doesn't fit, leaves the page as it
+    was and says why. */
+import { assetUrl } from "@mapled/client";
+import { renderMarkdown } from "./markdown.js";
+import { asText } from "./paths.js";
+import { isAssetId, safeUrl } from "./url.js";
+const HTML = "http://www.w3.org/1999/xhtml";
+/** Never written into, by local name and in any namespace (rule 2): their
+    text or attributes are code, policy or the base of every address. */
+const REFUSED = new Set(["script", "style", "iframe", "frame", "frameset", "object", "embed", "applet", "base", "link", "meta", "template", "noscript"]);
+/** The attributes content may fill (rule 3): the name that is written,
+    the elements it belongs to (null — any HTML element), what the value
+    is held to. */
+export const ATTRIBUTES = {
+    href: { on: ["a", "area"], holds: "link" },
+    src: { on: ["img", "video", "audio", "source"], holds: "media" },
+    alt: { on: ["img", "area"], holds: "text" },
+    title: { on: null, holds: "text" },
+    "aria-label": { on: null, holds: "text" },
+    placeholder: { on: ["input", "textarea"], holds: "text" },
+    datetime: { on: ["time", "del", "ins"], holds: "text" },
+};
+const isHtml = (el) => el.namespaceURI === HTML;
+/** Whether the element may be written into at all. */
+export const writable = (el) => !REFUSED.has(el.localName.toLowerCase());
+/** The element's text. Markup in the value stays text: this is the one
+    assignment content reaches, and it parses nothing. */
+export function writeText(el, value) {
+    if (!writable(el))
+        return "refused-element";
+    const text = asText(value);
+    if (text === null)
+        return "type";
+    el.textContent = text;
+    return null;
+}
+/** The element's content from Markdown. */
+export function writeMarkdown(el, value, ctx) {
+    if (!writable(el) || !isHtml(el))
+        return "refused-element";
+    if (typeof value !== "string")
+        return "type";
+    el.replaceChildren(renderMarkdown(value, el.ownerDocument, ctx.base));
+    return null;
+}
+/** An image or a file: an asset id becomes its URL under the API's
+    /files (resized when the page asks for a width), anything else is an
+    address held to the media policy. */
+function mediaUrl(value, ctx, width) {
+    if (typeof value !== "string")
+        return null;
+    if (isAssetId(value))
+        return assetUrl(value, { ...(ctx.apiUrl ? { apiUrl: ctx.apiUrl } : {}), ...(width ? { width } : {}) });
+    return safeUrl(value, ctx.base, "media");
+}
+/** `<img data-mapled-bind>`: the picture. */
+export function writeImage(el, value, ctx, width) {
+    if (!isHtml(el) || el.localName !== "img")
+        return "refused-element";
+    if (typeof value !== "string")
+        return "type";
+    const url = mediaUrl(value, ctx, width);
+    if (url === null)
+        return "unsafe-url";
+    // the author's srcset would keep showing the fallback picture
+    el.removeAttribute("srcset");
+    el.setAttribute("src", url);
+    return null;
+}
+/** One attribute of the table. `name` is the page's spelling: it is
+    looked up, never written as it came. */
+export function writeAttribute(el, name, value, ctx, width) {
+    const key = name.toLowerCase();
+    const rule = Object.prototype.hasOwnProperty.call(ATTRIBUTES, key) ? ATTRIBUTES[key] : undefined;
+    if (!rule)
+        return "unsupported";
+    if (!writable(el) || !isHtml(el))
+        return "refused-element";
+    if (rule.on !== null && !rule.on.includes(el.localName))
+        return "unsupported";
+    if (rule.holds === "text") {
+        const text = asText(value);
+        if (text === null)
+            return "type";
+        el.setAttribute(key, text);
+        return null;
+    }
+    if (typeof value !== "string")
+        return "type";
+    const url = rule.holds === "media" ? mediaUrl(value, ctx, el.localName === "img" ? width : undefined) : safeUrl(value, ctx.base, "link");
+    if (url === null)
+        return "unsafe-url";
+    el.setAttribute(key, url);
+    return null;
+}
+/** A link built from the page's own template (url.ts › fillTemplate). */
+export function writeLink(el, url) {
+    if (!isHtml(el) || (el.localName !== "a" && el.localName !== "area"))
+        return "unsupported";
+    el.setAttribute("href", url);
+    return null;
+}
+/** Shown or not — the `hidden` attribute and nothing else. */
+export function setVisible(el, visible) {
+    if (visible)
+        el.removeAttribute("hidden");
+    else
+        el.setAttribute("hidden", "");
+}
+export const FORMATS = ["text", "markdown", "date", "datetime", "number"];
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+/** What Mapled's date and date-time fields hold. `Date` alone would read a year out of almost any text. */
+const ISO = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+/** A date or a number in the words of the page's language. Null when
+    the value isn't one. */
+export function formatted(value, format, lang) {
+    const locale = lang && /^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(lang) ? lang : undefined;
+    try {
+        if (format === "number") {
+            const n = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
+            return Number.isFinite(n) ? new Intl.NumberFormat(locale).format(n) : null;
+        }
+        if (typeof value !== "string" || !ISO.test(value))
+            return null;
+        const at = new Date(value);
+        if (Number.isNaN(at.getTime()))
+            return null;
+        // a date without a time is a calendar day, the same day everywhere
+        const day = DATE_ONLY.test(value);
+        return new Intl.DateTimeFormat(locale, {
+            dateStyle: "long",
+            ...(format === "datetime" && !day ? { timeStyle: "short" } : {}),
+            ...(day ? { timeZone: "UTC" } : {}),
+        }).format(at);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/url.d.ts

@@ -0,0 +1,30 @@
+/** The one policy every address from content passes before it reaches
+    the page (DOM_SECURITY.md, rule 4). The browser's own URL parser does
+    the reading — the parser navigation uses — so a scheme hidden behind
+    tabs, newlines, control characters or mixed case is judged the way
+    the browser would read it, and what is written is the parser's
+    `href`, never the text that came in. */
+/** `link` — where a person goes (`href`); `media` — what the page loads
+    (`src`, images of rich text). */
+export type AddressKind = "link" | "media";
+/** The address as the browser reads it against `base`, or null when it
+    may not be written: a scheme outside the list, credentials in it
+    (`https://bank.example@evil.example/` reads as the bank), not an
+    address at all. */
+export declare function safeUrl(value: string, base: string, kind: AddressKind): string | null;
+/** An image or file value is an asset id: Mapled serves it under /files. */
+export declare const isAssetId: (value: unknown) => value is string;
+export type Filled = {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    reason: "bad-path" | "empty" | "unsafe-url";
+    path: string;
+};
+/** A link template — `/post.html?slug={slug}`: the text is the page
+    author's, every `{path}` is a value of the record in scope, and each
+    value is percent-encoded before it goes in — it can fill a segment or
+    a parameter, never add a scheme, a host, a slash or a second
+    parameter. The result still passes `safeUrl`. */
+export declare function fillTemplate(template: string, base: string, lookup: (segments: string[]) => unknown): Filled;

package/dist/url.js

@@ -0,0 +1,58 @@
+/** The one policy every address from content passes before it reaches
+    the page (DOM_SECURITY.md, rule 4). The browser's own URL parser does
+    the reading — the parser navigation uses — so a scheme hidden behind
+    tabs, newlines, control characters or mixed case is judged the way
+    the browser would read it, and what is written is the parser's
+    `href`, never the text that came in. */
+import { parsePath } from "./paths.js";
+const LINK = new Set(["http:", "https:", "mailto:", "tel:"]);
+const MEDIA = new Set(["http:", "https:"]);
+const MAX_LENGTH = 2048;
+/** The address as the browser reads it against `base`, or null when it
+    may not be written: a scheme outside the list, credentials in it
+    (`https://bank.example@evil.example/` reads as the bank), not an
+    address at all. */
+export function safeUrl(value, base, kind) {
+    if (typeof value !== "string" || value.length > MAX_LENGTH)
+        return null;
+    let url;
+    try {
+        url = new URL(value, base);
+    }
+    catch {
+        return null;
+    }
+    if (!(kind === "link" ? LINK : MEDIA).has(url.protocol))
+        return null;
+    if (url.username !== "" || url.password !== "")
+        return null;
+    return url.href;
+}
+const ASSET_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** An image or file value is an asset id: Mapled serves it under /files. */
+export const isAssetId = (value) => typeof value === "string" && ASSET_ID.test(value);
+/** A link template — `/post.html?slug={slug}`: the text is the page
+    author's, every `{path}` is a value of the record in scope, and each
+    value is percent-encoded before it goes in — it can fill a segment or
+    a parameter, never add a scheme, a host, a slash or a second
+    parameter. The result still passes `safeUrl`. */
+export function fillTemplate(template, base, lookup) {
+    const failures = [];
+    const text = template.replace(/\{([^{}]*)\}/g, (_, name) => {
+        const segments = parsePath(name);
+        if (!segments) {
+            failures.push({ ok: false, reason: "bad-path", path: name.trim().slice(0, 80) });
+            return "";
+        }
+        const value = lookup(segments);
+        if ((typeof value !== "string" && typeof value !== "number") || value === "") {
+            failures.push({ ok: false, reason: "empty", path: segments.join(".") });
+            return "";
+        }
+        return encodeURIComponent(String(value));
+    });
+    if (failures[0])
+        return failures[0];
+    const url = safeUrl(text, base, "link");
+    return url === null ? { ok: false, reason: "unsafe-url", path: template.slice(0, 80) } : { ok: true, url };
+}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+/** The package's version — what the banner of the single file and
+    `Mapled.version` say. Kept equal to package.json by version.test.ts. */
+export declare const VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1,3 @@
+/** The package's version — what the banner of the single file and
+    `Mapled.version` say. Kept equal to package.json by version.test.ts. */
+export const VERSION = "0.1.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mapled/vanilla",
-  "version": "0.0.1",
-  "description": "The browser runtime of Mapled, the hosted headless CMS for sites built with AI — published content in a plain HTML site, no framework and no build step. 0.0.1 holds no code yet; 0.1.0 is the first release.",
+  "version": "0.1.0",
+  "description": "The browser runtime of Mapled, the hosted headless CMS for sites built with AI — published content in a plain HTML site: one script tag and data-mapled attributes, no framework and no build step.",
   "license": "MIT",
   "homepage": "https://mapled.io",
   "keywords": [
@@ -9,9 +9,44 @@
     "cms",
     "headless-cms",
     "vanilla-js",
-    "html"
+    "html",
+    "static-site",
+    "script-tag"
   ],
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": [
+    "./dist/mapled.js"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "unpkg": "./dist/mapled.js",
+  "jsdelivr": "./dist/mapled.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./dist/mapled.js": "./dist/mapled.js"
+  },
   "files": [
-    "README.md"
-  ]
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node build.mjs",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@mapled/client": "^0.1.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2",
+    "jsdom": "^26.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.11"
+  }
 }