@markii/stdlib 0.13.0 → 0.15.0

package/dist/editor/complete/directive-context.js

@@ -0,0 +1,326 @@
+const NAME_CHAR = /[A-Za-z0-9_-]/;
+/**
+ * Clamps a possibly-hostile column (negative, non-finite, past the end of
+ * the line) into `[0, line.length]`.
+ */
+export function clampColumn(line, column) {
+    const safeLine = typeof line === 'string' ? line : '';
+    const safeColumn = Number.isFinite(column) ? column : 0;
+    return Math.max(0, Math.min(safeColumn, safeLine.length));
+}
+/**
+ * The last `{` at an index below `column` with no `}` between it and
+ * `column`, or `undefined` if the nearest unmatched-looking brace character
+ * going backward is a `}` (the braces are already closed here) or there is
+ * no `{` at all.
+ */
+function findOpenBrace(line, column) {
+    for (let i = column - 1; i >= 0; i--) {
+        const ch = line[i];
+        if (ch === '}')
+            return undefined;
+        if (ch === '{')
+            return i;
+    }
+    return undefined;
+}
+/** Extends forward from `from` over identifier characters, stopping at the first non-identifier character or end of line. */
+function extendOverIdentifier(line, from) {
+    let end = from;
+    while (end < line.length && NAME_CHAR.test(line[end]))
+        end++;
+    return end;
+}
+const OPENER_RE = /(:{1,})([A-Za-z0-9_-]+)(\[[^\]]*\])?$/;
+/**
+ * Finds the directive opener a `{...}` clause belongs to: the text right
+ * before the brace must end with `:name`, `::name`, or `:::name` (three or
+ * more colons), positioned per docs/format.md's rules (a block form's colon
+ * run sits at the line's start, ignoring leading whitespace; the inline
+ * form's single colon sits at the line's start or after whitespace).
+ * `undefined` when there is no unclosed `{` below `column`, or the text
+ * before it does not look like a directive opener.
+ */
+function findAttributeOpener(line, column) {
+    const braceIndex = findOpenBrace(line, column);
+    if (braceIndex === undefined)
+        return undefined;
+    const before = line.slice(0, braceIndex);
+    const match = OPENER_RE.exec(before);
+    if (match === null)
+        return undefined;
+    const colons = match[1];
+    const name = match[2];
+    const colonStart = match.index;
+    if (colons.length >= 2) {
+        if (!/^\s*$/.test(line.slice(0, colonStart)))
+            return undefined;
+    }
+    else if (colonStart > 0 && !/\s/.test(line[colonStart - 1])) {
+        return undefined;
+    }
+    const form = colons.length === 1 ? 'inline' : colons.length === 2 ? 'leaf' : 'container';
+    return { form, directiveName: name.toLowerCase(), braceIndex };
+}
+/** The end of a brace clause: the first unquoted `}` after `braceIndex`, or `line.length` when the clause is never closed. */
+function findClauseEnd(line, braceIndex) {
+    let quote;
+    for (let i = braceIndex + 1; i < line.length; i++) {
+        const ch = line[i];
+        if (quote !== undefined) {
+            if (ch === quote)
+                quote = undefined;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === '}')
+            return i;
+    }
+    return line.length;
+}
+/** Splits `text` into whitespace-separated tokens, respecting quoted spans so a quoted value's internal whitespace never splits a token. */
+function splitTopLevelTokens(text) {
+    const tokens = [];
+    let current = '';
+    let quote;
+    for (const ch of text) {
+        if (quote !== undefined) {
+            current += ch;
+            if (ch === quote)
+                quote = undefined;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (current.length > 0) {
+                tokens.push(current);
+                current = '';
+            }
+            continue;
+        }
+        current += ch;
+    }
+    if (current.length > 0)
+        tokens.push(current);
+    return tokens;
+}
+/** Attribute names already written in a brace clause (`name=` and bare `name` tokens), lowercased. Ignores `#id`/`.class` shorthand tokens. */
+function presentAttributeNames(line, start, end) {
+    const tokens = splitTopLevelTokens(line.slice(start, end));
+    const names = new Set();
+    for (const token of tokens) {
+        if (token.startsWith('#') || token.startsWith('.'))
+            continue;
+        const eq = token.indexOf('=');
+        const name = eq === -1 ? token : token.slice(0, eq);
+        if (name.length > 0)
+            names.add(name.toLowerCase());
+    }
+    return names;
+}
+/** The attribute name whose `=` sits at `equalsIndex`, or `undefined` if no name characters precede it. Lowercased. */
+function attributeNameBeforeEquals(line, equalsIndex) {
+    let i = equalsIndex;
+    while (i > 0 && NAME_CHAR.test(line[i - 1]))
+        i--;
+    if (i === equalsIndex)
+        return undefined;
+    return line.slice(i, equalsIndex).toLowerCase();
+}
+/** Whether `column` sits inside an open quote started somewhere in `[start, column)`, tracking simple (non-escaping) quote toggles. */
+function quoteStateUpTo(line, start, column) {
+    let quote;
+    let quoteOpenIndex = -1;
+    for (let i = start; i < column; i++) {
+        const ch = line[i];
+        if (quote !== undefined) {
+            if (ch === quote) {
+                quote = undefined;
+                quoteOpenIndex = -1;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            quoteOpenIndex = i;
+        }
+    }
+    return { quote, quoteOpenIndex };
+}
+/** The attribute-name or attribute-value context inside an opened `{...}` clause, or `{ kind: 'none' }` when the cursor sits somewhere that context detection cannot make sense of (e.g. an unterminated quote not opened right after `=`). */
+function parseInsideBraces(line, column, opener) {
+    const start = opener.braceIndex + 1;
+    const qs = quoteStateUpTo(line, start, column);
+    if (qs.quote !== undefined) {
+        if (line[qs.quoteOpenIndex - 1] !== '=')
+            return { kind: 'none' };
+        const attributeName = attributeNameBeforeEquals(line, qs.quoteOpenIndex - 1);
+        if (attributeName === undefined)
+            return { kind: 'none' };
+        const valueStart = qs.quoteOpenIndex + 1;
+        let valueEnd = column;
+        while (valueEnd < line.length && line[valueEnd] !== qs.quote)
+            valueEnd++;
+        const hasClosingQuote = line[valueEnd] === qs.quote;
+        return {
+            kind: 'attribute-value',
+            directiveName: opener.directiveName,
+            form: opener.form,
+            attributeName,
+            replaceStart: valueStart,
+            replaceEnd: valueEnd,
+            partial: line.slice(valueStart, column),
+            quoteChar: qs.quote,
+            hasClosingQuote,
+        };
+    }
+    const beforeCursor = line.slice(start, column);
+    const tokenMatch = /[A-Za-z0-9_-]*$/.exec(beforeCursor);
+    const token = tokenMatch[0];
+    const tokenStart = column - token.length;
+    const prevChar = line[tokenStart - 1];
+    if (prevChar === '=') {
+        const attributeName = attributeNameBeforeEquals(line, tokenStart - 1);
+        if (attributeName === undefined)
+            return { kind: 'none' };
+        const valueEnd = extendOverIdentifier(line, column);
+        return {
+            kind: 'attribute-value',
+            directiveName: opener.directiveName,
+            form: opener.form,
+            attributeName,
+            replaceStart: tokenStart,
+            replaceEnd: valueEnd,
+            partial: token,
+            quoteChar: undefined,
+            hasClosingQuote: false,
+        };
+    }
+    if (prevChar === '{' || prevChar === ' ' || prevChar === '\t') {
+        const clauseEnd = findClauseEnd(line, opener.braceIndex);
+        const presentNames = presentAttributeNames(line, start, clauseEnd);
+        presentNames.delete(token.toLowerCase());
+        const nameEnd = extendOverIdentifier(line, column);
+        return {
+            kind: 'attribute-name',
+            directiveName: opener.directiveName,
+            form: opener.form,
+            replaceStart: tokenStart,
+            replaceEnd: nameEnd,
+            partial: token,
+            presentNames,
+        };
+    }
+    return { kind: 'none' };
+}
+/** Parses the block-form (`::`/`:::`+) directive-name context: `^(\s*)(:{2,})([A-Za-z0-9_-]*)$` against the text up to `column`. May fire with zero name characters typed. */
+function parseBlockDirectiveName(line, column) {
+    const prefix = line.slice(0, column);
+    const match = /^(\s*)(:{2,})([A-Za-z0-9_-]*)$/.exec(prefix);
+    if (match === null)
+        return undefined;
+    const ws = match[1];
+    const colons = match[2];
+    const name = match[3];
+    const colonStart = ws.length;
+    const form = colons.length === 2 ? 'leaf' : 'container';
+    const nameEnd = extendOverIdentifier(line, column);
+    return {
+        kind: 'directive-name',
+        form,
+        colonRun: colons,
+        replaceStart: colonStart,
+        replaceEnd: nameEnd,
+        tokenStart: colonStart + colons.length,
+        partial: name,
+    };
+}
+/** Parses the inline-form (single `:`) directive-name context. Requires at least one typed name character, and the colon must sit at the line start or after whitespace (and must not itself be part of a longer colon run). */
+function parseInlineDirectiveName(line, column) {
+    let i = column;
+    while (i > 0 && NAME_CHAR.test(line[i - 1]))
+        i--;
+    const nameStart = i;
+    if (nameStart === column)
+        return undefined; // no typed name characters
+    if (nameStart === 0)
+        return undefined; // no colon can precede
+    if (line[nameStart - 1] !== ':')
+        return undefined;
+    const colonIndex = nameStart - 1;
+    if (!(colonIndex === 0 || /\s/.test(line[colonIndex - 1])))
+        return undefined;
+    const nameEnd = extendOverIdentifier(line, column);
+    return {
+        kind: 'directive-name',
+        form: 'inline',
+        colonRun: ':',
+        replaceStart: colonIndex,
+        replaceEnd: nameEnd,
+        tokenStart: nameStart,
+        partial: line.slice(nameStart, column),
+    };
+}
+/**
+ * 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 function parseCompletionContext(line, column) {
+    const safeLine = typeof line === 'string' ? line : '';
+    const clampedColumn = clampColumn(safeLine, column);
+    const opener = findAttributeOpener(safeLine, clampedColumn);
+    if (opener !== undefined) {
+        return parseInsideBraces(safeLine, clampedColumn, opener);
+    }
+    const block = parseBlockDirectiveName(safeLine, clampedColumn);
+    if (block !== undefined)
+        return block;
+    const inline = parseInlineDirectiveName(safeLine, clampedColumn);
+    if (inline !== undefined)
+        return inline;
+    return { kind: 'none' };
+}
+const OPENER_SCAN_RE = /(:{1,})([A-Za-z0-9_-]+)/g;
+/**
+ * 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 function findDirectiveNameTokenAt(line, column) {
+    const safeLine = typeof line === 'string' ? line : '';
+    const clampedColumn = clampColumn(safeLine, column);
+    OPENER_SCAN_RE.lastIndex = 0;
+    let match;
+    while ((match = OPENER_SCAN_RE.exec(safeLine)) !== null) {
+        const colons = match[1];
+        const name = match[2];
+        const colonStart = match.index;
+        const nameStart = colonStart + colons.length;
+        const nameEnd = nameStart + name.length;
+        const valid = colons.length === 1
+            ? colonStart === 0 || /\s/.test(safeLine[colonStart - 1])
+            : /^\s*$/.test(safeLine.slice(0, colonStart));
+        if (valid && nameStart <= clampedColumn && clampedColumn <= nameEnd) {
+            return {
+                name: name.toLowerCase(),
+                form: colons.length === 1
+                    ? 'inline'
+                    : colons.length === 2
+                        ? 'leaf'
+                        : 'container',
+                start: nameStart,
+                end: nameEnd,
+            };
+        }
+    }
+    return undefined;
+}

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

@@ -0,0 +1,31 @@
+import type { InsertableComponent } from '../insert/component-catalog.js';
+import type { ComponentDocumentation } from './types.js';
+/**
+ * Builds the structured documentation for one catalog entry: a standard
+ * component's contract description and attribute list (its full prose, not
+ * the picker row's first-sentence truncation), or a pack component's own
+ * declared description and declared attribute list (issue #27 slice 4).
+ * Never composed filler text: a pack that declares neither gets empty
+ * strings and an empty list, and the host decides what, if anything, to
+ * show in their place.
+ */
+export declare function componentDocumentation(component: InsertableComponent): ComponentDocumentation;
+/**
+ * Renders `ComponentDocumentation` as plain text for a host with no
+ * rich-text popup:
+ *
+ * ```
+ * <summary>
+ *
+ * Attributes:
+ * - type: info | warning | danger
+ * - title
+ *
+ * Example: :::callout{}
+ * ```
+ *
+ * Any section with nothing to show is omitted entirely, and the result
+ * never ends with a trailing blank line. All-empty documentation formats to
+ * the empty string.
+ */
+export declare function formatComponentDocumentation(doc: ComponentDocumentation): string;

package/dist/editor/complete/documentation.js

@@ -0,0 +1,92 @@
+import { getContract } from '../../contracts.js';
+import { componentSkeleton } from '../insert/component-skeleton.js';
+/** `name`, `name (required)`, `name: a | b`, or `name (required): a | b`. */
+function attributeDocLine(name, schema) {
+    const requiredPart = schema.required === true ? ' (required)' : '';
+    const enumPart = schema.enum !== undefined ? `: ${schema.enum.join(' | ')}` : '';
+    return `${name}${requiredPart}${enumPart}`;
+}
+/**
+ * The same line for a pack's declared attribute, plus the one thing a
+ * standard contract has no field for: a declared `default`, appended as
+ * `(default: x)`. Everything else lines up with `attributeDocLine` above
+ * so a reader cannot tell from the shape of the line whether the
+ * attributes came from a contract or from a `pack.json`.
+ */
+function packAttributeDocLine(attribute) {
+    const requiredPart = attribute.required === true ? ' (required)' : '';
+    const valuesPart = attribute.values !== undefined ? `: ${attribute.values.join(' | ')}` : '';
+    const defaultPart = attribute.default !== undefined ? ` (default: ${attribute.default})` : '';
+    return `${attribute.name}${requiredPart}${valuesPart}${defaultPart}`;
+}
+/**
+ * The one-line usage example built from `componentSkeleton`. For a
+ * container, only the opening fence line is shown (`:::name{}`, with its
+ * brace clause and required attributes if any) rather than the multi-line
+ * `\n\n:::` body form — that is the line an author actually recognizes as
+ * "how do I write this".
+ */
+function exampleFor(component) {
+    const skeleton = componentSkeleton(component.directiveName, component.kind, component.requiredAttributes);
+    if (component.kind !== 'container')
+        return skeleton.text;
+    const newline = skeleton.text.indexOf('\n');
+    return newline === -1 ? skeleton.text : skeleton.text.slice(0, newline);
+}
+/**
+ * Builds the structured documentation for one catalog entry: a standard
+ * component's contract description and attribute list (its full prose, not
+ * the picker row's first-sentence truncation), or a pack component's own
+ * declared description and declared attribute list (issue #27 slice 4).
+ * Never composed filler text: a pack that declares neither gets empty
+ * strings and an empty list, and the host decides what, if anything, to
+ * show in their place.
+ */
+export function componentDocumentation(component) {
+    const example = exampleFor(component);
+    if (component.source === 'standard') {
+        const contract = getContract(component.directiveName);
+        if (contract === undefined) {
+            return { summary: component.description ?? '', attributes: [], example };
+        }
+        return {
+            summary: contract.description,
+            attributes: Object.entries(contract.attributes).map(([name, schema]) => attributeDocLine(name, schema)),
+            example,
+        };
+    }
+    return {
+        summary: component.description ?? '',
+        attributes: (component.attributes ?? []).map((attribute) => packAttributeDocLine(attribute)),
+        example,
+    };
+}
+/**
+ * Renders `ComponentDocumentation` as plain text for a host with no
+ * rich-text popup:
+ *
+ * ```
+ * <summary>
+ *
+ * Attributes:
+ * - type: info | warning | danger
+ * - title
+ *
+ * Example: :::callout{}
+ * ```
+ *
+ * Any section with nothing to show is omitted entirely, and the result
+ * never ends with a trailing blank line. All-empty documentation formats to
+ * the empty string.
+ */
+export function formatComponentDocumentation(doc) {
+    const sections = [];
+    if (doc.summary.length > 0)
+        sections.push(doc.summary);
+    if (doc.attributes.length > 0) {
+        sections.push(['Attributes:', ...doc.attributes.map((line) => `- ${line}`)].join('\n'));
+    }
+    if (doc.example.length > 0)
+        sections.push(`Example: ${doc.example}`);
+    return sections.join('\n\n');
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Directive autocompletion (GitHub issue #27, slice 1): the public surface
+ * both hosts' completion providers import. See `./completion.ts` for
+ * `completionAt`/`hoverAt`, `./documentation.ts` for
+ * `componentDocumentation`/`formatComponentDocumentation`, and `./types.ts`
+ * for the shared contract types.
+ */
+export type { CompletionContext, CompletionContextKind, CompletionItem, CompletionItemKind, ComponentDocumentation, HoverInfo, } from './types.js';
+export { completionAt, componentDocumentation, formatComponentDocumentation, hoverAt, } from './completion.js';

package/dist/editor/complete/index.js

@@ -0,0 +1 @@
+export { completionAt, componentDocumentation, formatComponentDocumentation, hoverAt, } from './completion.js';

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

@@ -0,0 +1,82 @@
+/**
+ * Directive autocompletion (GitHub issue #27, slice 1): the public types
+ * both `completionAt`/`hoverAt` (`./completion.ts`) and
+ * `componentDocumentation`/`formatComponentDocumentation`
+ * (`./documentation.ts`) are built against. Kept in their own module so
+ * neither of those implementation files has to import the other just to
+ * share a type — this is the one seam every editor host (a `@markii/*`
+ * host in this repo, or a third-party one importing `@markii/stdlib/editor`
+ * directly) codes against, so its names and shapes are a contract, not an
+ * implementation detail.
+ */
+/** What a completion item inserts and where it came from. */
+export type CompletionItemKind = 'component' | 'attribute' | 'value';
+/** Structured documentation for a component or attribute, so a host can render it its own way. */
+export interface ComponentDocumentation {
+    /** Full prose: a standard component's contract description, a pack component's declared description, or an attribute's description. Empty string when none is available. */
+    readonly summary: string;
+    /** One line per attribute, e.g. `type (required): info | warning | danger`. Empty for an attribute's own documentation. */
+    readonly attributes: readonly string[];
+    /** A one-line usage example built from the skeleton builder, e.g. `:::callout{}`. Empty when there is nothing useful to show. */
+    readonly example: string;
+}
+export interface CompletionItem {
+    /** What the picker shows and filters on: a directive name, an attribute name, or an attribute value. */
+    readonly label: string;
+    readonly kind: CompletionItemKind;
+    /** One short line for the row's secondary text. May be empty. */
+    readonly detail: string;
+    /** Structured docs, when there are any. */
+    readonly documentation?: ComponentDocumentation;
+    /** The exact PLAIN text that replaces the context's range. Never a snippet, never host-specific syntax. */
+    readonly insertText: string;
+    /** Character offset within `insertText` where the cursor should land afterward. Same convention as `componentSkeleton`'s `cursorOffset`. */
+    readonly insertCursorOffset: number;
+    /** Present on a `component` item: which catalog group it came from, so a host can render its own origin tag. */
+    readonly group?: 'standard' | 'layout' | 'pack';
+    /** Present on a `component` item from a pack. */
+    readonly packName?: string;
+}
+export type CompletionContextKind = 'none' | 'directive-name' | 'attribute-name' | 'attribute-value';
+export interface CompletionContext {
+    readonly kind: CompletionContextKind;
+    /**
+     * Zero-based column an accepted item's `insertText` replaces FROM. Equals
+     * `replaceEnd` when `kind` is `'none'`.
+     *
+     * `replaceStart` and `tokenStart` answer two different questions and a
+     * host that uses one for the other's job gets a working-looking popup
+     * that silently filters everything out (GitHub issue #50). `replaceStart`
+     * is the REPLACE-RANGE start: for a `'directive-name'` context on an
+     * otherwise-empty rest of the line, it sits at the start of the COLON RUN
+     * (`:::`), not at the directive name, because accepting an item there
+     * replaces the whole fence with the chosen component's skeleton. A host
+     * that also uses this value as the text a popup FILTERS candidates
+     * against (CodeMirror's `CompletionResult.from` is exactly that) ends up
+     * comparing the typed text `":::cal"` against labels like `"callout"`:
+     * the leading colons never match, and the popup opens empty. Use
+     * `tokenStart` for filtering; use `replaceStart` for the edit.
+     */
+    readonly replaceStart: number;
+    /** Zero-based column the replacement ends at. */
+    readonly replaceEnd: number;
+    /**
+     * Zero-based column where the NAME token itself starts, i.e. `replaceStart`
+     * plus the colon run's length for a `'directive-name'` context (for
+     * `:::cal` with `replaceStart` 0, `tokenStart` is 3). This is the value a
+     * filtering completion host (one that scores candidates against the
+     * text between its own `from` and the cursor) should hand back as that
+     * `from`, since candidate labels never carry the leading colons.
+     * `undefined` for every other context kind, where `replaceStart` already
+     * sits at the token being replaced and there is nothing separate to name.
+     */
+    readonly tokenStart?: number;
+    readonly items: readonly CompletionItem[];
+}
+export interface HoverInfo {
+    readonly directiveName: string;
+    readonly documentation: ComponentDocumentation;
+    /** Zero-based columns of the directive name token being hovered, for a host that highlights the range. */
+    readonly start: number;
+    readonly end: number;
+}

package/dist/editor/complete/types.js

@@ -0,0 +1,12 @@
+/**
+ * Directive autocompletion (GitHub issue #27, slice 1): the public types
+ * both `completionAt`/`hoverAt` (`./completion.ts`) and
+ * `componentDocumentation`/`formatComponentDocumentation`
+ * (`./documentation.ts`) are built against. Kept in their own module so
+ * neither of those implementation files has to import the other just to
+ * share a type — this is the one seam every editor host (a `@markii/*`
+ * host in this repo, or a third-party one importing `@markii/stdlib/editor`
+ * directly) codes against, so its names and shapes are a contract, not an
+ * implementation detail.
+ */
+export {};