puredocs_v2 1.0.0

package/dist/core/auth-storage.d.ts

@@ -0,0 +1,3 @@
+import type { AuthState, SecurityScheme } from './types';
+export declare function areAuthStatesEqual(a: AuthState, b: AuthState): boolean;
+export declare function reconcileAuthWithSecuritySchemes(auth: AuthState, securitySchemes: Record<string, SecurityScheme>): AuthState;

package/dist/core/effects.d.ts

@@ -0,0 +1,33 @@
+import type { PortalState } from './types';
+type EffectHandler = (state: PortalState) => void;
+type CleanupFn = () => void;
+/**
+ * Page-scoped reactive effects manager.
+ *
+ * Each page component registers its own effects at render time via `useEffects()`.
+ * When state changes (env / auth) without a route change, `notifyEffects()` runs
+ * all registered handlers so every component can update itself.
+ * On route change, `disposeEffects()` tears everything down cleanly.
+ *
+ * This replaces the monolithic `updateEnvironmentState` in app.ts — each component
+ * now owns its reactive behaviour.
+ */
+declare class Effects {
+    private handlers;
+    private cleanupFns;
+    /** Register a named reactive handler that runs on every state change */
+    on(key: string, handler: EffectHandler): void;
+    /** Register a cleanup callback (runs on dispose) */
+    onCleanup(fn: CleanupFn): void;
+    /** Run all registered handlers with current state */
+    notify(state: PortalState): void;
+    /** Dispose: run cleanups and clear all handlers */
+    dispose(): void;
+}
+/** Get the current page effects instance (creates one if needed) */
+export declare function useEffects(): Effects;
+/** Notify all page effects of a state change (env / auth) */
+export declare function notifyEffects(state: PortalState): void;
+/** Dispose current effects — call on route change / unmount */
+export declare function disposeEffects(): void;
+export {};

package/dist/core/parser.d.ts

@@ -0,0 +1,7 @@
+import type { ParsedSpec, SchemaObject } from './types';
+/** Parse and normalize an OpenAPI 3.x spec */
+export declare function parseSpec(raw: Record<string, unknown>): ParsedSpec;
+/** Generate a sample value from a schema when no example is provided */
+export declare function generateExample(schema: SchemaObject | undefined): unknown;
+/** Load spec from URL (JSON or YAML) */
+export declare function loadSpec(url: string): Promise<Record<string, unknown>>;

package/dist/core/persistence.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Persist portal state (env, baseUrl, auth) to localStorage
+ * so values survive page refresh.
+ */
+import type { PortalEnvironment, AuthState } from './types';
+export interface PersistedState {
+    activeEnvironment: string;
+    environments: PortalEnvironment[];
+    auth: AuthState;
+}
+export declare function loadPersisted(): PersistedState | null;
+export declare function savePersisted(data: PersistedState): void;

package/dist/core/router.d.ts

@@ -0,0 +1,40 @@
+import type { RouteInfo } from './types';
+/** Initialize the hash-based router */
+export declare function initRouter(base?: string): void;
+/** Remove all router event listeners */
+export declare function destroyRouter(): void;
+/** Push a new hash path and trigger a route change */
+export declare function navigate(path: string): void;
+/**
+ * Build a human-readable URL from a RouteInfo object.
+ *
+ * URL patterns:
+ *   #/                             → Overview
+ *   #/{tag}                        → Tag page
+ *   #/{tag}/{method}/{apiPath}     → Endpoint
+ *   #/schemas/{name}               → Schema
+ *   #/webhooks/{name}              → Webhook
+ *   #/guides/{path}                → Guide
+ *
+ * Examples:
+ *   #/users                        → "Users" tag page
+ *   #/users/get/users/{id}         → GET /users/{id} in "Users" tag
+ *   #/pets/post/pets               → POST /pets in "Pets" tag
+ *   #/schemas/UserResponse         → Schema "UserResponse"
+ */
+export declare function buildPath(route: RouteInfo): string;
+/**
+ * Parse a raw hash path into a RouteInfo object.
+ *
+ * Handles URL-encoded segments, normalizes slashes,
+ * and strips query strings.
+ */
+export declare function parsePath(rawPath: string): RouteInfo;
+/**
+ * Convert a tag name to a URL-friendly slug.
+ *
+ * "User Management" → "user-management"
+ * "Pets"            → "pets"
+ * "auth/v2"         → "auth-v2"
+ */
+export declare function slugifyTag(tag: string): string;

package/dist/core/search.d.ts

@@ -0,0 +1,5 @@
+import type { ParsedSpec, SearchEntry } from './types';
+/** Build search index from parsed spec */
+export declare function buildSearchIndex(spec: ParsedSpec): void;
+/** Search the index with a query string */
+export declare function search(query: string, limit?: number): SearchEntry[];

package/dist/core/security.d.ts

@@ -0,0 +1,16 @@
+import type { OperationSecurityInfo, SecurityRequirement, SecurityScheme } from './types';
+export interface OperationAuthResolved {
+    headers: Record<string, string>;
+    query: Record<string, string>;
+    cookies: Record<string, string>;
+    matchedSchemeNames: string[];
+}
+export declare function normalizeSecurityRequirements(raw: unknown): SecurityRequirement[] | undefined;
+export declare function resolveOperationSecurityInfo(requirements: SecurityRequirement[] | undefined, securitySchemes: Record<string, SecurityScheme>, explicitlyNoAuth: boolean): OperationSecurityInfo;
+export declare function hasOperationAuth(info: OperationSecurityInfo | undefined): boolean;
+export declare function getSecuritySchemeBadge(scheme: SecurityScheme | undefined): string;
+export declare function getOperationSecurityBadges(info: OperationSecurityInfo | undefined): string[];
+export declare function formatOperationAuthBadge(info: OperationSecurityInfo | undefined): string | null;
+export declare function formatOperationAuthTitle(info: OperationSecurityInfo | undefined): string;
+export declare function resolveOperationAuth(info: OperationSecurityInfo | undefined, configuredSchemes: Record<string, string>, activeScheme: string, fallbackToken: string): OperationAuthResolved;
+export declare function getOperationAuthHeaderPlaceholders(info: OperationSecurityInfo | undefined): Record<string, string>;

package/dist/core/state.d.ts

@@ -0,0 +1,24 @@
+import type { PortalState, AuthState, TryItState, RouteInfo } from './types';
+type Listener = (state: PortalState) => void;
+type PartialUpdate = Partial<PortalState>;
+/** Simple reactive state store */
+declare class Store {
+    private state;
+    private listeners;
+    constructor();
+    private defaultState;
+    get(): PortalState;
+    set(update: PartialUpdate): void;
+    setAuth(update: Partial<AuthState>): void;
+    /** Update a specific scheme value and sync token if it's the active scheme */
+    setSchemeValue(schemeName: string, value: string): void;
+    setTryIt(update: Partial<TryItState> | null): void;
+    setRoute(route: RouteInfo): void;
+    /** Switch active environment */
+    setActiveEnvironment(name: string): void;
+    subscribe(fn: Listener): () => void;
+    private notify;
+    reset(): void;
+}
+export declare const store: Store;
+export {};

package/dist/core/theme.d.ts

@@ -0,0 +1,9 @@
+export interface ThemeConfig {
+    primaryColor?: string;
+}
+/** Theme class switching only and optional config overrides */
+export declare function applyTheme(root: HTMLElement, themeMode: 'light' | 'dark', config?: ThemeConfig): void;
+/** Toggle between light and dark theme */
+export declare function toggleTheme(): void;
+/** Detect initial theme */
+export declare function detectTheme(preference?: 'light' | 'dark' | 'auto'): 'light' | 'dark';

package/dist/core/types.d.ts

@@ -0,0 +1,291 @@
+export interface PortalConfig {
+    /** CSS selector or HTMLElement to mount into */
+    mount: string | HTMLElement;
+    /** URL to fetch the OpenAPI spec from */
+    specUrl?: string;
+    /** Inline OpenAPI spec object */
+    spec?: Record<string, unknown>;
+    /** Portal title override */
+    title?: string;
+    /** Initial theme */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Primary accent color (hex) */
+    primaryColor?: string;
+    /** Hide Try It console */
+    hideTryIt?: boolean;
+    /** Hide deprecated endpoints */
+    hideDeprecated?: boolean;
+    /** Hide schema viewer */
+    hideSchemas?: boolean;
+    /** Language */
+    locale?: 'en' | 'ru';
+    /** Plugin hooks */
+    plugins?: PortalPlugin[];
+}
+/** Zero-boilerplate startup config: auto-create mount and optional CSS link injection */
+export interface PortalBootstrapConfig extends Omit<PortalConfig, 'mount'> {
+    /** Existing mount selector/element. If omitted, container is auto-created in body. */
+    mount?: string | HTMLElement;
+    /** Auto-created mount id when mount is omitted. Default: "puredocs". */
+    mountId?: string;
+    /** Apply minimal full-page layout styles. Default: true. */
+    fullPage?: boolean;
+    /** Optional stylesheet URL to inject once (useful for plain JS/UMD). */
+    cssHref?: string;
+}
+export interface PortalEnvironment {
+    name: string;
+    baseUrl: string;
+    variables?: Record<string, string>;
+    bearerToken?: string;
+}
+export interface PortalPlugin {
+    name: string;
+    init?: (portal: PortalApi) => void;
+    destroy?: () => void;
+}
+export interface PortalApi {
+    getState: () => PortalState;
+    subscribe: (fn: (state: PortalState) => void) => () => void;
+    setToken: (token: string) => void;
+    setEnvironment: (name: string) => void;
+    navigate: (path: string) => void;
+}
+export interface PortalState {
+    spec: ParsedSpec | null;
+    loading: boolean;
+    error: string | null;
+    route: RouteInfo;
+    theme: 'light' | 'dark';
+    sidebarOpen: boolean;
+    searchOpen: boolean;
+    activeEnvironment: string;
+    environments: PortalEnvironment[];
+    /** Canonical env list from config/spec — baseUrl reset to this when switching env */
+    initialEnvironments: PortalEnvironment[];
+    auth: AuthState;
+    tryItState: TryItState | null;
+}
+export interface AuthState {
+    /** Per-scheme configured values: schemeName -> value (token/apiKey/etc.) */
+    schemes: Record<string, string>;
+    /** Currently active scheme name */
+    activeScheme: string;
+    /** Derived token for requests (from active scheme) */
+    token: string;
+    locked: boolean;
+    source: 'manual' | 'auto-body' | 'auto-header';
+}
+export interface TryItState {
+    operationId: string;
+    response: TryItResponse | null;
+    loading: boolean;
+}
+export interface TryItResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: string;
+    duration: number;
+    size: number;
+}
+export interface RouteInfo {
+    type: 'overview' | 'endpoint' | 'schema' | 'guide' | 'tag' | 'webhook';
+    tag?: string;
+    method?: string;
+    path?: string;
+    operationId?: string;
+    schemaName?: string;
+    guidePath?: string;
+    webhookName?: string;
+}
+export interface ParsedSpec {
+    raw: Record<string, unknown>;
+    info: SpecInfo;
+    servers: SpecServer[];
+    tags: SpecTag[];
+    operations: SpecOperation[];
+    schemas: Record<string, SchemaObject>;
+    securitySchemes: Record<string, SecurityScheme>;
+    webhooks: SpecWebhook[];
+}
+export interface SpecInfo {
+    title: string;
+    description?: string;
+    version: string;
+    contact?: {
+        name?: string;
+        email?: string;
+        url?: string;
+    };
+    license?: {
+        name: string;
+        url?: string;
+    };
+}
+export interface SpecServer {
+    url: string;
+    description?: string;
+    variables?: Record<string, {
+        default: string;
+        enum?: string[];
+        description?: string;
+    }>;
+}
+export interface SpecTag {
+    name: string;
+    description?: string;
+    operations: SpecOperation[];
+}
+export interface SpecOperation {
+    operationId: string;
+    method: string;
+    path: string;
+    summary?: string;
+    description?: string;
+    tags: string[];
+    deprecated?: boolean;
+    security?: SecurityRequirement[];
+    resolvedSecurity?: OperationSecurityInfo;
+    parameters: SpecParameter[];
+    requestBody?: SpecRequestBody;
+    responses: Record<string, SpecResponse>;
+    callbacks?: SpecCallback[];
+}
+export interface SpecWebhook {
+    /** Key from the webhooks object */
+    name: string;
+    method: string;
+    /** URL template (usually runtime expression) */
+    path: string;
+    summary?: string;
+    description?: string;
+    security?: SecurityRequirement[];
+    resolvedSecurity?: OperationSecurityInfo;
+    parameters: SpecParameter[];
+    requestBody?: SpecRequestBody;
+    responses: Record<string, SpecResponse>;
+}
+export interface SpecCallback {
+    /** Key from the callbacks object */
+    name: string;
+    operations: SpecOperation[];
+}
+export interface SpecParameter {
+    name: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+    required?: boolean;
+    description?: string;
+    schema?: SchemaObject;
+    example?: unknown;
+    examples?: Record<string, SpecExample>;
+    deprecated?: boolean;
+}
+export interface SpecRequestBody {
+    description?: string;
+    required?: boolean;
+    content: Record<string, SpecMediaType>;
+}
+export interface SpecMediaType {
+    schema?: SchemaObject;
+    example?: unknown;
+    examples?: Record<string, SpecExample>;
+}
+export interface SpecResponseHeader {
+    description?: string;
+    required?: boolean;
+    schema?: SchemaObject;
+    example?: unknown;
+    deprecated?: boolean;
+}
+export interface SpecResponse {
+    statusCode: string;
+    description?: string;
+    headers?: Record<string, SpecResponseHeader>;
+    content?: Record<string, SpecMediaType>;
+}
+export interface SpecExample {
+    summary?: string;
+    description?: string;
+    value: unknown;
+}
+export interface SecurityScheme {
+    type: string;
+    scheme?: string;
+    bearerFormat?: string;
+    description?: string;
+    in?: string;
+    name?: string;
+    openIdConnectUrl?: string;
+    flows?: Record<string, SecurityOAuthFlow>;
+}
+export interface SecurityOAuthFlow {
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    refreshUrl?: string;
+    scopes?: Record<string, string>;
+}
+export type SecurityRequirement = Record<string, string[]>;
+export interface ResolvedSecuritySchemeRequirement {
+    schemeName: string;
+    scopes: string[];
+    scheme?: SecurityScheme;
+}
+export interface OperationSecurityInfo {
+    explicitlyNoAuth: boolean;
+    requirements: ResolvedSecuritySchemeRequirement[][];
+}
+export interface SchemaObject {
+    type?: string;
+    format?: string;
+    title?: string;
+    description?: string;
+    default?: unknown;
+    example?: unknown;
+    examples?: unknown[];
+    enum?: unknown[];
+    const?: unknown;
+    nullable?: boolean;
+    deprecated?: boolean;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    required?: string[];
+    properties?: Record<string, SchemaObject>;
+    additionalProperties?: boolean | SchemaObject;
+    items?: SchemaObject;
+    allOf?: SchemaObject[];
+    oneOf?: SchemaObject[];
+    anyOf?: SchemaObject[];
+    discriminator?: {
+        propertyName: string;
+        mapping?: Record<string, string>;
+    };
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    $ref?: string;
+    [key: string]: unknown;
+}
+export interface SearchEntry {
+    type: 'operation' | 'schema' | 'tag' | 'webhook';
+    title: string;
+    subtitle?: string;
+    method?: string;
+    requiresAuth?: boolean;
+    authBadge?: string;
+    authTitle?: string;
+    resolvedSecurity?: OperationSecurityInfo;
+    path?: string;
+    tag?: string;
+    operationId?: string;
+    schemaName?: string;
+    webhookName?: string;
+    keywords: string;
+}
+export type UiBadgeSize = 's' | 'm' | 'l';
+export type UiBadgeKind = 'method' | 'status' | 'webhook' | 'required' | 'chip';

package/dist/core/validation.d.ts

@@ -0,0 +1,17 @@
+import type { SchemaObject, SpecOperation, SpecParameter } from './types';
+export interface ValidationError {
+    field: string;
+    message: string;
+    /** 'param' | 'body' */
+    kind: 'param' | 'body';
+}
+export interface ValidationResult {
+    valid: boolean;
+    message?: string;
+}
+/** Validate a single parameter value against its schema */
+export declare function validateParam(value: string, param: SpecParameter): ValidationResult;
+/** Validate the request body string */
+export declare function validateBody(bodyStr: string, contentType: string, schema?: SchemaObject, required?: boolean): ValidationResult;
+/** Validate all fields in a Try It form. Returns array of errors (empty = valid). */
+export declare function validateAll(container: HTMLElement, operation: SpecOperation): ValidationError[];

package/dist/helpers/debounce.d.ts

@@ -0,0 +1 @@
+export declare function debounce<T extends (...args: unknown[]) => void>(fn: T, ms: number): T;

package/dist/helpers/schema-utils.d.ts

@@ -0,0 +1,2 @@
+import type { SchemaObject } from '../core/types';
+export declare function getSchemaTypeLabel(schema: SchemaObject): string;

package/dist/helpers/text.d.ts

@@ -0,0 +1,2 @@
+export declare function looksLikeJson(str: string): boolean;
+export declare function escapeHtml(str: string): string;

package/dist/helpers/validation-ui.d.ts

@@ -0,0 +1,4 @@
+import type { ValidationError } from '../core/validation';
+export declare function clearValidationErrors(container: HTMLElement): void;
+export declare function showValidationErrors(container: HTMLElement, errors: ValidationError[]): void;
+export declare function createErrorPlaceholder(field: string): HTMLElement;

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import './styles/index.css';
+import type { PortalConfig, PortalApi, PortalState, PortalBootstrapConfig } from './core/types';
+/** Mount the portal into the DOM */
+declare function mount(config: PortalConfig): Promise<PortalApi>;
+/** Universal zero-boilerplate startup for JS consumers */
+declare function bootstrap(config: PortalBootstrapConfig): Promise<PortalApi>;
+/** Unmount portal and cleanup */
+declare function unmount(): void;
+export declare class PureDocsElement extends HTMLElement {
+    private static activeElement;
+    private api;
+    private reloadTimer;
+    static get observedAttributes(): string[];
+    connectedCallback(): Promise<void>;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    reload(): Promise<void>;
+    getState(): PortalState | null;
+    subscribe(fn: (state: PortalState) => void): () => void;
+    navigate(path: string): void;
+    setToken(token: string): void;
+    setEnvironment(name: string): void;
+    private mountFromAttributes;
+    private parseConfig;
+    private renderSingletonError;
+}
+export declare const PureDocs: {
+    mount: typeof mount;
+    bootstrap: typeof bootstrap;
+    unmount: typeof unmount;
+    version: string;
+};
+export type { PortalConfig, PortalBootstrapConfig, PortalApi, PortalState } from './core/types';
+export default PureDocs;

package/dist/lib/dom.d.ts

@@ -0,0 +1,17 @@
+type Attrs = Record<string, string | boolean | number | EventListener | undefined>;
+type Child = HTMLElement | SVGElement | string | null | undefined | false;
+/** Create an HTML element with attributes and children */
+export declare function h(tag: string, attrs?: Attrs | null, ...children: Child[]): HTMLElement;
+/** Clear all children of an element */
+export declare function clear(el: HTMLElement): void;
+/** Replace all children of a container */
+export declare function render(container: HTMLElement, ...children: Child[]): void;
+/** Escape HTML to prevent XSS */
+export declare function escapeHtml(str: string): string;
+/** Copy text to clipboard */
+export declare function copyToClipboard(text: string): Promise<boolean>;
+/** Format bytes to human readable */
+export declare function formatBytes(bytes: number): string;
+/** Format duration in ms to human readable */
+export declare function formatDuration(ms: number): string;
+export {};

package/dist/lib/highlight.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Custom regex-based syntax highlighter — zero dependencies.
+ * Supports: JSON, JavaScript, Bash/curl, Go, Python, Rust.
+ * ~90 lines TS → ~1.4 KB min → ~0.6 KB gzip (vs ~18 KB for highlight.js).
+ */
+import { looksLikeJson } from '../helpers/text';
+export declare function highlightCode(code: string, language: string): string;
+export { looksLikeJson };

package/dist/lib/icons.d.ts

@@ -0,0 +1,24 @@
+/** SVG icon set — clean, consistent 20x20 Lucide-inspired icons */
+export declare const icons: {
+    readonly search: string;
+    readonly close: string;
+    readonly plus: string;
+    readonly chevronDown: string;
+    readonly chevronRight: string;
+    readonly chevronLeft: string;
+    readonly menu: string;
+    readonly sun: string;
+    readonly moon: string;
+    readonly copy: string;
+    readonly check: string;
+    /** Closed padlock — requires auth (red) */
+    readonly lock: string;
+    /** Open padlock — auth configured (green) */
+    readonly unlock: string;
+    readonly send: string;
+    readonly key: string;
+    readonly globe: string;
+    readonly server: string;
+    readonly warning: string;
+    readonly settings: string;
+};