@markii/stdlib 0.12.1 → 0.14.0

package/dist/editor/insert/component-skeleton.d.ts

@@ -0,0 +1,58 @@
+/**
+ * "Insert Component" (GitHub issue #17, slice 1): given a component's
+ * directive form and its required attributes, produces the exact directive
+ * text a host inserts at the cursor, plus where the cursor should land
+ * afterward so the author's next keystroke lands somewhere useful — inside
+ * the body for a component with nothing required, inside the first required
+ * attribute's quotes otherwise, since that is the first thing the author
+ * must fill in.
+ *
+ * Pure and host-neutral: no editor API, no knowledge of `vscode` or
+ * `obsidian`. Both hosts turn `ComponentSkeleton.cursorOffset` into their
+ * own editor's line/column (or offset) type using `offsetToLineColumn`
+ * below.
+ */
+import type { ComponentKind } from '../../contracts.js';
+/** The text to insert, and where the cursor should land within it. */
+export interface ComponentSkeleton {
+    /** The exact text to insert at the cursor. */
+    readonly text: string;
+    /** Character offset within `text` where the cursor should land after insertion. */
+    readonly cursorOffset: number;
+}
+/**
+ * Builds the skeleton for one directive. `requiredAttributes` is the
+ * contract's required attribute names, in the contract's own declared
+ * order (`@markii/stdlib`'s `ComponentContract.attributes` key order) —
+ * only required attributes are ever pre-filled; an optional attribute is
+ * never emitted, keeping the inserted text as small as the directive can
+ * legally be.
+ *
+ * Directive forms match docs/format.md's three spellings:
+ * - `container`: `:::NAME{...}\n\n:::`
+ * - `leaf`:      `::NAME{...}`
+ * - `inline`:    `:NAME[...]{...}`
+ *
+ * A directive with no required attributes of its own gets no `{}` clause at
+ * all, in every form: an empty brace pair is pointless noise the author
+ * would otherwise have to delete by hand, the same reasoning the inline
+ * form already applied (`[...]` is already its content slot). A container
+ * with nothing required lands the cursor in its empty body, between the
+ * fences; a leaf lands it right after the name, since there is nowhere else
+ * useful to put it.
+ */
+export declare function componentSkeleton(directiveName: string, kind: ComponentKind, requiredAttributes: readonly string[]): ComponentSkeleton;
+/** Zero-based line and column, both counting from 0. */
+export interface LineColumn {
+    readonly line: number;
+    readonly column: number;
+}
+/**
+ * Converts a character offset within `text` into a zero-based line/column,
+ * counting `\n` as the only line terminator (matching every directive
+ * skeleton this module produces, which never contains `\r`). An
+ * out-of-range offset (negative, or past the end of `text`) is clamped to
+ * the end of `text` rather than throwing — a defensive posture matching
+ * this package's other pure helpers.
+ */
+export declare function offsetToLineColumn(text: string, offset: number): LineColumn;

package/dist/editor/insert/component-skeleton.js

@@ -0,0 +1,85 @@
+/**
+ * Builds the skeleton for one directive. `requiredAttributes` is the
+ * contract's required attribute names, in the contract's own declared
+ * order (`@markii/stdlib`'s `ComponentContract.attributes` key order) —
+ * only required attributes are ever pre-filled; an optional attribute is
+ * never emitted, keeping the inserted text as small as the directive can
+ * legally be.
+ *
+ * Directive forms match docs/format.md's three spellings:
+ * - `container`: `:::NAME{...}\n\n:::`
+ * - `leaf`:      `::NAME{...}`
+ * - `inline`:    `:NAME[...]{...}`
+ *
+ * A directive with no required attributes of its own gets no `{}` clause at
+ * all, in every form: an empty brace pair is pointless noise the author
+ * would otherwise have to delete by hand, the same reasoning the inline
+ * form already applied (`[...]` is already its content slot). A container
+ * with nothing required lands the cursor in its empty body, between the
+ * fences; a leaf lands it right after the name, since there is nowhere else
+ * useful to put it.
+ */
+export function componentSkeleton(directiveName, kind, requiredAttributes) {
+    const attributesClause = attributeClause(requiredAttributes);
+    if (kind === 'container') {
+        if (requiredAttributes.length === 0) {
+            const prefix = `:::${directiveName}\n`;
+            return { text: `${prefix}\n:::`, cursorOffset: prefix.length };
+        }
+        const prefix = `:::${directiveName}${attributesClause}\n`;
+        return {
+            text: `${prefix}\n:::`,
+            cursorOffset: firstAttributeQuoteOffset(prefix),
+        };
+    }
+    if (kind === 'leaf') {
+        if (requiredAttributes.length === 0) {
+            const text = `::${directiveName}`;
+            return { text, cursorOffset: text.length };
+        }
+        const text = `::${directiveName}${attributesClause}`;
+        return { text, cursorOffset: firstAttributeQuoteOffset(text) };
+    }
+    // inline
+    if (requiredAttributes.length === 0) {
+        const text = `:${directiveName}[]`;
+        return { text, cursorOffset: text.length - 1 };
+    }
+    const text = `:${directiveName}[]${attributesClause}`;
+    return { text, cursorOffset: firstAttributeQuoteOffset(text) };
+}
+/** `{attr=""}` for one or more required attribute names, space-separated in the given order. Empty input never reaches this — callers branch on `requiredAttributes.length === 0` first. */
+function attributeClause(requiredAttributes) {
+    const parts = requiredAttributes.map((name) => `${name}=""`);
+    return `{${parts.join(' ')}}`;
+}
+/**
+ * The offset of the character right after the first `="` in `text` — i.e.
+ * inside the first attribute's quotes. `text` is always one this module
+ * just built from `attributeClause`, so `="` is always present.
+ */
+function firstAttributeQuoteOffset(text) {
+    const marker = '="';
+    const index = text.indexOf(marker);
+    return index + marker.length;
+}
+/**
+ * Converts a character offset within `text` into a zero-based line/column,
+ * counting `\n` as the only line terminator (matching every directive
+ * skeleton this module produces, which never contains `\r`). An
+ * out-of-range offset (negative, or past the end of `text`) is clamped to
+ * the end of `text` rather than throwing — a defensive posture matching
+ * this package's other pure helpers.
+ */
+export function offsetToLineColumn(text, offset) {
+    const clamped = Math.max(0, Math.min(offset, text.length));
+    let line = 0;
+    let lastNewlineEnd = 0;
+    for (let i = 0; i < clamped; i++) {
+        if (text[i] === '\n') {
+            line++;
+            lastNewlineEnd = i + 1;
+        }
+    }
+    return { line, column: clamped - lastNewlineEnd };
+}

package/dist/editor/insert/first-sentence.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Truncates `description` to its first sentence, for a picker row that has
+ * no room for a contract's full prose. Shared by `./component-catalog.ts`
+ * (a component's picker-row description) and `../complete/documentation.ts`
+ * (an attribute's completion-row detail), so the sentence-boundary rule
+ * lives in exactly one place.
+ *
+ * A sentence boundary is a period followed by a space AND an uppercase
+ * letter, NOT merely ". ". Almost every contract description in
+ * `@markii/stdlib` contains "e.g. " before its first real sentence break,
+ * and a bare ". " split truncates 19 of the 20 standard components to a
+ * row reading "A titled panel, e.g." — the example, which is the useful
+ * half, cut off mid-phrase. The uppercase requirement steps over "e.g. `"
+ * and "... :::`" alike, because neither is followed by a capital.
+ *
+ * When no such boundary exists the whole string is returned unchanged: a
+ * description that is already one sentence is not worth mangling further.
+ */
+export declare function firstSentence(description: string): string;

package/dist/editor/insert/first-sentence.js

@@ -0,0 +1,24 @@
+/**
+ * Truncates `description` to its first sentence, for a picker row that has
+ * no room for a contract's full prose. Shared by `./component-catalog.ts`
+ * (a component's picker-row description) and `../complete/documentation.ts`
+ * (an attribute's completion-row detail), so the sentence-boundary rule
+ * lives in exactly one place.
+ *
+ * A sentence boundary is a period followed by a space AND an uppercase
+ * letter, NOT merely ". ". Almost every contract description in
+ * `@markii/stdlib` contains "e.g. " before its first real sentence break,
+ * and a bare ". " split truncates 19 of the 20 standard components to a
+ * row reading "A titled panel, e.g." — the example, which is the useful
+ * half, cut off mid-phrase. The uppercase requirement steps over "e.g. `"
+ * and "... :::`" alike, because neither is followed by a capital.
+ *
+ * When no such boundary exists the whole string is returned unchanged: a
+ * description that is already one sentence is not worth mangling further.
+ */
+export function firstSentence(description) {
+    const boundary = /\.\s+(?=[A-Z])/.exec(description);
+    if (boundary === null)
+        return description;
+    return description.slice(0, boundary.index + 1);
+}

package/dist/index.d.ts

@@ -3,3 +3,5 @@ export { ALIGN_PRESETS, LAYOUT_ATTRIBUTE_KEYS, LAYOUT_ATTRIBUTES, WIDTH_PRESETS,
 export { TEXT_ALIGN_ATTRIBUTE, TEXT_ALIGN_COMPONENTS, TEXT_ALIGN_PRESETS, type TextAlignPreset, } from './text-align.js';
 export { formatValue, isNumericLike, FORMAT_ATTRIBUTE, DECIMALS_ATTRIBUTE, type ValueFormat, } from './value-format.js';
 export { deriveTableShape, type TableShape } from './table-shape.js';
+export { reportDiagnostic, type DiagnosticEvent, type DiagnosticKind, type OnDiagnostic, } from './diagnostics.js';
+export { INTERACTIVE_ATTRIBUTE } from './interactive.js';

package/dist/index.js

@@ -3,3 +3,5 @@ export { ALIGN_PRESETS, LAYOUT_ATTRIBUTE_KEYS, LAYOUT_ATTRIBUTES, WIDTH_PRESETS,
 export { TEXT_ALIGN_ATTRIBUTE, TEXT_ALIGN_COMPONENTS, TEXT_ALIGN_PRESETS, } from './text-align.js';
 export { formatValue, isNumericLike, FORMAT_ATTRIBUTE, DECIMALS_ATTRIBUTE, } from './value-format.js';
 export { deriveTableShape } from './table-shape.js';
+export { reportDiagnostic, } from './diagnostics.js';
+export { INTERACTIVE_ATTRIBUTE } from './interactive.js';

package/dist/interactive.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The interactive-element marker contract (docs/integration.md): an editor
+ * host that renders Markii output as a live-preview widget needs to tell,
+ * from a DOM click target, whether it landed on a genuinely interactive
+ * control (a tab button, a details/script-marker summary) versus plain text
+ * — text reveals the raw source for editing, a control acts instead.
+ *
+ * `@markii/react` and `@markii/html` both put this attribute on every
+ * element they emit that is a real `<button>`, carries `role="tab"` or
+ * `role="button"`, or is a `<summary>`. It is also the contract a pack's own
+ * component is expected to follow for its own interactive elements — this
+ * package carries no enforcement (a pack is arbitrary code), only the one
+ * name every renderer and pack should agree on.
+ */
+export declare const INTERACTIVE_ATTRIBUTE = "data-mk-interactive";

package/dist/interactive.js

@@ -0,0 +1,15 @@
+/**
+ * The interactive-element marker contract (docs/integration.md): an editor
+ * host that renders Markii output as a live-preview widget needs to tell,
+ * from a DOM click target, whether it landed on a genuinely interactive
+ * control (a tab button, a details/script-marker summary) versus plain text
+ * — text reveals the raw source for editing, a control acts instead.
+ *
+ * `@markii/react` and `@markii/html` both put this attribute on every
+ * element they emit that is a real `<button>`, carries `role="tab"` or
+ * `role="button"`, or is a `<summary>`. It is also the contract a pack's own
+ * component is expected to follow for its own interactive elements — this
+ * package carries no enforcement (a pack is arbitrary code), only the one
+ * name every renderer and pack should agree on.
+ */
+export const INTERACTIVE_ATTRIBUTE = 'data-mk-interactive';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/stdlib",
-  "version": "0.12.1",
+  "version": "0.14.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",
@@ -28,6 +28,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./editor": {
+      "types": "./dist/editor/index.d.ts",
+      "import": "./dist/editor/index.js",
+      "default": "./dist/editor/index.js"
     }
   },
   "files": [