@markii/stdlib 0.2.0 → 0.3.1

package/dist/contracts.d.ts

@@ -1,6 +1,6 @@
 /**
  * The neutral, framework-agnostic definition of Mark's standard component
- * *contracts* (DESIGN.md §13.3/§13.6): name + kind + attribute schema +
+ * *contracts* (docs/integration.md/§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
@@ -9,7 +9,7 @@
  *
  * 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:
+ * written (`kind`, matching the three directive forms from docs/format.md/§13:
  * `inline` -> `:name[...]`, `leaf` -> `::name{...}`, `container` ->
  * `:::name{...} ... :::`) and what attributes it accepts.
  */
@@ -23,7 +23,7 @@
 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
+ * raw strings (or `null` for a bare attribute) — docs/spec.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

package/dist/contracts.js

@@ -1,6 +1,6 @@
 /**
  * The neutral, framework-agnostic definition of Mark's standard component
- * *contracts* (DESIGN.md §13.3/§13.6): name + kind + attribute schema +
+ * *contracts* (docs/integration.md/§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
@@ -9,10 +9,38 @@
  *
  * 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:
+ * written (`kind`, matching the three directive forms from docs/format.md/§13:
  * `inline` -> `:name[...]`, `leaf` -> `::name{...}`, `container` ->
  * `:::name{...} ... :::`) and what attributes it accepts.
  */
+/**
+ * Builds one of docs/format.md's five layout-wrapper container contracts —
+ * `center`/`right`/`wide`/`narrow`/`full` — which are otherwise identical in
+ * shape (`kind: 'container'`, no attributes) and differ only in `name` and
+ * the preset-specific half of `description`. A tiny helper rather than five
+ * hand-copied literals, since a typo in one copy's `kind`/`attributes` would
+ * otherwise be easy to miss across five near-duplicate blocks.
+ *
+ * `whatItDoes` is the preset-specific clause (e.g. "Centers narrower-than-
+ * column plain markdown..."); the shared clause about why these exist (the
+ * attribute mechanism cannot reach plain markdown) and about composing with
+ * a nested wrapper is appended identically for all five.
+ */
+function layoutWrapperContract(name, whatItDoes) {
+    return {
+        name,
+        kind: 'container',
+        attributes: {},
+        description: `${whatItDoes} Takes no attributes — docs/format.md gives these five ` +
+            'wrapper names a closed, attribute-free form; unlike a `width`/`align` ' +
+            'attribute on a directive, a wrapper also reaches plain markdown a ' +
+            'directive attribute mechanism structurally cannot (a GFM table or a ' +
+            'bare image has no `{...}` to write `width=`/`align=` into). Nesting a ' +
+            'width wrapper (`wide`/`narrow`/`full`) inside an alignment wrapper ' +
+            '(`center`/`right`) composes, e.g. `::::center :::narrow ... ::: ::::` ' +
+            '(the outer fence needs more colons than the inner one).',
+    };
+}
 /**
  * The standard component set, seeded from the components that ship with
  * `@markii/react` today (`packages/platforms/markii-react/src/components/
@@ -210,7 +238,7 @@ export const STANDARD_COMPONENTS = {
                 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.',
             },
         },
-        description: 'A leaf directive rendering a minimal hand-rolled inline SVG chart, e.g. `::chart{kind=line values="1,3,2,5"}`. Sizes to its container — use DESIGN.md §4\'s `width`/`align` layout presets to control its footprint, not a pixel attribute. 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.',
+        description: 'A leaf directive rendering a minimal hand-rolled inline SVG chart, e.g. `::chart{kind=line values="1,3,2,5"}`. Sizes to its container — use docs/format.md\'s `width`/`align` layout presets to control its footprint, not a pixel attribute. 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.',
     },
     row: {
         name: 'row',
@@ -223,8 +251,20 @@ export const STANDARD_COMPONENTS = {
                 description: 'Fixed column count for the row. Defaults to auto-fit (a responsive number of equal-width columns) when absent or not one of the allowed values — an invalid `cols` is never an error.',
             },
         },
-        description: "DESIGN.md §4's one layout container, e.g. `:::row{cols=3} ... :::`. Its block children become equal-width cells that wrap responsively and stack on narrow viewports — and simply stack in a plain markdown viewer. No spans, no per-cell sizing, no other knobs.",
+        description: "docs/format.md's one layout container, e.g. `:::row{cols=3} ... :::`. Its block children become equal-width cells that wrap responsively and stack on narrow viewports — and simply stack in a plain markdown viewer. No spans, no per-cell sizing, no other knobs.",
+    },
+    cell: {
+        name: 'cell',
+        kind: 'container',
+        attributes: {},
+        description: "A transparent grouping container, e.g. `:::cell ... :::`. Its only job is making several blocks count as ONE cell of a `row`: a row's cells are its direct block children, so two blocks are two cells unless a `cell` groups them — and two adjacent task lists, which markdown merges into a single list, can only become two cells by putting one `cell` around each. Takes no attributes and adds no look of its own; outside a `row` it is inert. The enclosing `row` fence must use MORE colons than its `cell` children (directive container nesting rule), hence `::::row` wrapping `:::cell`.",
     },
+    center: layoutWrapperContract('center', 'Centers narrower-than-column plain markdown (a table, an image) within its scope and sets text alignment for everything in scope, e.g. `:::center ... :::`.'),
+    left: layoutWrapperContract('left', 'Left-aligns plain markdown within its scope and sets text alignment for everything in scope, e.g. `:::left ... :::`. Mostly matches the ambient default; it exists to override an alignment inherited from an enclosing scope, such as opting one cell back out of `:::row{align=center}`.'),
+    right: layoutWrapperContract('right', 'Right-aligns narrower-than-column plain markdown (a table, an image) within its scope and sets text alignment for everything in scope, e.g. `:::right ... :::`.'),
+    wide: layoutWrapperContract('wide', "Sizes its scope's content to docs/format.md's wide-column width preset, e.g. `:::wide ... :::`."),
+    narrow: layoutWrapperContract('narrow', "Sizes its scope's content to docs/format.md's narrow-column width preset, e.g. `:::narrow ... :::`."),
+    full: layoutWrapperContract('full', "Sizes its scope's content to the full available document-column width, e.g. `:::full ... :::`."),
 };
 /**
  * Looks `name` up in `STANDARD_COMPONENTS`, returning `undefined` if it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/stdlib",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",