@markii/stdlib 0.8.1 → 0.10.0

package/dist/contracts.d.ts

@@ -1,18 +1,3 @@
-/**
- * The neutral, framework-agnostic definition of Mark's standard component
- * *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
- * 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 docs/format.md/§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:
@@ -49,7 +34,7 @@ export interface ComponentContract {
 /**
  * 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
+ * {callout,kbd,rating,divider,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).

package/dist/contracts.js

@@ -13,38 +13,54 @@
  * `inline` -> `:name[...]`, `leaf` -> `::name{...}`, `container` ->
  * `:::name{...} ... :::`) and what attributes it accepts.
  */
+import { LAYOUT_ATTRIBUTES, layoutWrapperAxis, otherLayoutAxis, } from './layout.js';
+import { TEXT_ALIGN_ATTRIBUTE } from './text-align.js';
 /**
- * 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.
+ * Builds one of docs/format.md's layout-wrapper container contracts,
+ * `center`/`left`/`right`/`wide`/`narrow`/`full`/`fit`, which are otherwise
+ * identical in shape and differ only in `name`, the preset-specific half of
+ * `description`, and which of the two layout axes they leave open. A tiny
+ * helper rather than one hand-copied literal per preset, since a typo in
+ * one copy's `kind`/`attributes` would otherwise be easy to miss across a
+ * run of near-duplicate blocks.
+ *
+ * A wrapper decides ONE axis by its name and accepts the OTHER as an
+ * attribute (docs/spec.md §3), so an alignment wrapper declares `width` and
+ * a width wrapper declares `align`, taken from `./layout.ts`'s one
+ * definition of those two schemas. An attribute for the wrapper's own axis
+ * is deliberately absent from the contract: the name already decided it,
+ * and writing it is ignored rather than an error.
  *
  * `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.
+ * attribute mechanism cannot reach plain markdown) is appended identically
+ * for all of them.
  */
 function layoutWrapperContract(name, whatItDoes) {
+    const ownAxis = layoutWrapperAxis(name);
+    if (ownAxis === undefined) {
+        throw new Error(`"${name}" is not a layout-wrapper name`);
+    }
+    const openAxis = otherLayoutAxis(ownAxis);
     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).',
+        attributes: { [openAxis]: LAYOUT_ATTRIBUTES[openAxis] },
+        description: `${whatItDoes} A wrapper reaches plain markdown that a directive ` +
+            'attribute structurally cannot: a GFM table or a bare image has no ' +
+            '`{...}` to write `width=`/`align=` into. It sets one of the two ' +
+            `layout axes by its name and takes the other, \`${openAxis}\`, as an ` +
+            `attribute, so \`:::${name}{${openAxis}=...}\` applies both to the ` +
+            `one scope. An \`${ownAxis}\` attribute is ignored here, since the ` +
+            'name already decided that axis. Nesting two wrappers composes the ' +
+            'same way, 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/
- * {callout,kbd,rating,details,card,badge,figure,tabs,tab}.tsx`). Each
+ * {callout,kbd,rating,divider,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).
@@ -69,6 +85,7 @@ export const STANDARD_COMPONENTS = {
                 required: false,
                 description: 'Optional header text shown above the body. Absent means no header line is rendered.',
             },
+            text: TEXT_ALIGN_ATTRIBUTE,
         },
         description: "A colored box for an aside, warning, or danger note. Body is the directive's inner markdown, rendered as-is.",
     },
@@ -95,6 +112,30 @@ export const STANDARD_COMPONENTS = {
         },
         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.',
     },
+    divider: {
+        name: 'divider',
+        kind: 'leaf',
+        attributes: {
+            label: {
+                type: 'string',
+                required: false,
+                description: 'Optional short text shown in the break, centered unless `label-align` says otherwise. Absent or empty means an unlabeled divider.',
+            },
+            variant: {
+                type: 'string',
+                required: false,
+                enum: ['line', 'dots', 'ornament'],
+                description: 'Which break to draw: a solid hairline, a dotted hairline, or a centered ornament with no hairline. Defaults to `line` when absent or not one of the allowed values.',
+            },
+            'label-align': {
+                type: 'string',
+                required: false,
+                enum: ['left', 'center', 'right'],
+                description: 'Where the label sits along the rule. Defaults to `center` when absent or not one of the allowed values.',
+            },
+        },
+        description: 'A leaf directive drawing a section break, e.g. `::divider{label="Part 2" variant="dots"}`. Has no body, and every attribute is optional. A plain `---` thematic break keeps its own CommonMark meaning; this directive is for a break that carries a label or a chosen look.',
+    },
     details: {
         name: 'details',
         kind: 'container',
@@ -121,6 +162,7 @@ export const STANDARD_COMPONENTS = {
                 required: false,
                 description: 'Optional header text shown above the body. Absent means no title line is rendered.',
             },
+            text: TEXT_ALIGN_ATTRIBUTE,
         },
         description: 'A titled panel, e.g. `:::card{title="Notes"} ... :::`. Body is the directive\'s inner markdown, rendered as-is.',
     },
@@ -250,21 +292,23 @@ export const STANDARD_COMPONENTS = {
                 enum: ['2', '3', '4'],
                 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.',
             },
+            text: TEXT_ALIGN_ATTRIBUTE,
         },
-        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.",
+        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. A row always fills the column, so the reserved `align` has nothing to place on it; `text` is what aligns the content inside its cells.",
     },
     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`.",
+        attributes: { text: TEXT_ALIGN_ATTRIBUTE },
+        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. Its only presentation of its own is `text`, which overrides the enclosing row's; 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}`.'),
+    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{text=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 ... :::`."),
+    fit: layoutWrapperContract('fit', 'Shrinks its scope to the width of its own content rather than filling the column, e.g. `:::fit ... :::`. Pair it with an alignment to place the result, as in `:::fit{align=right} ... :::`.'),
 };
 /**
  * Looks `name` up in `STANDARD_COMPONENTS`, returning `undefined` if it

package/dist/index.d.ts

@@ -1 +1,3 @@
 export { getContract, STANDARD_COMPONENTS, type AttributeSchema, type ComponentContract, type ComponentKind, } from './contracts.js';
+export { ALIGN_PRESETS, LAYOUT_ATTRIBUTE_KEYS, LAYOUT_ATTRIBUTES, WIDTH_PRESETS, layoutWrapperAxis, otherLayoutAxis, type LayoutAxis, } from './layout.js';
+export { TEXT_ALIGN_ATTRIBUTE, TEXT_ALIGN_COMPONENTS, TEXT_ALIGN_PRESETS, type TextAlignPreset, } from './text-align.js';

package/dist/index.js

@@ -1 +1,3 @@
 export { getContract, STANDARD_COMPONENTS, } from './contracts.js';
+export { ALIGN_PRESETS, LAYOUT_ATTRIBUTE_KEYS, LAYOUT_ATTRIBUTES, WIDTH_PRESETS, layoutWrapperAxis, otherLayoutAxis, } from './layout.js';
+export { TEXT_ALIGN_ATTRIBUTE, TEXT_ALIGN_COMPONENTS, TEXT_ALIGN_PRESETS, } from './text-align.js';

package/dist/layout.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The neutral definition of docs/format.md's layout system: the two
+ * reserved attributes every block directive can carry (`width`, `align`)
+ * and their closed preset vocabularies. Zero dependency, matching this
+ * package's own posture — every renderer (`@markii/react`, `@markii/html`,
+ * and any future one) builds its class-mapping logic off these same value
+ * lists instead of hand-copying the literals, which is how the two
+ * existing renderers drifted into two near-identical copies in the first
+ * place.
+ *
+ * This module carries VALUES only (the attribute names, the preset lists,
+ * and the two attributes expressed as `AttributeSchema`s for a tool that
+ * documents or completes attributes). It says nothing about markup,
+ * classes, or rendering; see each renderer's own `layout.ts` for that.
+ */
+import type { AttributeSchema } from './contracts.js';
+/** The two attribute names docs/format.md reserves on every block directive. */
+export declare const LAYOUT_ATTRIBUTE_KEYS: readonly ["width", "align"];
+/**
+ * One of the two layout axes. `width` sizes a block's box; `align` places
+ * that box within the column. They are independent: every block has a
+ * value on both, and setting one never implies the other.
+ */
+export type LayoutAxis = (typeof LAYOUT_ATTRIBUTE_KEYS)[number];
+/** The axis a wrapper of the other axis takes as an attribute (docs/spec.md §3). */
+export declare function otherLayoutAxis(axis: LayoutAxis): LayoutAxis;
+/**
+ * The closed `width=` preset vocabulary (docs/format.md), listed narrowest
+ * to widest so the list reads as the scale it is: `fit` hugs the block's
+ * own content, `normal` is the default column width, and `full` fills the
+ * column. Order is user-visible: a completion popup offers the values in
+ * this order.
+ */
+export declare const WIDTH_PRESETS: readonly ["fit", "narrow", "normal", "wide", "full"];
+/** The closed `align=` preset vocabulary (docs/format.md), in the order the docs list them. */
+export declare const ALIGN_PRESETS: readonly ["left", "center", "right"];
+/**
+ * The layout axis the wrapper container named `name` sets by its NAME
+ * (docs/format.md, "The same presets as wrappers"), or `undefined` when
+ * `name` is not one of the seven wrapper names.
+ *
+ * This is the one place the seven names are classified. A wrapper owns its
+ * own axis and takes the OTHER axis as an attribute, so both renderers and
+ * the completion layer need the same answer to "which axis does this name
+ * already decide?" — deriving it here keeps a hand-copied per-name mapping
+ * out of all three.
+ */
+export declare function layoutWrapperAxis(name: string): LayoutAxis | undefined;
+/**
+ * The two reserved layout attributes as `AttributeSchema`s, so a tool that
+ * completes or documents attributes reads them exactly like a component's
+ * own.
+ */
+export declare const LAYOUT_ATTRIBUTES: Readonly<Record<'width' | 'align', AttributeSchema>>;

package/dist/layout.js

@@ -0,0 +1,78 @@
+/** The two attribute names docs/format.md reserves on every block directive. */
+export const LAYOUT_ATTRIBUTE_KEYS = ['width', 'align'];
+/** The axis a wrapper of the other axis takes as an attribute (docs/spec.md §3). */
+export function otherLayoutAxis(axis) {
+    return axis === 'width' ? 'align' : 'width';
+}
+/**
+ * The closed `width=` preset vocabulary (docs/format.md), listed narrowest
+ * to widest so the list reads as the scale it is: `fit` hugs the block's
+ * own content, `normal` is the default column width, and `full` fills the
+ * column. Order is user-visible: a completion popup offers the values in
+ * this order.
+ */
+export const WIDTH_PRESETS = [
+    'fit',
+    'narrow',
+    'normal',
+    'wide',
+    'full',
+];
+/** The closed `align=` preset vocabulary (docs/format.md), in the order the docs list them. */
+export const ALIGN_PRESETS = ['left', 'center', 'right'];
+/**
+ * Wrapper-name lookups as sets rather than `Array.includes` scans: a `Set`
+ * answers "is this a wrapper name" without ever resolving through a
+ * prototype chain, so a directive literally named `constructor` or
+ * `__proto__` misses cleanly. Built from the two preset lists above, so the
+ * wrapper vocabulary can never drift from the attribute vocabulary; there
+ * is no `normal` wrapper, since the default width needs no wrapper at all.
+ */
+const ALIGN_WRAPPER_NAMES = new Set(ALIGN_PRESETS);
+const WIDTH_WRAPPER_NAMES = new Set(WIDTH_PRESETS.filter((preset) => preset !== 'normal'));
+/**
+ * The layout axis the wrapper container named `name` sets by its NAME
+ * (docs/format.md, "The same presets as wrappers"), or `undefined` when
+ * `name` is not one of the seven wrapper names.
+ *
+ * This is the one place the seven names are classified. A wrapper owns its
+ * own axis and takes the OTHER axis as an attribute, so both renderers and
+ * the completion layer need the same answer to "which axis does this name
+ * already decide?" — deriving it here keeps a hand-copied per-name mapping
+ * out of all three.
+ */
+export function layoutWrapperAxis(name) {
+    if (ALIGN_WRAPPER_NAMES.has(name))
+        return 'align';
+    if (WIDTH_WRAPPER_NAMES.has(name))
+        return 'width';
+    return undefined;
+}
+/**
+ * The two reserved layout attributes as `AttributeSchema`s, so a tool that
+ * completes or documents attributes reads them exactly like a component's
+ * own.
+ */
+export const LAYOUT_ATTRIBUTES = {
+    width: {
+        type: 'string',
+        required: false,
+        enum: WIDTH_PRESETS,
+        description: 'Sets how wide the directive renders, from narrowest to widest: ' +
+            '`fit` shrinks the block to its own content, then `narrow`, ' +
+            '`normal` at the default column width, `wide`, and `full`. ' +
+            '`normal` is the explicit default and produces no class, the same ' +
+            'as leaving `width` off entirely. An invalid value is ignored as if ' +
+            'absent; nothing errors.',
+    },
+    align: {
+        type: 'string',
+        required: false,
+        enum: ALIGN_PRESETS,
+        description: 'Places the directive within the column: `left`, `center`, or ' +
+            "`right`, defaulting to `left`. It moves the block's box and never " +
+            'its contents, so it only shows when the box is narrower than the ' +
+            'column: pair it with a `width` such as `fit` or `narrow`. An ' +
+            'invalid value is ignored as if absent; nothing errors.',
+    },
+};

package/dist/text-align.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The `text` attribute (docs/format.md, "Aligning text inside a component";
+ * docs/spec.md §3): the standard set's one content-alignment attribute.
+ *
+ * `text` is deliberately NOT part of the layout system in `./layout.ts`.
+ * `width` and `align` are reserved on every directive and are intercepted
+ * by the renderer before a component ever sees them, because they mean the
+ * same thing on every block. `text` means "align the text inside THIS
+ * component", which only a component can act on, so it reaches the
+ * component like any other attribute of its own and appears in each of
+ * those components' contracts.
+ *
+ * This module carries values only: the closed value list and the schema
+ * four contracts share. It says nothing about markup or classes; each
+ * renderer's own `layout.ts` maps a value to a class.
+ */
+import type { AttributeSchema } from './contracts.js';
+/** The closed `text=` value vocabulary, in the order docs/format.md lists them. */
+export declare const TEXT_ALIGN_PRESETS: readonly ["left", "center", "right"];
+/** One of the closed `text=` values. */
+export type TextAlignPreset = (typeof TEXT_ALIGN_PRESETS)[number];
+/**
+ * The standard components that accept `text` (docs/spec.md §3). Listed here
+ * so `./contracts.ts` builds all four from one source, and so a test can
+ * assert the set both renderers honor is exactly this one.
+ */
+export declare const TEXT_ALIGN_COMPONENTS: readonly ["row", "cell", "card", "callout"];
+/**
+ * The shared `text` schema. Identical wording on all four components on
+ * purpose: the attribute means the same thing everywhere, and a reader who
+ * learned it on `callout` should not have to re-read it on `card`. The
+ * row-specific cascade is spelled out because it is the one place `text`
+ * reaches past the component it was written on.
+ */
+export declare const TEXT_ALIGN_ATTRIBUTE: AttributeSchema;

package/dist/text-align.js

@@ -0,0 +1,31 @@
+/** The closed `text=` value vocabulary, in the order docs/format.md lists them. */
+export const TEXT_ALIGN_PRESETS = ['left', 'center', 'right'];
+/**
+ * The standard components that accept `text` (docs/spec.md §3). Listed here
+ * so `./contracts.ts` builds all four from one source, and so a test can
+ * assert the set both renderers honor is exactly this one.
+ */
+export const TEXT_ALIGN_COMPONENTS = [
+    'row',
+    'cell',
+    'card',
+    'callout',
+];
+/**
+ * The shared `text` schema. Identical wording on all four components on
+ * purpose: the attribute means the same thing everywhere, and a reader who
+ * learned it on `callout` should not have to re-read it on `card`. The
+ * row-specific cascade is spelled out because it is the one place `text`
+ * reaches past the component it was written on.
+ */
+export const TEXT_ALIGN_ATTRIBUTE = {
+    type: 'string',
+    required: false,
+    enum: TEXT_ALIGN_PRESETS,
+    description: 'Aligns the text inside this component: `left`, `center`, or `right`. ' +
+        'On a `row` it applies to every cell, a cell with its own `text` ' +
+        'overrides it, and an alignment wrapper written inside a cell wins ' +
+        'over both. Unlike the reserved `align`, which places the whole box ' +
+        'within the column, `text` never moves the box. An invalid value is ' +
+        'ignored as if absent; nothing errors.',
+};

package/package.json

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