/**
 * Semantic layer over the syntactic scanner: validates attributes against
 * the sdoc language rules and produces typed entities ready for the Vite
 * plugin, the CLI app-gen, and the editor tooling.
 */
import { type ScanError, type Span, type TagBlock } from './scanner.js';
import type { ComponentStatus, DocNote, GlossaryBlock, TodoItem } from '../types.js';
export type { TodoItem };
export type ArgValue = string | number | boolean | null;
/** Explicit presentation overrides from stage attributes */
export interface Sizing {
    maxWidth: string | null;
    padding: string | null;
    /** flex-direction of preview/example stages */
    direction: string | null;
    /** gap of preview/example stages */
    gap: string | null;
    /** horizontal alignment of preview/example stage contents */
    contentX: string | null;
    /** vertical alignment of preview/example stage contents */
    contentY: string | null;
    /** background of preview/example stages — a CSS color or var() */
    background: string | null;
    /** minimum height of preview/example stages — a CSS length; reserves room
     * for content that overflows the stage, like an open dropdown */
    minHeight: string | null;
    /** table-of-contents visibility (DOC) */
    toc: boolean | null;
}
export interface PreviewBlock {
    /** The identifier from component={X}; null when invalid/missing (already reported) */
    componentName: string | null;
    /** Parsed args literal; null when absent or invalid */
    args: Record<string, ArgValue> | null;
    /** Exact source of the args expression (inner object), for code display */
    argsRaw: string | null;
    /** Explicit title="…" override, when present */
    title: string | null;
    /** Short text rendered with the preview, when present */
    description: string | null;
    /** Other names this component answers to, from synonyms="…". Shown with
     * the preview and searched by the MCP server; empty when absent. */
    synonyms: string[];
    /** Where this component sits in its life, from status="…"; null when the
     * author did not say. */
    status: ComponentStatus | null;
    /** Tab label: the title override or the component name */
    label: string;
    sizing: Sizing;
    /** Normalized full body — block script/style included (display/formatting form) */
    body: string;
    bodySpan: Span;
    /** Block-level <script>, when the body opens with one */
    script: TagBlock | null;
    /** Block-level <style>, when the body ends with one */
    style: TagBlock | null;
    /** Normalized markup between the block script and style */
    markup: string;
    span: Span;
}
export interface ExampleBlock {
    title: string;
    /** Short text rendered under the example heading, when present */
    description: string | null;
    /** What this example shows, from tags="…" — the parts or contexts it
     * belongs to. Shown under the description and searched by the MCP
     * server; empty when absent. */
    tags: string[];
    /** Standing remarks from a nested [NOTES] block; empty when there is none */
    notes: DocNote[];
    /** The checklist from a nested [TODO] block; empty when there is none */
    todos: TodoItem[];
    /** Markdown from a nested [PROSE] block, rendered under the title */
    prose: string | null;
    /** `code="false"` hides this example's code panel; true by default. */
    showCode: boolean;
    sizing: Sizing;
    /** Normalized full body — block script/style included (display/formatting form) */
    body: string;
    bodySpan: Span;
    /** Block-level <script>, when the body opens with one */
    script: TagBlock | null;
    /** Block-level <style>, when the body ends with one */
    style: TagBlock | null;
    /** Normalized markup between the block script and style */
    markup: string;
    span: Span;
}
/** One `- [ ] text` line of a `[TODO]` block, with whatever nests under it. */
/**
 * One item in a [SHOWCASE]'s body, in source order.
 *
 * `[COMPONENT]` blocks are tabs rather than flow: several of them share one
 * stage, one set of code panels and one API table, so the whole tab strip is a
 * single item here — which is what lets prose sit before or after it and mean
 * something. `index` points into the entity's own `previews`/`examples`/
 * `prose` arrays.
 */
export type FlowItem = {
    kind: 'components';
    indices: number[];
} | {
    kind: 'example';
    index: number;
} | {
    kind: 'prose';
    index: number;
} | {
    kind: 'glossary';
    index: number;
};
export interface ShowcaseEntity {
    kind: 'SHOWCASE';
    title: string;
    slug: string;
    /** Explicit route leaf from slug="…"; null → slugified title segment */
    routeSlug: string | null;
    /** `hide` flag: routable but never listed in a sidebar */
    hide: boolean;
    /** Standing remarks from a [NOTES] block; empty when there is none */
    notes: DocNote[];
    /** The checklist from a [TODO] block; empty when there is none */
    todos: TodoItem[];
    /** Markdown from [PROSE] blocks, in source order; empty when there are none */
    prose: string[];
    /** What the entity shows, in the order it was written. */
    flow: FlowItem[];
    /** [GLOSSARY] blocks, in source order. */
    glossaries: GlossaryBlock[];
    description: string | null;
    sizing: Sizing;
    /** Entity-level <script> — shared by every block of this entity */
    script: TagBlock | null;
    /** Entity-level <style> — joins the stage css of this entity's blocks */
    style: TagBlock | null;
    previews: PreviewBlock[];
    examples: ExampleBlock[];
    openerSpan: Span;
    span: Span;
}
export interface DocEntity {
    kind: 'DOC';
    title: string;
    slug: string;
    /** Explicit route leaf from slug="…"; null → slugified title segment */
    routeSlug: string | null;
    /** `hide` flag: routable but never listed in a sidebar */
    hide: boolean;
    /** Standing remarks from a [NOTES] block; empty when there is none */
    notes: DocNote[];
    /** The checklist from a [TODO] block; empty when there is none */
    todos: TodoItem[];
    /** Markdown from [PROSE] blocks, in source order; empty when there are none */
    prose: string[];
    /** [GLOSSARY] blocks, in source order — spliced into the body where they
     * were written, the way examples are. */
    glossaries: GlossaryBlock[];
    sizing: Sizing;
    /** Entity-level <script> — shared by every block of this entity */
    script: TagBlock | null;
    /** Entity-level <style> — joins the stage css of this entity's blocks */
    style: TagBlock | null;
    /** Prose body with each [example] block replaced by a
     * `{@render __sdocsExample?.(i)}` marker the doc renderer resolves. */
    body: string;
    /** The doc's [example] blocks, in marker order */
    examples: ExampleBlock[];
    bodySpan: Span;
    openerSpan: Span;
    span: Span;
}
/** A Svelte-built page in the docs app's own context: the body is plain
 * Svelte (no markdown), rendered as a real page without stage tooling. */
export interface PageEntity {
    kind: 'PAGE';
    title: string;
    slug: string;
    /** Explicit route leaf from slug="…"; null → slugified title segment */
    routeSlug: string | null;
    /** `hide` flag: routable but never listed in a sidebar */
    hide: boolean;
    /** Standing remarks from a [NOTES] block; empty when there is none */
    notes: DocNote[];
    /** The checklist from a [TODO] block; empty when there is none */
    todos: TodoItem[];
    /** Markdown from [PROSE] blocks, in source order; empty when there are none */
    prose: string[];
    sizing: Sizing;
    /** Entity-level <script> — shared by every block of this entity */
    script: TagBlock | null;
    /** Entity-level <style> — joins the stage css of this entity's blocks */
    style: TagBlock | null;
    body: string;
    bodySpan: Span;
    openerSpan: Span;
    span: Span;
}
export interface LayoutEntity {
    kind: 'LAYOUT';
    title: string;
    slug: string;
    /** Explicit route leaf from slug="…"; null → slugified title segment */
    routeSlug: string | null;
    /** `hide` flag: routable but never listed in a sidebar */
    hide: boolean;
    /** Standing remarks from a [NOTES] block; empty when there is none */
    notes: DocNote[];
    /** The checklist from a [TODO] block; empty when there is none */
    todos: TodoItem[];
    /** Markdown from [PROSE] blocks, in source order; empty when there are none */
    prose: string[];
    sizing: Sizing;
    /** Entity-level <script> — shared by every block of this entity */
    script: TagBlock | null;
    /** Entity-level <style> — joins the stage css of this entity's blocks */
    style: TagBlock | null;
    body: string;
    bodySpan: Span;
    openerSpan: Span;
    span: Span;
}
/**
 * A composition documented as one thing: a user menu, a notifications system.
 *
 * Structurally a [SHOWCASE] with the prop half switched off — the same blocks,
 * the same flow, the same stages — but no [COMPONENT], because a composition
 * has no single component whose API it could document. `previews` is always
 * empty; it is kept so the two kinds share every code path that reads them.
 */
export interface PatternEntity extends Omit<ShowcaseEntity, 'kind'> {
    kind: 'PATTERNS';
}
export type SdocEntity = ShowcaseEntity | DocEntity | PageEntity | LayoutEntity | PatternEntity;
export interface SdocDocument {
    script: TagBlock | null;
    style: TagBlock | null;
    entities: SdocEntity[];
    diagnostics: ScanError[];
    source: string;
}
/**
 * Normalize a raw block body for consumption: strip the common leading
 * indentation (bodies sit one level deep inside their block), drop a
 * trailing carriage return per line, and unescape lines that start with
 * `\[` (the escape for body lines that would otherwise read as tags).
 * The scanner keeps the raw text and spans; this is the display/runtime form.
 */
export declare function normalizeBody(raw: string): string;
/**
 * Slug used for entity addressing: relPath + '#' + slug.
 *
 * The same rule the routes use. It was ASCII-only, which meant every title in
 * a script without one — Cyrillic, CJK, Arabic — collapsed to 'untitled', and
 * a second such entity in the file was a duplicate-address error. The routes
 * had already been taught to keep those letters; this had not.
 */
export declare function slugifyTitle(title: string): string;
/** URL-safe slug for an example snippet. The 'x-' prefix keeps example slugs
 * clear of 'content' and of most preview slugs — a preview label can still
 * produce the same slug ("X Ray" → x-ray vs example "Ray" → x-ray), which
 * gets a diagnostic here and a deterministic numeric suffix in the planner. */
export declare function exampleSlug(title: string): string;
/** URL-safe slug for a preview snippet (from its tab label). */
export declare function previewSlug(label: string): string;
/** The local identifiers an import statement list binds — default, namespace,
 * and named (respecting `as` aliases). Offsets are relative to `script`. */
export declare function importedNames(script: string): Map<string, Span>;
export interface AttrRule {
    /** required | optional */
    required: boolean;
    /** expected value kind ('bare' = a lone flag, no value) */
    kind: 'string' | 'expression' | 'bare';
    hint: string;
    /** Diagnostic code when the attribute is missing or its value has the
     * wrong kind (defaults: 'missing-attr' / 'attr-value-kind'). A dedicated
     * code lets the build treat an unusable attribute as an error. */
    code?: string;
}
/** Allowed attributes and their value shapes for a block, keyed by kind
 * ('SHOWCASE'|'DOC'|'PAGE'|'LAYOUT'|'preview'|'example'). Single source of
 * truth for both diagnostics and editor attribute completions.
 *
 * Entity kinds are uppercase; a sub-block tag is accepted in either casing,
 * matching the parser — a file the formatter has not reached yet is still a
 * file the editor has to help with. */
export declare function attributeRules(kind: string): Record<string, AttrRule>;
/**
 * The `[NOTES]` vocabulary, **worst first** — the order the sidebar rolls a
 * subtree up by.
 *
 * Status only, deliberately. `a11y`, `perf` and the like are categories, not
 * statuses, and mixing the two makes the ranking meaningless: there is no
 * honest answer to whether an `a11y` note outranks a `bug`. Categories are
 * what `tags` already does.
 *
 * A line with no type sits between `wip` and `ready`: it says "read me"
 * without saying what about, which is more than a note whose whole content is
 * reassurance.
 */
export { NOTE_TYPES, NOTE_TYPE_ORDER } from '../note-order.js';
/** The lifecycle a `[COMPONENT]` may declare, in order. */
export declare const COMPONENT_STATUSES: readonly ComponentStatus[];
/**
 * Parse a preview args expression: a flat object literal whose values are
 * plain literals (strings, numbers, booleans, null). Anything richer belongs
 * in the block body, so it is rejected here.
 */
export declare function parseArgsLiteral(raw: string, span: Span, diagnostics: ScanError[]): Record<string, ArgValue> | null;
export declare function parseSdoc(source: string): SdocDocument;