@markii/stdlib 0.13.0 → 0.14.0

package/dist/diagnostics.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The neutral shape of a render-time diagnostic event (docs/integration.md):
+ * something a renderer recognized and handled by rendering a quiet marker
+ * instead of silently dropping content or failing outright, reported
+ * through a render engine's `onDiagnostic` option so a host can route it to
+ * its own diagnostics surface (AGENTS.md's "clean is not silent" rule: a
+ * quiet in-page marker alone is not enough, the reason must also reach a
+ * surface a host actually shows).
+ *
+ * Both platform renderers (`@markii/react`, `@markii/html`) emit this exact
+ * shape from their own independent implementations, so a host wiring up
+ * one engine's callback needs no engine-specific branching if it later
+ * adds the other. The WORDING in `message` is produced by each engine's own
+ * `failure-presentation` module (the one home of failure wording per
+ * engine) — this module only defines the envelope, never the words.
+ */
+/**
+ * `'invalid-attribute-value'` — a known attribute (one `@markii/stdlib`'s
+ * component contracts declare) received a value outside its closed enum;
+ * the component still rendered, with a quiet marker.
+ *
+ * `'unsafe-image-src'` — a component-built `<img>` (the standard `figure`)
+ * had its `src` refused as an unsafe URL scheme; the component rendered
+ * without the image, with a quiet marker.
+ */
+export type DiagnosticKind = 'invalid-attribute-value' | 'unsafe-image-src';
+export interface DiagnosticEvent {
+    readonly kind: DiagnosticKind;
+    /** The directive name the event happened on, when there is a single unambiguous one. */
+    readonly directive?: string;
+    /** The attribute name involved, for `'invalid-attribute-value'`. Absent for a kind with no single attribute to name. */
+    readonly attribute?: string;
+    /** The same human-readable text the in-page marker's tooltip carries. */
+    readonly message: string;
+}
+export type OnDiagnostic = (event: DiagnosticEvent) => void;
+/**
+ * Calls `onDiagnostic` with `event`, swallowing any exception it throws.
+ * A host-supplied callback must never be able to break rendering — the same
+ * never-throw guarantee every other render-time hook in this format carries
+ * (Architecture rule 3's spirit, extended to a host's own code). Both
+ * engines call this instead of invoking `onDiagnostic` directly, so the
+ * guard cannot drift between them.
+ */
+export declare function reportDiagnostic(onDiagnostic: OnDiagnostic | undefined, event: DiagnosticEvent): void;

package/dist/diagnostics.js

@@ -0,0 +1,34 @@
+/**
+ * The neutral shape of a render-time diagnostic event (docs/integration.md):
+ * something a renderer recognized and handled by rendering a quiet marker
+ * instead of silently dropping content or failing outright, reported
+ * through a render engine's `onDiagnostic` option so a host can route it to
+ * its own diagnostics surface (AGENTS.md's "clean is not silent" rule: a
+ * quiet in-page marker alone is not enough, the reason must also reach a
+ * surface a host actually shows).
+ *
+ * Both platform renderers (`@markii/react`, `@markii/html`) emit this exact
+ * shape from their own independent implementations, so a host wiring up
+ * one engine's callback needs no engine-specific branching if it later
+ * adds the other. The WORDING in `message` is produced by each engine's own
+ * `failure-presentation` module (the one home of failure wording per
+ * engine) — this module only defines the envelope, never the words.
+ */
+/**
+ * Calls `onDiagnostic` with `event`, swallowing any exception it throws.
+ * A host-supplied callback must never be able to break rendering — the same
+ * never-throw guarantee every other render-time hook in this format carries
+ * (Architecture rule 3's spirit, extended to a host's own code). Both
+ * engines call this instead of invoking `onDiagnostic` directly, so the
+ * guard cannot drift between them.
+ */
+export function reportDiagnostic(onDiagnostic, event) {
+    if (!onDiagnostic)
+        return;
+    try {
+        onDiagnostic(event);
+    }
+    catch {
+        // A throwing callback must never break rendering.
+    }
+}

package/dist/editor/complete/completion.d.ts

@@ -0,0 +1,15 @@
+import type { InsertableComponent } from '../insert/component-catalog.js';
+import type { CompletionContext, HoverInfo } from './types.js';
+export type { CompletionContext, CompletionContextKind, CompletionItem, CompletionItemKind, ComponentDocumentation, HoverInfo, } from './types.js';
+export { componentDocumentation, formatComponentDocumentation, } from './documentation.js';
+/**
+ * The one entry point a host calls: the current line's text, the zero-based
+ * cursor column, and the insert catalog. Never throws; returns a `'none'`
+ * context when nothing completes here.
+ */
+export declare function completionAt(line: string, column: number, catalog: readonly InsertableComponent[]): CompletionContext;
+/**
+ * The directive under the cursor, for a hover popup. `undefined` when the
+ * cursor is not on a known component's directive name.
+ */
+export declare function hoverAt(line: string, column: number, catalog: readonly InsertableComponent[]): HoverInfo | undefined;

package/dist/editor/complete/completion.js

@@ -0,0 +1,322 @@
+import { getContract } from '../../contracts.js';
+import { LAYOUT_ATTRIBUTES, LAYOUT_ATTRIBUTE_KEYS, layoutWrapperAxis, otherLayoutAxis, } from '../../layout.js';
+import { componentSkeleton } from '../insert/component-skeleton.js';
+import { firstSentence } from '../insert/first-sentence.js';
+import { clampColumn, findDirectiveNameTokenAt, parseCompletionContext, } from './directive-context.js';
+import { componentDocumentation } from './documentation.js';
+export { componentDocumentation, formatComponentDocumentation, } from './documentation.js';
+const EMPTY_CONTEXT_AT = (column) => ({
+    kind: 'none',
+    replaceStart: column,
+    replaceEnd: column,
+    items: [],
+});
+/** Whether `component` is offered when the author is typing directive `form`. A pack component with no declared kind (see `InsertableComponent.kindDeclared`) is offered in every form. */
+function componentOffersForm(component, form) {
+    if (!component.kindDeclared)
+        return true;
+    return component.kind === form;
+}
+/**
+ * Adjusts a container skeleton's opening/closing fence to use exactly the
+ * colon run the user typed (docs/format.md: an outer fence needs more
+ * colons than an inner one, e.g. `::::tabs` when nesting). The skeleton's
+ * container form is always `:::name{...}\n\n:::` — a fixed three-colon
+ * prefix and a fixed three-colon suffix — so swapping both for `colonRun`
+ * is a straight slice-and-splice; `cursorOffset` shifts by the same amount
+ * the prefix grew, since the cursor always lands before the closing fence.
+ */
+function adjustContainerFence(skeleton, colonRun) {
+    if (colonRun.length === 3)
+        return skeleton;
+    const shift = colonRun.length - 3;
+    const text = colonRun + skeleton.text.slice(3, skeleton.text.length - 3) + colonRun;
+    return { text, cursorOffset: skeleton.cursorOffset + shift };
+}
+function buildSkeleton(directiveName, kind, requiredAttributes, colonRun) {
+    const skeleton = componentSkeleton(directiveName, kind, requiredAttributes);
+    return kind === 'container'
+        ? adjustContainerFence(skeleton, colonRun)
+        : skeleton;
+}
+function directiveNameItem(component, ctx, isRestEmpty) {
+    let insertText;
+    let insertCursorOffset;
+    if (isRestEmpty) {
+        // The form the AUTHOR TYPED wins over the catalog's `kind` for a pack
+        // component that declared none: `componentOffersForm` above lets such a
+        // component through in all three forms, and the catalog's `'container'`
+        // is only a default there, not a fact. Building a container skeleton
+        // for an author who typed `::` would rewrite their two colons into a
+        // broken two-colon fence. For every other component the two agree by
+        // construction, since the filter only admits a matching form.
+        const kind = component.kindDeclared ? component.kind : ctx.form;
+        const skeleton = buildSkeleton(component.directiveName, kind, component.requiredAttributes, ctx.colonRun);
+        insertText = skeleton.text;
+        insertCursorOffset = skeleton.cursorOffset;
+    }
+    else {
+        insertText = component.directiveName;
+        insertCursorOffset = component.directiveName.length;
+    }
+    return {
+        label: component.directiveName,
+        kind: 'component',
+        detail: component.description ?? '',
+        documentation: componentDocumentation(component),
+        insertText,
+        insertCursorOffset,
+        group: component.group,
+        ...(component.packName !== undefined
+            ? { packName: component.packName }
+            : {}),
+    };
+}
+function directiveNameCompletionContext(ctx, catalog, line) {
+    const restOfLine = line.slice(ctx.replaceEnd);
+    const isRestEmpty = /^\s*$/.test(restOfLine);
+    const replaceStart = isRestEmpty
+        ? ctx.replaceStart
+        : ctx.replaceStart + ctx.colonRun.length;
+    const items = catalog
+        .filter((component) => componentOffersForm(component, ctx.form))
+        .map((component) => directiveNameItem(component, ctx, isRestEmpty));
+    return {
+        kind: 'directive-name',
+        replaceStart,
+        replaceEnd: ctx.replaceEnd,
+        tokenStart: ctx.tokenStart,
+        items,
+    };
+}
+/** The catalog entry for `directiveName`, matched case-insensitively the same way `hoverAt` matches. */
+function findCatalogEntry(catalog, directiveName) {
+    const lowered = directiveName.toLowerCase();
+    return catalog.find((component) => component.directiveName.toLowerCase() === lowered);
+}
+/**
+ * The declared attributes of the pack component named `directiveName`, or
+ * an empty list when the name is unknown, is a standard component (its
+ * attributes come from its contract instead), or declared none.
+ *
+ * On a block form the two reserved layout attributes are filtered out:
+ * `width` and `align` are offered from `@markii/stdlib`'s one layout
+ * source a few lines below, so a pack that also declares one of those
+ * names would otherwise produce two rows for the same attribute, with
+ * different values behind them. An inline directive is never offered the
+ * layout attributes at all, so there a declared `width` is the pack's own
+ * and passes through.
+ */
+function packAttributesFor(directiveName, form, catalog) {
+    const entry = findCatalogEntry(catalog, directiveName);
+    if (entry?.source !== 'pack' || entry.attributes === undefined)
+        return [];
+    if (form === 'inline')
+        return entry.attributes;
+    return entry.attributes.filter((attribute) => !LAYOUT_ATTRIBUTE_NAME_SET.has(attribute.name));
+}
+/**
+ * Expresses a pack's declared attribute as the same `AttributeSchema` a
+ * standard contract carries, so `attributeNameItem` below stays the ONE
+ * item builder for both sources rather than growing a near-duplicate for
+ * pack attributes. `default` has no place in `AttributeSchema` and is not
+ * invented into one here; it reaches the author through the attribute doc
+ * lines in `./documentation.ts`.
+ */
+function schemaForPackAttribute(attribute) {
+    return {
+        type: 'string',
+        ...(attribute.required === true ? { required: true } : {}),
+        ...(attribute.values !== undefined ? { enum: attribute.values } : {}),
+        description: attribute.description ?? '',
+    };
+}
+function attributeNameItem(name, schema) {
+    const insertText = `${name}=""`;
+    const insertCursorOffset = name.length + 2;
+    const requiredPrefix = schema.required === true ? 'required. ' : '';
+    // A pack may declare an attribute with no description at all, which a
+    // standard contract never does. Trimming keeps that case from reading as
+    // `required. ` with a dangling separator, and is a no-op for every
+    // described attribute.
+    const detail = `${requiredPrefix}${firstSentence(schema.description)}`.trim();
+    return {
+        label: name,
+        kind: 'attribute',
+        detail,
+        documentation: { summary: schema.description, attributes: [], example: '' },
+        insertText,
+        insertCursorOffset,
+    };
+}
+/**
+ * The two reserved layout attributes, read from `@markii/stdlib` rather
+ * than re-listed here: that package is the one source of the layout
+ * vocabulary, and a third hand-copied literal is exactly what it exists to
+ * prevent.
+ */
+const LAYOUT_ATTRIBUTE_NAMES = LAYOUT_ATTRIBUTE_KEYS;
+const LAYOUT_ATTRIBUTE_NAME_SET = new Set(LAYOUT_ATTRIBUTE_NAMES);
+/**
+ * Which reserved layout attributes to offer on `directiveName`, written in
+ * directive `form`.
+ *
+ * An inline directive gets none: the two keys are stripped there and have
+ * no effect, so offering them would be offering a no-op. A layout WRAPPER
+ * gets exactly one, the axis its own name did not already decide
+ * (docs/spec.md §3): `:::center` is already centered, so it offers `width`
+ * and not `align`, and `:::fit` offers `align` and not `width`. Writing the
+ * wrapper's own axis is ignored by both renderers, so completing it would
+ * be inviting the author to type something that does nothing. Every other
+ * block directive gets both.
+ */
+function layoutAttributesFor(directiveName, form) {
+    if (form === 'inline')
+        return [];
+    const ownAxis = layoutWrapperAxis(directiveName);
+    return ownAxis === undefined
+        ? LAYOUT_ATTRIBUTE_NAMES
+        : [otherLayoutAxis(ownAxis)];
+}
+function attributeNameCompletionContext(ctx, catalog) {
+    const contract = getContract(ctx.directiveName);
+    const items = [];
+    const offered = new Set();
+    if (contract !== undefined) {
+        for (const [name, schema] of Object.entries(contract.attributes)) {
+            if (ctx.presentNames.has(name.toLowerCase()))
+                continue;
+            items.push(attributeNameItem(name, schema));
+            offered.add(name.toLowerCase());
+        }
+    }
+    else {
+        // No contract means this is not a standard component, so the only
+        // attribute metadata that can exist for it is what its pack declared
+        // (issue #27 slice 4). A pack that declared none simply contributes no
+        // rows, and the layout attributes below still apply.
+        for (const attribute of packAttributesFor(ctx.directiveName, ctx.form, catalog)) {
+            if (ctx.presentNames.has(attribute.name.toLowerCase()))
+                continue;
+            items.push(attributeNameItem(attribute.name, schemaForPackAttribute(attribute)));
+            offered.add(attribute.name.toLowerCase());
+        }
+    }
+    for (const name of layoutAttributesFor(ctx.directiveName, ctx.form)) {
+        if (ctx.presentNames.has(name) || offered.has(name))
+            continue;
+        items.push(attributeNameItem(name, LAYOUT_ATTRIBUTES[name]));
+    }
+    return {
+        kind: 'attribute-name',
+        replaceStart: ctx.replaceStart,
+        replaceEnd: ctx.replaceEnd,
+        items,
+    };
+}
+function resolveValueEnum(ctx, catalog) {
+    // The same axis filter the attribute-NAME context applies, so the two can
+    // never disagree: a name that is not offered here never gets values
+    // either, and `:::center{align=` completes nothing rather than offering
+    // three values the renderer will ignore.
+    if ((ctx.attributeName === 'width' || ctx.attributeName === 'align') &&
+        layoutAttributesFor(ctx.directiveName, ctx.form).includes(ctx.attributeName)) {
+        return LAYOUT_ATTRIBUTES[ctx.attributeName].enum;
+    }
+    const contract = getContract(ctx.directiveName);
+    if (contract === undefined) {
+        // A pack component's declared `values`, read through the same filtered
+        // accessor the attribute-name context uses, so a name offered from the
+        // layout source can never take its values from a pack declaration.
+        return packAttributesFor(ctx.directiveName, ctx.form, catalog).find((attribute) => attribute.name === ctx.attributeName)?.values;
+    }
+    // `Object.hasOwn`, not bare indexing: a directive attribute literally
+    // named `constructor` or `__proto__` must miss this lookup rather than
+    // resolve through the prototype chain to an inherited `Object.prototype`
+    // member. Same defense `getContract` itself applies one level up.
+    if (!Object.hasOwn(contract.attributes, ctx.attributeName))
+        return undefined;
+    return contract.attributes[ctx.attributeName]?.enum;
+}
+function attributeValueItem(value, ctx) {
+    let insertText;
+    if (ctx.quoteChar === undefined) {
+        insertText = value;
+    }
+    else if (ctx.hasClosingQuote) {
+        insertText = value;
+    }
+    else {
+        insertText = `${value}${ctx.quoteChar}`;
+    }
+    return {
+        label: value,
+        kind: 'value',
+        detail: '',
+        insertText,
+        insertCursorOffset: insertText.length,
+    };
+}
+function attributeValueCompletionContext(ctx, catalog) {
+    const enumValues = resolveValueEnum(ctx, catalog);
+    if (enumValues === undefined || enumValues.length === 0) {
+        return EMPTY_CONTEXT_AT(ctx.replaceEnd);
+    }
+    return {
+        kind: 'attribute-value',
+        replaceStart: ctx.replaceStart,
+        replaceEnd: ctx.replaceEnd,
+        items: enumValues.map((value) => attributeValueItem(value, ctx)),
+    };
+}
+/**
+ * The one entry point a host calls: the current line's text, the zero-based
+ * cursor column, and the insert catalog. Never throws; returns a `'none'`
+ * context when nothing completes here.
+ */
+export function completionAt(line, column, catalog) {
+    try {
+        const safeLine = typeof line === 'string' ? line : '';
+        const safeCatalog = Array.isArray(catalog) ? catalog : [];
+        const clampedColumn = clampColumn(safeLine, column);
+        const ctx = parseCompletionContext(safeLine, clampedColumn);
+        switch (ctx.kind) {
+            case 'attribute-value':
+                return attributeValueCompletionContext(ctx, safeCatalog);
+            case 'attribute-name':
+                return attributeNameCompletionContext(ctx, safeCatalog);
+            case 'directive-name':
+                return directiveNameCompletionContext(ctx, safeCatalog, safeLine);
+            default:
+                return EMPTY_CONTEXT_AT(clampedColumn);
+        }
+    }
+    catch {
+        return EMPTY_CONTEXT_AT(clampColumn(line, column));
+    }
+}
+/**
+ * The directive under the cursor, for a hover popup. `undefined` when the
+ * cursor is not on a known component's directive name.
+ */
+export function hoverAt(line, column, catalog) {
+    try {
+        const safeLine = typeof line === 'string' ? line : '';
+        const safeCatalog = Array.isArray(catalog) ? catalog : [];
+        const token = findDirectiveNameTokenAt(safeLine, column);
+        if (token === undefined)
+            return undefined;
+        const entry = findCatalogEntry(safeCatalog, token.name);
+        if (entry === undefined)
+            return undefined;
+        return {
+            directiveName: entry.directiveName,
+            documentation: componentDocumentation(entry),
+            start: token.start,
+            end: token.end,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/editor/complete/directive-context.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Directive autocompletion (GitHub issue #27, slice 1): the pure line/column
+ * parser that decides WHAT kind of thing sits at the cursor — a directive
+ * name being typed, an attribute name, or an attribute value — and WHERE
+ * the accepted completion's text would replace. No knowledge of the insert
+ * catalog or `@markii/stdlib` contracts lives here; this module only reads
+ * characters. `./completion.ts` turns what this module finds into the
+ * actual `CompletionItem[]`.
+ *
+ * Every exported function is defensive: an out-of-range or negative
+ * `column`, an empty line, an unterminated brace, and an unterminated quote
+ * all produce a sensible "nothing here" result rather than throwing.
+ */
+import type { ComponentKind } from '../../contracts.js';
+/** Which of the three directive forms the text around the cursor is written as. Matches `ComponentKind`'s three values one-to-one. */
+export type DirectiveForm = ComponentKind;
+/** Attribute names already present in the brace clause, lowercased, minus the partial name currently being typed. */
+export interface AttributeNameParseResult {
+    readonly kind: 'attribute-name';
+    readonly directiveName: string;
+    readonly form: DirectiveForm;
+    readonly replaceStart: number;
+    readonly replaceEnd: number;
+    readonly partial: string;
+    readonly presentNames: ReadonlySet<string>;
+}
+export interface AttributeValueParseResult {
+    readonly kind: 'attribute-value';
+    readonly directiveName: string;
+    readonly form: DirectiveForm;
+    readonly attributeName: string;
+    readonly replaceStart: number;
+    readonly replaceEnd: number;
+    readonly partial: string;
+    /** The quote character the value was opened with, or `undefined` for an unquoted value. */
+    readonly quoteChar: '"' | "'" | undefined;
+    /** True when a closing quote matching `quoteChar` already sits after the replace range. Always `false` when `quoteChar` is `undefined`. */
+    readonly hasClosingQuote: boolean;
+}
+export interface DirectiveNameParseResult {
+    readonly kind: 'directive-name';
+    readonly form: DirectiveForm;
+    /** The colon run exactly as typed (e.g. `':'`, `'::'`, `'::::'`). */
+    readonly colonRun: string;
+    /** Start of the colon run. */
+    readonly replaceStart: number;
+    readonly replaceEnd: number;
+    /** Start of the NAME token, i.e. `replaceStart + colonRun.length` — after the colon run, where the partial name itself begins. See `CompletionContext.tokenStart`'s doc comment for why this is a separate field from `replaceStart`. */
+    readonly tokenStart: number;
+    readonly partial: string;
+}
+export type ParsedCompletionContext = AttributeNameParseResult | AttributeValueParseResult | DirectiveNameParseResult | {
+    readonly kind: 'none';
+};
+/**
+ * Clamps a possibly-hostile column (negative, non-finite, past the end of
+ * the line) into `[0, line.length]`.
+ */
+export declare function clampColumn(line: string, column: number): number;
+/**
+ * The full context-detection algorithm: attribute contexts are checked
+ * first, then the directive-name contexts, then `'none'`. `column` is
+ * clamped defensively; this function never throws.
+ */
+export declare function parseCompletionContext(line: string, column: number): ParsedCompletionContext;
+/** A directive name token found anywhere on the line, for `hoverAt`. */
+export interface DirectiveNameToken {
+    readonly name: string;
+    readonly form: DirectiveForm;
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Finds the directive-name token whose range contains or abuts `column`,
+ * anywhere on the line (not only at the end of the cursor's prefix, since
+ * hover targets an already-written directive). `undefined` when no valid
+ * opener's name range covers `column`.
+ */
+export declare function findDirectiveNameTokenAt(line: string, column: number): DirectiveNameToken | undefined;