@markii/stdlib 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sadigaxund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @markii/stdlib
+
+The neutral, framework-agnostic definition of [Mark](https://github.com/sadigaxund/markii)'s standard directive contracts (callout, kbd, rating, and the rest of the built-in set): component kind, attribute schemas, and lookup by name. No React, zero dependencies — the seam every renderer implements against, not an implementation itself.
+
+See the [repository](https://github.com/sadigaxund/markii) for the format spec and the reference library as a whole.

package/dist/contracts.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The neutral, framework-agnostic definition of Mark's standard component
+ * *contracts* (DESIGN.md §13.3/§13.6): name + kind + attribute schema +
+ * semantics, as pure data — zero React, zero dependency on any other
+ * `@markii/*` package. A renderer (today `@markii/react`, tomorrow a
+ * hypothetical `@markii/gnome`) implements these same contracts against its
+ * own component framework; this module is the seam that makes "one format,
+ * many renderers" a checkable fact rather than a hope.
+ *
+ * A contract never describes markup, styling, or a component
+ * implementation — only what a directive named `name` means: how it is
+ * written (`kind`, matching the three directive forms from DESIGN.md §2/§13:
+ * `inline` -> `:name[...]`, `leaf` -> `::name{...}`, `container` ->
+ * `:::name{...} ... :::`) and what attributes it accepts.
+ */
+/**
+ * Which of the three directive forms a component is written as. Matches
+ * `remark-directive`'s three node types one-to-one:
+ * - `inline`    — text directive, `:name[...]`
+ * - `leaf`      — leaf directive, `::name{...}` (no body)
+ * - `container` — container directive, `:::name{...} ... :::` (block body)
+ */
+export type ComponentKind = 'inline' | 'leaf' | 'container';
+/**
+ * Schema for one directive attribute. All directive attributes arrive as
+ * raw strings (or `null` for a bare attribute) — DESIGN.md never gives
+ * directives a typed attribute grammar (Architecture rule 5: "no
+ * expressions, conditionals, or loops in attributes"). `type` is kept as an
+ * explicit field, rather than assumed, so the schema has somewhere to grow
+ * if a future spec revision adds a second attribute kind; today it is
+ * always `'string'`.
+ */
+export interface AttributeSchema {
+    type: 'string';
+    /** Whether the directive is invalid/incomplete without this attribute. Absent or `false` means optional. */
+    required?: boolean;
+    /** The exact set of allowed string values, if the attribute is a closed enum. Absent means any string is accepted. */
+    enum?: readonly string[];
+    /** Human-readable semantics: what the attribute controls, and its default/fallback behavior when absent or invalid. */
+    description: string;
+}
+/** One standard component's full contract: name, directive form, attribute schema, and semantics. */
+export interface ComponentContract {
+    name: string;
+    kind: ComponentKind;
+    attributes: Record<string, AttributeSchema>;
+    description: string;
+}
+/**
+ * The standard component set, seeded from the components that ship with
+ * `@markii/react` today (`packages/platforms/markii-react/src/components/
+ * {callout,kbd,rating,details,card,badge,figure,tabs,tab}.tsx`). Each
+ * contract was written by reading the real implementation — `kind` from how
+ * the component is registered in `defaultRegistry`, `attributes` from
+ * exactly the props the component reads (no invented attributes).
+ *
+ * Keyed by directive name, matching `defaultRegistry`'s shape so a renderer
+ * can iterate `Object.entries(STANDARD_COMPONENTS)` the same way it iterates
+ * its own registry.
+ */
+export declare const STANDARD_COMPONENTS: Record<string, ComponentContract>;
+/**
+ * Looks `name` up in `STANDARD_COMPONENTS`, returning `undefined` if it
+ * isn't a standard component. Guards against `name` being `'__proto__'`,
+ * `'constructor'`, `'toString'`, `'hasOwnProperty'`, etc. resolving through
+ * the prototype chain to an inherited `Object.prototype` member instead of
+ * correctly reporting "not found" — the same defense `@markii/react`'s
+ * registry (`createRegistry`/lookup in `render.tsx`) and `@markii/runtime`'s
+ * `ValueStore` already apply, via `Object.hasOwn` rather than `in`/bracket
+ * access alone.
+ */
+export declare function getContract(name: string): ComponentContract | undefined;

package/dist/contracts.js

@@ -0,0 +1,240 @@
+/**
+ * The neutral, framework-agnostic definition of Mark's standard component
+ * *contracts* (DESIGN.md §13.3/§13.6): name + kind + attribute schema +
+ * semantics, as pure data — zero React, zero dependency on any other
+ * `@markii/*` package. A renderer (today `@markii/react`, tomorrow a
+ * hypothetical `@markii/gnome`) implements these same contracts against its
+ * own component framework; this module is the seam that makes "one format,
+ * many renderers" a checkable fact rather than a hope.
+ *
+ * A contract never describes markup, styling, or a component
+ * implementation — only what a directive named `name` means: how it is
+ * written (`kind`, matching the three directive forms from DESIGN.md §2/§13:
+ * `inline` -> `:name[...]`, `leaf` -> `::name{...}`, `container` ->
+ * `:::name{...} ... :::`) and what attributes it accepts.
+ */
+/**
+ * The standard component set, seeded from the components that ship with
+ * `@markii/react` today (`packages/platforms/markii-react/src/components/
+ * {callout,kbd,rating,details,card,badge,figure,tabs,tab}.tsx`). Each
+ * contract was written by reading the real implementation — `kind` from how
+ * the component is registered in `defaultRegistry`, `attributes` from
+ * exactly the props the component reads (no invented attributes).
+ *
+ * Keyed by directive name, matching `defaultRegistry`'s shape so a renderer
+ * can iterate `Object.entries(STANDARD_COMPONENTS)` the same way it iterates
+ * its own registry.
+ */
+export const STANDARD_COMPONENTS = {
+    callout: {
+        name: 'callout',
+        kind: 'container',
+        attributes: {
+            type: {
+                type: 'string',
+                required: false,
+                enum: ['info', 'warning', 'danger'],
+                description: 'Visual/semantic variant, selecting the icon and color. Defaults to `info` when absent or not one of the allowed values.',
+            },
+            title: {
+                type: 'string',
+                required: false,
+                description: 'Optional header text shown above the body. Absent means no header line is rendered.',
+            },
+        },
+        description: "A colored box for an aside, warning, or danger note. Body is the directive's inner markdown, rendered as-is.",
+    },
+    kbd: {
+        name: 'kbd',
+        kind: 'inline',
+        attributes: {},
+        description: 'A styled keycap for an inline text directive, e.g. `:kbd[Ctrl+S]`. Takes no attributes; its inner content is the key label.',
+    },
+    rating: {
+        name: 'rating',
+        kind: 'leaf',
+        attributes: {
+            value: {
+                type: 'string',
+                required: false,
+                description: 'Number of filled stars, as a numeric string. Defaults to `0`; non-numeric input falls back to the default; the effective value is clamped to `[0, max]`.',
+            },
+            max: {
+                type: 'string',
+                required: false,
+                description: 'Total number of stars, as a numeric string. Defaults to `5`; non-numeric input falls back to the default; the effective value is clamped to `[1, 20]`.',
+            },
+        },
+        description: 'A leaf directive rendering a row of stars, e.g. `::rating{value=3 max=5}`. Has no body — both attributes are optional and degrade gracefully rather than throwing.',
+    },
+    details: {
+        name: 'details',
+        kind: 'container',
+        attributes: {
+            title: {
+                type: 'string',
+                required: false,
+                description: 'Summary text shown on the always-visible header. Defaults to `Details` when absent.',
+            },
+            open: {
+                type: 'string',
+                required: false,
+                description: 'Bare attribute (e.g. `{open}`). When present, the disclosure starts expanded; absent means it starts folded.',
+            },
+        },
+        description: 'A collapsible disclosure, e.g. `:::details{title="More"} ... :::`. Body is the directive\'s inner markdown, hidden until expanded.',
+    },
+    card: {
+        name: 'card',
+        kind: 'container',
+        attributes: {
+            title: {
+                type: 'string',
+                required: false,
+                description: 'Optional header text shown above the body. Absent means no title line is rendered.',
+            },
+        },
+        description: 'A titled panel, e.g. `:::card{title="Notes"} ... :::`. Body is the directive\'s inner markdown, rendered as-is.',
+    },
+    badge: {
+        name: 'badge',
+        kind: 'inline',
+        attributes: {
+            variant: {
+                type: 'string',
+                required: false,
+                enum: ['neutral', 'info', 'success', 'warning', 'danger'],
+                description: 'Visual/semantic variant, selecting the pill color. Defaults to `neutral` when absent or not one of the allowed values.',
+            },
+        },
+        description: 'A status pill for an inline text directive, e.g. `:badge[New]{variant=success}`. Its inner content is the label text.',
+    },
+    figure: {
+        name: 'figure',
+        kind: 'container',
+        attributes: {
+            src: {
+                type: 'string',
+                required: true,
+                description: 'Image URL. Required; an unsafe scheme (e.g. `javascript:`) is dropped and no image is rendered.',
+            },
+            alt: {
+                type: 'string',
+                required: false,
+                description: 'Image alt text. Defaults to the empty string when absent.',
+            },
+        },
+        description: 'An image with a rich caption, e.g. `:::figure{src="cat.png" alt="A cat"} A cat, napping. ::: `. Body is the directive\'s inner markdown, rendered as the caption.',
+    },
+    tabs: {
+        name: 'tabs',
+        kind: 'container',
+        attributes: {},
+        description: 'A tabbed panel switcher, e.g. `::::tabs :::tab{label="A"} ... ::: :::tab{label="B"} ... ::: ::::`. Takes no attributes of its own; its body is a sequence of `tab` containers, one per panel, and it shows only the active one. The enclosing fence must use MORE colons than its `tab` children (directive container nesting rule), hence `::::tabs` wrapping `:::tab`.',
+    },
+    tab: {
+        name: 'tab',
+        kind: 'container',
+        attributes: {
+            label: {
+                type: 'string',
+                required: false,
+                description: 'Tab button text, read by the enclosing `tabs` component. Defaults to `Tab` when absent.',
+            },
+        },
+        description: 'One panel of a `tabs` component, e.g. `:::tab{label="A"} ... :::`. Body is the directive\'s inner markdown, shown only while this tab is active. Rendered standalone (outside a `tabs` parent) it simply shows its panel.',
+    },
+    stat: {
+        name: 'stat',
+        kind: 'leaf',
+        attributes: {
+            value: {
+                type: 'string',
+                required: false,
+                description: "The headline value, shown large. Overridden by a bound `data=` value/object's own `value` field when both are present. Absent value (from either source) renders `—`.",
+            },
+            label: {
+                type: 'string',
+                required: false,
+                description: "Caption shown under the value. Overridden by a bound `data=` object's `label` field when both are present. Absent means no caption line is rendered.",
+            },
+            delta: {
+                type: 'string',
+                required: false,
+                description: "Optional secondary text (e.g. a change amount) shown next to the value. Overridden by a bound `data=` object's `delta` field when both are present.",
+            },
+            trend: {
+                type: 'string',
+                required: false,
+                enum: ['up', 'down', 'flat'],
+                description: "Colors/annotates `delta` as an increase, decrease, or no change. Overridden by a bound `data=` object's `trend` field when both are present; absent/invalid means no trend styling.",
+            },
+        },
+        description: 'A leaf directive rendering a big value plus label, e.g. `::stat{value=42 label="stars" trend=up}`. Data binding (§8): `data=name` resolves against the value store — a number/string value supplies `value` directly; an object may supply `value`/`label`/`delta`/`trend` fields (explicit attributes on the directive always take precedence over the bound object\'s fields). Degrades to `—` when both the attribute and the bound value are absent — never throws.',
+    },
+    progress: {
+        name: 'progress',
+        kind: 'leaf',
+        attributes: {
+            value: {
+                type: 'string',
+                required: false,
+                description: "Current amount, as a numeric string. Overridden by a bound `data=` number, or a bound object's `value` field, when present. Non-numeric/NaN/Infinity input is treated as `0`; the effective value is clamped to `[0, max]`.",
+            },
+            max: {
+                type: 'string',
+                required: false,
+                description: "The amount `value` is measured against, as a numeric string. Defaults to `1`. Overridden by a bound object's `max` field when present. Non-numeric/NaN/Infinity/non-positive input falls back to the default.",
+            },
+            label: {
+                type: 'string',
+                required: false,
+                description: 'Optional caption shown above/alongside the bar. Absent means no caption line is rendered.',
+            },
+        },
+        description: 'A leaf directive rendering a meter bar, e.g. `::progress{value=3 max=5 label="tasks"}`. Data binding (§8): `data=name` resolves against the value store — a bare number supplies `value` directly; an object may supply `value`/`max` fields (explicit attributes take precedence). Parses defensively and clamps rather than throwing; missing/invalid input renders an empty (0%) bar.',
+    },
+    chart: {
+        name: 'chart',
+        kind: 'leaf',
+        attributes: {
+            kind: {
+                type: 'string',
+                required: false,
+                enum: ['line', 'bar'],
+                description: 'Chart form: a connected line through the points, or a bar per point. Defaults to `line` when absent or not one of the allowed values.',
+            },
+            values: {
+                type: 'string',
+                required: false,
+                description: 'Comma-separated numbers for static authoring, e.g. `values="1,3,2,5"`. Ignored in favor of a bound `data=` array when both are present. Non-numeric entries are dropped.',
+            },
+            height: {
+                type: 'string',
+                required: false,
+                description: 'SVG viewport height in pixels, as a numeric string. Defaults to a sane built-in size; non-numeric/non-positive input falls back to the default.',
+            },
+            width: {
+                type: 'string',
+                required: false,
+                description: 'SVG viewport width in pixels, as a numeric string. Defaults to a sane built-in size; non-numeric/non-positive input falls back to the default.',
+            },
+        },
+        description: 'A leaf directive rendering a minimal hand-rolled inline SVG chart, e.g. `::chart{kind=line values="1,3,2,5"}`. Data binding (§8): `data=name` resolves against the value store — expects an array of numbers (typically a Lua script returning a table), or an array of `{value}` objects. Non-finite/non-numeric entries are filtered out and the point count is capped; an empty or all-invalid series renders a small neutral empty state rather than a broken chart. Never throws, and never places unescaped text into the emitted SVG markup.',
+    },
+};
+/**
+ * Looks `name` up in `STANDARD_COMPONENTS`, returning `undefined` if it
+ * isn't a standard component. Guards against `name` being `'__proto__'`,
+ * `'constructor'`, `'toString'`, `'hasOwnProperty'`, etc. resolving through
+ * the prototype chain to an inherited `Object.prototype` member instead of
+ * correctly reporting "not found" — the same defense `@markii/react`'s
+ * registry (`createRegistry`/lookup in `render.tsx`) and `@markii/runtime`'s
+ * `ValueStore` already apply, via `Object.hasOwn` rather than `in`/bracket
+ * access alone.
+ */
+export function getContract(name) {
+    return Object.hasOwn(STANDARD_COMPONENTS, name)
+        ? STANDARD_COMPONENTS[name]
+        : undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { getContract, STANDARD_COMPONENTS, type AttributeSchema, type ComponentContract, type ComponentKind, } from './contracts.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { getContract, STANDARD_COMPONENTS, } from './contracts.js';

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@markii/stdlib",
+  "version": "0.1.0",
+  "description": "Neutral, framework-agnostic standard component contracts for Mark (.mk.md) — the kind/attribute-schema seam every renderer (e.g. @markii/react) implements against. No React, zero dependencies.",
+  "keywords": [
+    "markdown",
+    "mark",
+    "mk.md",
+    "stdlib",
+    "contracts",
+    "directive"
+  ],
+  "license": "MIT",
+  "author": "sadigaxund",
+  "homepage": "https://github.com/sadigaxund/markii#readme",
+  "bugs": "https://github.com/sadigaxund/markii/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sadigaxund/markii.git",
+    "directory": "packages/markii-stdlib"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsc --noEmit -p tsconfig.json",
+    "build:dist": "rm -rf dist && tsc -p tsconfig.build.json",
+    "lint": "eslint ."
+  }
+}