asyncapi-viewer 2.0.0 → 2.1.0

package/dist/types/element.d.ts

@@ -0,0 +1,33 @@
+import { LitElement } from 'lit';
+import { type LoadResult } from './load/loader.js';
+import type { Document, Problem } from './model/types.js';
+import { type Options } from './options.js';
+/**
+ * <asyncapi-viewer src="..."> renders an AsyncAPI document.
+ *
+ * Options are read from the element's attributes (see options.schema.json) and watched with a
+ * MutationObserver, because each option has several accepted spellings and hand-written HTML
+ * lowercases camelCase names. The theme controller reflects the resolved mode as
+ * `resolved-theme` on the host. Derived colours (badge text, text-safe accents) are computed
+ * from the resolved accent at runtime and set as private custom properties on the root.
+ * Each finished load dispatches `asyncapi-load` or `asyncapi-error` (events.ts).
+ */
+export declare class AsyncAPIViewerElement extends LitElement {
+    #private;
+    static styles: import("lit").CSSResult[];
+    /** The validated options, re-read whenever an attribute changes. */
+    get options(): Options;
+    /** The outcome of the last load, for tests and tooling. */
+    get loadResult(): LoadResult | undefined;
+    /** Problems collected so far (reference loading and normalisation). */
+    get problems(): readonly Problem[];
+    /** The normalised model, once loaded. */
+    get model(): Document | undefined;
+    /** The element id used as the anchor prefix; generated when the tag has none. */
+    get anchorPrefix(): string;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected firstUpdated(): void;
+    protected updated(): void;
+    render(): import("lit-html").TemplateResult<1>;
+}

package/dist/types/events.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Public types for the element: the events it dispatches and the attributes it accepts.
+ *
+ * Both events bubble and cross shadow roots. They fire once per `src`, after the viewer has
+ * rendered the result, so a listener can already find the rendered sections. Rebuilding the model
+ * because a label option changed does not fire them again.
+ */
+import type { LoadError } from './load/loader.js';
+import type { Document, Problem } from './model/types.js';
+import type { AsyncAPIViewerElement } from './element.js';
+export interface AsyncAPILoadDetail {
+    /** The document URL, resolved against the page. */
+    url: string;
+    /** Exact `asyncapi` field, e.g. "3.0.0". */
+    specVersion: string;
+    specMajor: 2 | 3;
+    /** The normalised model the viewer renders. */
+    model: Document;
+    /** Reference and normalisation problems (the Problems panel); empty when there are none. */
+    problems: readonly Problem[];
+}
+export interface AsyncAPIErrorDetail {
+    /** The document URL, resolved against the page. */
+    url: string;
+    /** Why the document could not be shown: network, HTTP status, parse or version failure. */
+    error: LoadError;
+}
+/** `asyncapi-load`: the document loaded and rendered. */
+export type AsyncAPILoadEvent = CustomEvent<AsyncAPILoadDetail>;
+/** `asyncapi-error`: the document could not be loaded; the viewer shows the error in place. */
+export type AsyncAPIErrorEvent = CustomEvent<AsyncAPIErrorDetail>;
+/** Values the element reads as true or false (case-insensitive); an empty or bare attribute is true. */
+export type BooleanAttribute = boolean | '' | 'true' | 'false' | '1' | '0' | 'yes' | 'no' | 'on' | 'off';
+/**
+ * Every attribute of `<asyncapi-viewer>` in its kebab-case spelling, as written in HTML or JSX.
+ * Mirrors options.schema.json; a unit test keeps the two in step. Booleans are for frameworks
+ * that turn `true` into a bare attribute and `false` into none (React 19, Vue, Svelte, Lit).
+ */
+export interface AsyncAPIViewerAttributes {
+    /** The AsyncAPI document (JSON or YAML), as a path or URL relative to the page. Required. */
+    src?: string;
+    /** Element id; also prefixes every anchor inside the viewer. Generated when absent. */
+    id?: string;
+    /** Show the navigation column; a drawer behind a menu button on narrow containers. Default false. */
+    sidebar?: BooleanAttribute;
+    /** Show the Info section. Default true. */
+    info?: BooleanAttribute;
+    /** Show the Servers section and the server selector. Default true. */
+    servers?: BooleanAttribute;
+    /** Show the operations. Default true. */
+    operations?: BooleanAttribute;
+    /** Show the Messages section (component messages). Default true. */
+    messages?: BooleanAttribute;
+    /** Show the Schemas section (component schemas). Default true. */
+    schemas?: BooleanAttribute;
+    /** Show the load and validation problems panel. Default true. */
+    errors?: BooleanAttribute;
+    /** Show examples in the Messages section. Default false. */
+    'show-message-examples'?: BooleanAttribute;
+    /** Example panels start expanded; false starts them collapsed. Default true. */
+    'message-examples'?: BooleanAttribute;
+    /** Sidebar grouping for servers. Default byDefault. */
+    'show-servers'?: 'byDefault' | 'bySpecTags' | 'byServersTags';
+    /** Sidebar grouping for operations. Default byDefault. */
+    'show-operations'?: 'byDefault' | 'bySpecTags' | 'byOperationsTags';
+    /** AsyncAPI 3: label operations by channel address instead of title. Default false. */
+    'use-channel-address-as-identifier'?: BooleanAttribute;
+    /** Badge text for AsyncAPI 2 publish operations. Default PUB. */
+    'publish-label'?: string;
+    /** Badge text for AsyncAPI 2 subscribe operations. Default SUB. */
+    'subscribe-label'?: string;
+    /** Badge text for AsyncAPI 3 send operations. Default SEND. */
+    'send-label'?: string;
+    /** Badge text for AsyncAPI 3 receive operations. Default RECEIVE. */
+    'receive-label'?: string;
+    /** Badge text for AsyncAPI 3 send operations that carry a reply. Default REQUEST. */
+    'request-label'?: string;
+    /** Badge text for AsyncAPI 3 receive operations that carry a reply. Default REPLY. */
+    'reply-label'?: string;
+    /** JSON object; only `{"applyTraits": false}` changes anything. */
+    'parser-options'?: string;
+    /** @deprecated Accepted, warns once, does nothing. */
+    'schema-id'?: string;
+    /** auto follows the host page (Material scheme, html[data-theme], prefers-color-scheme). Default auto. */
+    theme?: 'auto' | 'light' | 'dark';
+    /** Show a light/dark toggle in the viewer header. Default false. */
+    'theme-toggle'?: BooleanAttribute;
+    /** Keep the Info, Servers, Messages and Schemas links visible while a sidebar search query is active. Default false. */
+    'search-keep-sections'?: BooleanAttribute;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'asyncapi-viewer': AsyncAPIViewerElement;
+    }
+    interface HTMLElementEventMap {
+        'asyncapi-load': AsyncAPILoadEvent;
+        'asyncapi-error': AsyncAPIErrorEvent;
+    }
+}

package/dist/types/index.d.ts

@@ -0,0 +1,12 @@
+export { AsyncAPIViewerElement } from './element.js';
+export type * from './events.js';
+export type * from './model/types.js';
+export { parseOptions, DEFAULTS, OPTION_SPECS, toAttributeName } from './options.js';
+export type { Options } from './options.js';
+export { loadDocument, parseText, resolveUrl } from './load/loader.js';
+export type { LoadResult, LoadError } from './load/loader.js';
+export { RefResolver, isRef, schemaNameOf } from './load/refs.js';
+export type { Resolved, Dereferenced, ResolveFailure } from './load/refs.js';
+export { normalize } from './model/normalize.js';
+export type { NormalizeInput } from './model/normalize.js';
+export { checkDocument } from './model/invariants.js';

package/dist/types/load/loader.d.ts

@@ -0,0 +1,46 @@
+export type LoadErrorKind = 'network' | 'http' | 'empty' | 'parse' | 'not-object' | 'unsupported';
+export interface LoadError {
+    kind: LoadErrorKind;
+    /** One sentence, no URL (the URL is beside it). */
+    message: string;
+    status?: number;
+}
+export interface LoadSuccess {
+    ok: true;
+    url: string;
+    /** The document exactly as served, for "Download spec". */
+    text: string;
+    format: 'json' | 'yaml';
+    /** The parsed root object. */
+    data: Record<string, unknown>;
+    /** Exact `asyncapi` field, e.g. "2.6.0". */
+    specVersion: string;
+    specMajor: 2 | 3;
+}
+export interface LoadFailure {
+    ok: false;
+    url: string;
+    error: LoadError;
+}
+export type LoadResult = LoadSuccess | LoadFailure;
+export type FetchLike = (url: string) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/** Resolve `src` against a base (normally `document.baseURI`); returns `src` unchanged if that fails. */
+export declare function resolveUrl(src: string, base: string): string;
+export declare function loadDocument(url: string, fetchImpl?: FetchLike): Promise<LoadResult>;
+/** JSON first, then YAML. Exported for tests and for future build-time validation. */
+export declare function parseText(text: string): {
+    format: 'json' | 'yaml';
+    data: Record<string, unknown>;
+} | {
+    error: LoadError;
+};
+export declare function detectVersion(data: Record<string, unknown>): {
+    specVersion: string;
+    specMajor: 2 | 3;
+} | {
+    error: LoadError;
+};

package/dist/types/load/refs.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `$ref` resolution.
+ *
+ * The normalisers are synchronous, so resolution happens in two steps: `preload()` walks the
+ * root document, fetches every external document it references (and theirs, recursively),
+ * each exactly once, and records what could not be loaded as problems. After that `resolve()`
+ * and `deref()` are synchronous lookups.
+ *
+ * A reference is `<url>#<json pointer>`. The url part is resolved against the document the
+ * reference appears in, so references inside an external file are relative to that file.
+ * Reference chains (a `$ref` pointing at another `$ref`) are followed with a cycle guard.
+ * Cycles in the schema graph itself are not an error here: the tree builder detects them by
+ * tracking resolved ids on its way down.
+ */
+import type { Problem } from '../model/types.js';
+import { type FetchLike } from './loader.js';
+export interface Resolved {
+    /** The target value with its own `$ref`s still in place. */
+    value: unknown;
+    /** Stable identity: `<absolute url>#<pointer>`. Two refs to the same target share an id. */
+    id: string;
+    /** The document the target lives in; nested references resolve against it. */
+    baseUrl: string;
+    /** The pointer within that document, e.g. "/components/schemas/Order". */
+    pointer: string;
+}
+export interface ResolveFailure {
+    error: string;
+}
+/** What `deref()` returns: like `Resolved`, but inline values have no id. */
+export interface Dereferenced {
+    value: unknown;
+    id: string | undefined;
+    baseUrl: string;
+    pointer: string;
+}
+export declare function isRef(value: unknown): value is {
+    $ref: string;
+};
+/** `#/components/schemas/Order` -> `Order`; undefined for anything else. */
+export declare function schemaNameOf(id: string): string | undefined;
+export declare class RefResolver {
+    #private;
+    readonly rootUrl: string;
+    constructor(rootUrl: string, rootDoc: Record<string, unknown>, fetchImpl?: FetchLike);
+    /** Fetch every external document reachable through `$ref`s. Returns load problems. */
+    preload(): Promise<Problem[]>;
+    /** Resolve one reference string as written at `baseUrl`. Synchronous; needs `preload()` first for external refs. */
+    resolve(ref: string, baseUrl: string): Resolved | ResolveFailure;
+    /**
+     * Follow `$ref` chains from a value until a non-reference is reached. Inline values come back
+     * unchanged with the caller's `baseUrl` and no id.
+     */
+    deref(value: unknown, baseUrl: string): Dereferenced | ResolveFailure;
+    /** Every document loaded so far, by absolute URL (the root first). */
+    get documents(): ReadonlyMap<string, Record<string, unknown>>;
+}
+/** Every `$ref` string in a document with the JSON pointer of the object that holds it. */
+export declare function collectRefs(doc: unknown): Array<[ref: string, where: string]>;
+export declare function walkPointer(doc: unknown, pointer: string): unknown;
+export declare function decodePointerSegment(segment: string): string;
+export declare function encodePointerSegment(segment: string): string;

package/dist/types/model/avro.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Avro schemas as SchemaNode trees, so Kafka documents get the same rows as JSON Schema.
+ *
+ * Mapping: record -> object (fields as children, `doc` as description, field `default`);
+ * a union with `null` marks the field optional and adds "null" to the types; a union of
+ * several non-null types becomes oneOf variants; array -> "[]" item; map -> "*" child;
+ * enum -> string with enum; fixed and bytes -> string · bytes; logical types become formats.
+ * Named types are registered when first seen so later references by name resolve; a
+ * reference back to an ancestor becomes a circular leaf.
+ */
+import type { SchemaNode } from './types.js';
+export declare function isAvroFormat(schemaFormat: string): boolean;
+/** Build a tree from an Avro schema; undefined when the value is not an Avro schema at all. */
+export declare function avroToNode(schema: unknown, name: string, isRoot: boolean): SchemaNode | undefined;

package/dist/types/model/context.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared state for one normalisation run: the resolver, the problems list, the label options,
+ * anchor allocation and the small helpers every normaliser needs.
+ */
+import { type RefResolver } from '../load/refs.js';
+import type { Binding, BindingScope, ExternalDocs, Problem, SectionId, SecurityRequirement, Tag } from './types.js';
+export interface Labels {
+    publish: string;
+    subscribe: string;
+    send: string;
+    receive: string;
+    request: string;
+    reply: string;
+}
+export interface NormalizeOptions {
+    labels: Labels;
+    useChannelAddressAsIdentifier: boolean;
+    applyTraits: boolean;
+}
+export declare const DEFAULT_NORMALIZE_OPTIONS: NormalizeOptions;
+export type Obj = Record<string, unknown>;
+export declare function isObj(value: unknown): value is Obj;
+export declare function str(value: unknown): string | undefined;
+/** A dereferenced object together with where it lives, for nested references. */
+export interface Located {
+    value: Obj;
+    baseUrl: string;
+    /** Resolved id when the value came through a `$ref`. */
+    id: string | undefined;
+}
+export declare class Context {
+    #private;
+    readonly resolver: RefResolver;
+    readonly options: NormalizeOptions;
+    readonly problems: Problem[];
+    constructor(resolver: RefResolver, options: NormalizeOptions);
+    problem(severity: Problem['severity'], message: string, where: string): void;
+    /**
+     * Dereference `value` (following `$ref` chains) and require an object. Anything else is
+     * recorded as a problem at `where` and yields undefined.
+     */
+    object(value: unknown, baseUrl: string, where: string): Located | undefined;
+    /** Iterate a map-shaped field (`servers`, `channels`, ...) dereferencing each entry. */
+    entries(map: unknown, baseUrl: string, where: string): Generator<[key: string, located: Located, where: string]>;
+    /** Iterate a list field dereferencing each entry. */
+    items(list: unknown, baseUrl: string, where: string): Generator<[located: Located, where: string]>;
+    /** A document-unique anchor for `id` within a section. */
+    anchor(section: SectionId, id: string): string;
+    tags(list: unknown, baseUrl: string, where: string): Tag[];
+    externalDocs(value: unknown, baseUrl: string, where: string): ExternalDocs | undefined;
+    /** `bindings: { kafka: { groupId: x, bindingVersion: y } }` -> one Binding per key. */
+    bindings(scope: BindingScope, value: unknown, baseUrl: string, where: string): Binding[];
+    /**
+     * Apply `traits` to an object: the object's own fields win, then earlier traits over later
+     * ones (the official parser's order). Keys a trait must not carry are dropped with a problem.
+     * Returns the object unchanged when `applyTraits` is off or there are no traits.
+     */
+    withTraits(value: Obj, baseUrl: string, where: string, forbidden: readonly string[]): Obj;
+    /** The last pointer segment of a resolved id: `#/servers/production` -> `production`. */
+    static keyOf(id: string | undefined): string | undefined;
+    static schemaName(id: string | undefined): string | undefined;
+}
+/** Deep merge where `over` wins; lists and scalars are replaced, objects merged key by key. */
+/**
+ * The facts of a security scheme object that a reader wants beside its name: where an API key
+ * goes, the HTTP scheme, the OpenID discovery URL and, for OAuth 2, every flow with its URLs and
+ * scopes. v2 flows list scopes under `scopes`, v3 under `availableScopes`; both are read.
+ */
+export declare function securitySchemeDetails(scheme: Obj): Pick<SecurityRequirement, 'facts' | 'openIdConnectUrl' | 'flows' | 'extensions'>;
+export declare function mergeObjects(base: Obj, over: Obj): Obj;
+/**
+ * Anchor slug for an id. Runs of separators collapse to one hyphen so an anchor never contains
+ * "--", the separator between element id, section and item in page anchors.
+ */
+export declare function slug(id: string): string;

package/dist/types/model/invariants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Structural rules every normalised Document must satisfy, whatever produced it.
+ * Used by the fixture tests now and by the normaliser tests and the coverage gate later.
+ * Returns human-readable violations; an empty array means the document is well formed.
+ */
+import type { Document } from './types.js';
+export declare function checkDocument(doc: Document): string[];

package/dist/types/model/normalize.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Entry point: turn a loaded document into the normalised model.
+ */
+import type { RefResolver } from '../load/refs.js';
+import { type NormalizeOptions } from './context.js';
+import type { Document, Problem } from './types.js';
+export interface NormalizeInput {
+    resolver: RefResolver;
+    data: Record<string, unknown>;
+    specVersion: string;
+    specMajor: 2 | 3;
+    /** Problems found earlier (reference preloading) to carry into the document. */
+    problems?: Problem[];
+    options?: Partial<NormalizeOptions>;
+}
+export declare function normalize(input: NormalizeInput): Document;

package/dist/types/model/schema.d.ts

@@ -0,0 +1,16 @@
+import { Context } from './context.js';
+import type { Schema } from './types.js';
+/** Formats we can render as a tree. Anything else becomes a RawSchema. */
+export declare function isTreeFormat(schemaFormat: string): boolean;
+export interface BuildInput {
+    /** The schema as written: a schema object, a `$ref`, a boolean, or a Multi Format Schema Object. */
+    raw: unknown;
+    baseUrl: string;
+    where: string;
+    /** Root name: "" for payload/headers, the key for components.schemas. */
+    name: string;
+    /** Applies when `raw` is a plain schema object without its own `schemaFormat`. */
+    defaultFormat: string;
+}
+/** Build a payload, headers or component schema. Handles the Multi Format Schema Object. */
+export declare function buildSchema(ctx: Context, input: BuildInput): Schema | undefined;