/**
 * A shared documentation-chrome renderer for the family's plugins.
 *
 * Every plugin hand-maintains the same "chrome" in many places: a multi-line badge/logo masthead byte-copied to the top of the README and every content doc, and an
 * ordered documentation index (each doc's title plus a one-line blurb) duplicated between the README's documentation section and the webUI's Support tab. Those copies
 * drift - a badge label here, a blurb there, an href form that differs per surface. This module collapses all of it into one per-plugin {@link DocChromeManifest} that a
 * plugin authors once (as a typed module or a static JSON file), so each surface becomes a pure projection of a single source of truth.
 *
 * The module exports pure string renderers - {@link renderMasthead}, {@link renderDocIndex}, {@link renderDevBadges}, {@link renderProjects} - and the marker constants
 * each surface embeds, plus the {@link parseDocChromeManifest} / {@link parseProjectEntries} validators. Like `featureOptions-docs.ts`, every function here is pure and
 * isomorphic: no `node:` imports, no `fs`, no `fetch`. Reading the target files, resolving a remote project list, and writing the spliced result back are the CLI's
 * concern; this module only ever renders already-resolved data. That keeps it browser-safe and trivially testable, though it is a tooling concern and is deliberately
 * NOT mirrored into `dist/ui/`.
 *
 * @module
 */
/**
 * Repository coordinates used to derive the GitHub blob URLs that navigation entries link to. The blob base is `https://github.com/{owner}/{name}/blob/{branch}`.
 *
 * @category Doc Chrome
 */
export interface RepoCoordinates {
    readonly branch: string;
    readonly name: string;
    readonly owner: string;
}
/**
 * A single shields-style badge: its alt text, its image URL, and the URL it links to. Stored as a full image URL rather than assembled from parts so the manifest stays
 * provider-agnostic - any badge service works, not just shields.io.
 *
 * @category Doc Chrome
 */
export interface Badge {
    readonly alt: string;
    readonly image: string;
    readonly link: string;
}
/**
 * The masthead: the centered logo, the H1 title, the ordered badge row, and the H2 tagline. Rendered identically into the README and every content doc. Text fields are
 * author-owned markup (the tagline may contain markdown links) and pass through verbatim.
 *
 * @category Doc Chrome
 */
export interface Masthead {
    readonly badges: readonly Badge[];
    readonly logo: {
        readonly alt: string;
        readonly href: string;
        readonly src: string;
    };
    readonly tagline: string;
    readonly title: string;
}
/**
 * One documentation-index entry. A discriminated union on `kind`: a `"doc"` entry points at a file under the plugin's `docs/` tree (and may opt out of the masthead via
 * `masthead: false`, as the changelog does), while a `"readme-anchor"` entry points at a section anchor within the README itself. The renderer derives the correct href
 * per surface from this one canonical shape, so the same entry can render as an in-README anchor on the README and as an absolute blob URL everywhere else.
 *
 * @category Doc Chrome
 */
export type DocEntry = {
    readonly anchor: string;
    readonly blurb: string;
    readonly kind: "readme-anchor";
    readonly title: string;
} | {
    readonly blurb: string;
    readonly file: string;
    readonly kind: "doc";
    readonly masthead?: boolean;
    readonly title: string;
};
/**
 * A named, ordered group of documentation entries (for example "Getting Started" or "Additional Topics"). Sections render in array order, and entries within a section
 * render in array order.
 *
 * @category Doc Chrome
 */
export interface NavSection {
    readonly entries: readonly DocEntry[];
    readonly title: string;
}
/**
 * One "other projects" entry for the webUI's project list. The rendered link text is `{title}: {blurb}`.
 *
 * @category Doc Chrome
 */
export interface ProjectEntry {
    readonly blurb: string;
    readonly href: string;
    readonly title: string;
}
/**
 * A manifest fragment whose data may be supplied inline (an array), read from a local file relative to the plugin root (`{ file }`), or fetched from a URL at stamp time
 * (`{ url }`). The CLI resolves these; the renderers only ever see the resolved inline array. The URL form is what lets a family-wide list (the project list) live in one
 * external file that every plugin's next build pulls from, without baking that list into this generic library.
 *
 * @category Doc Chrome
 */
export type ExternalSource<T> = readonly T[] | {
    readonly file: string;
} | {
    readonly url: string;
};
/**
 * The per-plugin documentation-chrome manifest - the single source of truth for a plugin's masthead, documentation index, dashboard badges, and project list. Authored
 * once per plugin (a typed TS module or a static JSON file) and consumed by the `prepare-chrome` CLI subcommand.
 *
 * @category Doc Chrome
 */
export interface DocChromeManifest {
    readonly devBadges?: readonly Badge[];
    readonly masthead: Masthead;
    readonly nav: readonly NavSection[];
    readonly projects?: ExternalSource<ProjectEntry>;
    readonly repo: RepoCoordinates;
    readonly surfaces?: {
        readonly readme?: string;
        readonly webui?: string;
    };
}
/**
 * The surface a documentation index is rendered for. `"readme"` and `"doc-footer"` both render markdown; `"webui"` renders HTML. The surface also selects href
 * derivation: `"readme"` uses in-README section anchors for `readme-anchor` entries, while `"doc-footer"` and `"webui"` use absolute blob URLs (an anchor entry viewed
 * from anywhere other than the README itself must resolve to the README's absolute URL). Only `"doc-footer"` omits the current document from its own list.
 *
 * @category Doc Chrome
 */
export type NavSurface = "doc-footer" | "readme" | "webui";
/**
 * The opening marker of the auto-generated masthead region. See {@link renderMasthead}. The text doubles as an in-document warning not to edit the region by hand.
 *
 * @category Doc Chrome
 */
export declare const MASTHEAD_BEGIN = "<!-- MASTHEAD:BEGIN - Auto-generated by homebridge-plugin-utils. Do not edit this region by hand. -->";
/**
 * The closing marker of the auto-generated masthead region. See {@link MASTHEAD_BEGIN}.
 *
 * @category Doc Chrome
 */
export declare const MASTHEAD_END = "<!-- MASTHEAD:END -->";
/**
 * The opening marker of the auto-generated documentation-index region, used in the README's documentation section, each content doc's footer, and the webUI's Support
 * tab. See {@link renderDocIndex}.
 *
 * @category Doc Chrome
 */
export declare const DOCUMENTATION_BEGIN = "<!-- DOCUMENTATION:BEGIN - Auto-generated by homebridge-plugin-utils. Do not edit this region by hand. -->";
/**
 * The closing marker of the auto-generated documentation-index region. See {@link DOCUMENTATION_BEGIN}.
 *
 * @category Doc Chrome
 */
export declare const DOCUMENTATION_END = "<!-- DOCUMENTATION:END -->";
/**
 * The opening marker of the auto-generated development-dashboard badge region (README only). See {@link renderDevBadges}.
 *
 * @category Doc Chrome
 */
export declare const DEV_BADGES_BEGIN = "<!-- DEV BADGES:BEGIN - Auto-generated by homebridge-plugin-utils. Do not edit this region by hand. -->";
/**
 * The closing marker of the auto-generated development-dashboard badge region. See {@link DEV_BADGES_BEGIN}.
 *
 * @category Doc Chrome
 */
export declare const DEV_BADGES_END = "<!-- DEV BADGES:END -->";
/**
 * The opening marker of the auto-generated project-list region (webUI only). See {@link renderProjects}.
 *
 * @category Doc Chrome
 */
export declare const PROJECTS_BEGIN = "<!-- PROJECTS:BEGIN - Auto-generated by homebridge-plugin-utils. Do not edit this region by hand. -->";
/**
 * The closing marker of the auto-generated project-list region. See {@link PROJECTS_BEGIN}.
 *
 * @category Doc Chrome
 */
export declare const PROJECTS_END = "<!-- PROJECTS:END -->";
/**
 * Render the masthead - the centered logo, the H1 title, the ordered badge row, and the H2 tagline - as the markdown/HTML block a plugin embeds at the top of its README
 * and every content doc. The block is identical across those surfaces, so a single manifest drives all of them and the hand-copied mastheads collapse to one.
 *
 * @param manifest - The documentation-chrome manifest.
 *
 * @returns The rendered masthead block.
 *
 * @category Doc Chrome
 */
export declare function renderMasthead(manifest: DocChromeManifest): string;
/**
 * Render the development-dashboard badges - the README-only badge row (license, build status, dependencies, and the like) that sits apart from the masthead. Returns an
 * empty string when the manifest declares no dashboard badges.
 *
 * @param manifest - The documentation-chrome manifest.
 *
 * @returns The rendered badge rows, one badge per line.
 *
 * @category Doc Chrome
 */
export declare function renderDevBadges(manifest: DocChromeManifest): string;
/**
 * Render the documentation index for a surface. On the markdown surfaces (`"readme"`, `"doc-footer"`) the output is one bullet per section with a nested bullet per
 * entry; on `"webui"` it is one `<h5>` heading and `<ul>` per section. Href derivation follows the surface: in-README anchors on `"readme"`, absolute blob URLs
 * elsewhere. A `"doc-footer"` render omits the current document (via `currentFile`) and drops any section left empty by that omission, so a doc's own footer never links
 * back to itself.
 *
 * @param input
 * @param input.currentFile - The doc file being rendered into, relative to the plugin root. Only consulted for the `"doc-footer"` surface, to omit the self-link.
 * @param input.manifest    - The documentation-chrome manifest.
 * @param input.surface     - The surface to render for.
 *
 * @returns The rendered documentation index.
 *
 * @category Doc Chrome
 */
export declare function renderDocIndex({ currentFile, manifest, surface }: {
    currentFile?: string;
    manifest: DocChromeManifest;
    surface: NavSurface;
}): string;
/**
 * Render the webUI project list - the "other projects" links - as an HTML `<ul>`. The CLI resolves the manifest's project source (inline, local file, or remote URL) to
 * this array before calling; the renderer never performs I/O. Entries are rendered in alphabetical order by title, so the list reads predictably no matter what order the
 * source - often a shared, remotely-fetched file every plugin points at - happens to hold. Each entry's link text is `{title}: {blurb}`.
 *
 * @param projects - The resolved project entries. Their order is not significant; the renderer sorts them by title.
 *
 * @returns The rendered project list.
 *
 * @category Doc Chrome
 */
export declare function renderProjects(projects: readonly ProjectEntry[]): string;
/**
 * Validate a loaded value and return it typed as a well-formed {@link DocChromeManifest}, failing fast with a framed diagnostic that names the manifest source and the
 * offending field rather than surfacing an opaque error deep inside a renderer or a bare `resolve()` type error in the CLI. Validates every field the renderer or the
 * CLI consumes - `masthead`, `nav`, `repo`, and the optional `devBadges` and `surfaces`. The project source is validated separately at resolution time, since it may be
 * a remote reference rather than inline data.
 *
 * @param value  - The loaded manifest value, untrusted until validated.
 * @param source - The manifest's path or module specifier, for diagnostics.
 *
 * @returns The same value, now typed as a validated {@link DocChromeManifest}.
 *
 * @category Doc Chrome
 */
export declare function parseDocChromeManifest(value: unknown, source: string): DocChromeManifest;
/**
 * Validate a resolved project source and return it typed as an array of {@link ProjectEntry}. The CLI calls this after resolving the manifest's project source - which
 * may be inline data, a local file, or a remote URL - so a malformed external list fails fast with a framed diagnostic naming the source rather than rendering broken
 * markup.
 *
 * @param value  - The resolved project value, untrusted until validated.
 * @param source - The project source (a path or URL) for diagnostics.
 *
 * @returns The same value, now typed as a validated array of {@link ProjectEntry}.
 *
 * @category Doc Chrome
 */
export declare function parseProjectEntries(value: unknown, source: string): readonly ProjectEntry[];
//# sourceMappingURL=docChrome.d.ts.map