@sneat/structured-data 0.0.0-stage → 0.27.30

package/types/sneat-structured-data.d.ts

@@ -0,0 +1,327 @@
+import * as i0 from '@angular/core';
+import { OnChanges, AfterViewChecked, EventEmitter, SimpleChanges } from '@angular/core';
+
+/** Public, transport-independent contract for @sneat/structured-data. */
+type StructuredFormat = 'json' | 'yaml' | 'hcl';
+/** Offsets and columns are UTF-16 code units; lines and columns are zero-based. */
+interface SourcePosition {
+    readonly line: number;
+    readonly column: number;
+}
+/** Half-open range into the exact, unchanged sourceText of a document. */
+interface SourceRange {
+    readonly startOffset: number;
+    readonly endOffset: number;
+    readonly start: SourcePosition;
+    readonly end: SourcePosition;
+}
+interface StructuredNull {
+    readonly kind: 'null';
+    readonly range?: SourceRange;
+}
+interface StructuredBoolean {
+    readonly kind: 'boolean';
+    readonly value: boolean;
+    readonly range?: SourceRange;
+}
+interface StructuredNumber {
+    readonly kind: 'number';
+    /** Exact numeric lexeme; the renderer never displays a rounded JS number. */
+    readonly sourceText: string;
+    /** Only supplied when conversion to a JS number is finite and lossless. */
+    readonly value?: number;
+    readonly range?: SourceRange;
+}
+interface StructuredString {
+    readonly kind: 'string';
+    readonly value: string;
+    readonly range?: SourceRange;
+}
+/** Never evaluate or silently coerce an HCL expression into a string. */
+interface StructuredExpression {
+    readonly kind: 'expression';
+    readonly sourceText: string;
+    readonly range: SourceRange;
+}
+interface StructuredArray {
+    readonly kind: 'array';
+    readonly items: readonly StructuredValue[];
+    readonly range?: SourceRange;
+}
+interface StructuredObjectEntry {
+    readonly key: string;
+    readonly value: StructuredValue;
+    readonly range?: SourceRange;
+}
+interface StructuredObject {
+    readonly kind: 'object';
+    readonly entries: readonly StructuredObjectEntry[];
+    readonly range?: SourceRange;
+}
+type StructuredValue = StructuredNull | StructuredBoolean | StructuredNumber | StructuredString | StructuredExpression | StructuredArray | StructuredObject;
+interface HclAttribute {
+    readonly kind: 'hcl-attribute';
+    readonly name: string;
+    readonly value: StructuredValue;
+    readonly range: SourceRange;
+}
+interface HclBlock {
+    readonly kind: 'hcl-block';
+    readonly blockType: string;
+    readonly labels: readonly string[];
+    readonly body: HclBody;
+    readonly range: SourceRange;
+}
+/** Members retain exact source order, including repeated blocks and labels. */
+interface HclBody {
+    readonly kind: 'hcl-body';
+    readonly members: readonly (HclAttribute | HclBlock)[];
+    readonly range: SourceRange;
+}
+type StructuredNode = StructuredValue | HclBody | HclBlock | HclAttribute;
+interface StructuredDocument {
+    readonly format: StructuredFormat;
+    readonly root: StructuredValue | HclBody;
+    /** The exact original text. Parsing never rewrites this source snapshot. */
+    readonly sourceText: string;
+}
+type StructuredDiagnosticCode = 'invalid_syntax' | 'unsupported_format' | 'unsupported_construct' | 'invalid_config' | 'limit_exceeded' | 'parser_unavailable';
+interface StructuredDiagnostic {
+    readonly code: StructuredDiagnosticCode;
+    readonly message: string;
+    readonly severity: 'error' | 'warning';
+    readonly range?: SourceRange;
+    readonly source?: string;
+}
+interface StructuredLimits {
+    readonly maxSourceBytes?: number;
+    readonly maxNodes?: number;
+    readonly maxDepth?: number;
+    readonly maxRows?: number;
+    readonly maxConfigBytes?: number;
+    readonly maxRules?: number;
+    readonly maxSections?: number;
+    readonly maxSelectorLength?: number;
+    readonly maxSelectorDepth?: number;
+    readonly maxYamlAliases?: number;
+    readonly timeoutMs?: number;
+}
+type ParseResult = {
+    readonly ok: true;
+    readonly document: StructuredDocument;
+    readonly diagnostics: readonly StructuredDiagnostic[];
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly StructuredDiagnostic[];
+};
+type ScalarListLayout = 'inline' | 'list';
+type CollectionPresentation = 'list' | 'accordion';
+type InitialExpansion = 'first' | 'all' | 'none';
+interface ViewTitle {
+    readonly label: string;
+    readonly path: string;
+}
+interface ViewField {
+    readonly label: string;
+    readonly path: string;
+    readonly scalarListLayout?: ScalarListLayout;
+}
+interface ViewColumn {
+    readonly label: string;
+    readonly path: string;
+}
+interface ViewEntryLayout {
+    /** $key for dictionary entries; $label/N for HCL block labels. */
+    readonly heading: string;
+    readonly sections?: readonly ViewSection[];
+}
+interface ViewSectionBase {
+    readonly id: string;
+    readonly title: string;
+    /** Relative JSON Pointer, or empty string for the current value. */
+    readonly path: string;
+}
+interface FieldsSection extends ViewSectionBase {
+    readonly kind: 'fields';
+    readonly fields: readonly ViewField[];
+}
+interface ValueSection extends ViewSectionBase {
+    readonly kind: 'value';
+    readonly scalarListLayout?: ScalarListLayout;
+}
+interface EntriesSection extends ViewSectionBase {
+    readonly kind: 'entries';
+    readonly presentation?: CollectionPresentation;
+    readonly allowLayoutSwitch?: boolean;
+    readonly initiallyExpanded?: InitialExpansion;
+    readonly entry?: ViewEntryLayout;
+}
+interface TableSection extends ViewSectionBase {
+    readonly kind: 'table';
+    readonly rows: 'dictionary' | 'list' | 'blocks';
+    readonly blockType?: string;
+    readonly columns: readonly ViewColumn[];
+}
+interface BlocksSection extends ViewSectionBase {
+    readonly kind: 'blocks';
+    readonly blockType: string;
+    readonly presentation?: CollectionPresentation;
+    readonly allowLayoutSwitch?: boolean;
+    readonly initiallyExpanded?: InitialExpansion;
+    readonly entry?: ViewEntryLayout;
+}
+type ViewSection = FieldsSection | ValueSection | EntriesSection | TableSection | BlocksSection;
+interface ViewRule {
+    readonly id: string;
+    readonly match: string;
+    readonly parser: StructuredFormat;
+    readonly title?: ViewTitle;
+    readonly sections?: readonly ViewSection[];
+}
+interface StructuredViewConfig {
+    readonly version: 1;
+    readonly rules: readonly ViewRule[];
+}
+/** Host supplies these from one pinned revision, root first and nearest last. */
+interface OrderedViewConfigDocument {
+    readonly sourcePath: string;
+    readonly config: unknown;
+}
+type ValidationResult = {
+    readonly ok: true;
+    readonly config: StructuredViewConfig;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly StructuredDiagnostic[];
+};
+type ResolutionResult = {
+    readonly status: 'matched';
+    readonly parser: StructuredFormat;
+    readonly view: ViewRule;
+} | {
+    readonly status: 'generic';
+    readonly parser: StructuredFormat;
+} | {
+    readonly status: 'unsupported';
+    readonly diagnostics: readonly StructuredDiagnostic[];
+} | {
+    readonly status: 'error';
+    readonly diagnostics: readonly StructuredDiagnostic[];
+};
+interface ResolveViewOptions {
+    readonly repositoryPath: string;
+    readonly orderedDocuments: readonly OrderedViewConfigDocument[];
+    /** App defaults precede root-to-nearest repository documents. */
+    readonly builtInRules?: readonly ViewRule[];
+    readonly limits?: StructuredLimits;
+}
+type SelectionResult = {
+    readonly found: true;
+    readonly value: StructuredNode;
+} | {
+    readonly found: false;
+};
+interface ViewRowContext {
+    readonly node: StructuredNode;
+    readonly key?: string;
+    readonly labels?: readonly string[];
+    /** Hierarchical, stable section path for nested row links and independent controls. */
+    readonly pathId?: string;
+}
+interface StructuredSectionSelection {
+    readonly sectionId: string;
+}
+
+declare const DEFAULT_LIMITS: Required<StructuredLimits>;
+
+declare function parseJsonText(sourceText: string, limits?: StructuredLimits): ParseResult;
+
+declare function parseYamlText(sourceText: string, limits?: StructuredLimits): ParseResult;
+
+/** Loads only same-origin packaged assets, and only when invoked in a browser. */
+declare function parseHclText(sourceText: string, limits?: StructuredLimits): Promise<ParseResult>;
+
+/** RFC 6901 without wildcards, evaluation, or prototype traversal. */
+declare function parseRelativePointer(pointer: string, maxLength?: number, maxDepth?: number): readonly string[] | null;
+declare function selectRelative(node: StructuredNode, pointer: string): SelectionResult;
+declare function selectViewPath(context: ViewRowContext, path: string): SelectionResult;
+
+declare function validateViewConfig(input: unknown, limits?: StructuredLimits): ValidationResult;
+declare function parseViewConfigText(textSource: string, format: 'json' | 'yaml', sourcePath?: string, limits?: StructuredLimits): ValidationResult;
+declare function resolveViewRule(options: ResolveViewOptions): ResolutionResult;
+
+declare function parseStructuredText(sourceText: string, format: StructuredFormat, limits?: StructuredLimits): Promise<ParseResult>;
+
+interface StructuredDisplayRow extends ViewRowContext {
+    readonly id: string;
+    readonly title: string;
+}
+declare class StructuredDataViewerComponent implements OnChanges, AfterViewChecked {
+    private readonly host;
+    document: StructuredDocument | null;
+    view: ViewRule | null;
+    activeSectionId: string | null;
+    diagnostics: readonly StructuredDiagnostic[];
+    sourceText: string;
+    showRawFallback: boolean;
+    limits: StructuredLimits;
+    sourcePositionSelected: EventEmitter<SourceRange>;
+    sectionSelected: EventEmitter<StructuredSectionSelection>;
+    private readonly expanded;
+    private readonly layouts;
+    private lastNavigatedId;
+    ngOnChanges(changes: SimpleChanges): void;
+    ngAfterViewChecked(): void;
+    get maxRows(): number;
+    get maxDepth(): number;
+    get sections(): readonly ViewSection[];
+    get rootContext(): ViewRowContext | null;
+    get rawFallbackText(): string;
+    titleText(): string | null;
+    selected(context: ViewRowContext, path: string): StructuredNode | null;
+    shortText(node: StructuredNode): string;
+    selectSection(sectionId: string): void;
+    sectionId(section: ViewSection, context: ViewRowContext): string;
+    rowActivated(row: StructuredDisplayRow): void;
+    private rowPath;
+    rowsFor(section: ViewSection, context: ViewRowContext): StructuredDisplayRow[];
+    totalRows(section: ViewSection, context: ViewRowContext): number;
+    rowLimitNotice(section: ViewSection, context: ViewRowContext): string | null;
+    entryHeading(entry: ViewEntryLayout | undefined, context: ViewRowContext, fallback: string): string;
+    entrySections(section: ViewSection): readonly ViewSection[];
+    layoutFor(section: ViewSection, context: ViewRowContext): CollectionPresentation;
+    setLayout(section: ViewSection, context: ViewRowContext, layout: CollectionPresentation): void;
+    expandedValues(section: ViewSection, context: ViewRowContext, rows: readonly StructuredDisplayRow[]): string[];
+    setExpandedValues(section: ViewSection, context: ViewRowContext, values: string | number | readonly (string | number)[] | null | undefined): void;
+    expandAll(section: ViewSection, context: ViewRowContext, rows: readonly StructuredDisplayRow[]): void;
+    collapseAll(section: ViewSection, context: ViewRowContext): void;
+    limitedFields(fields: readonly {
+        label: string;
+        node: StructuredNode;
+    }[]): readonly {
+        label: string;
+        node: StructuredNode;
+    }[];
+    omittedFields(fields: readonly {
+        label: string;
+        node: StructuredNode;
+    }[]): number;
+    otherFields(node: StructuredNode, sections: readonly ViewSection[]): readonly {
+        label: string;
+        node: StructuredNode;
+    }[];
+    fieldOther(node: StructuredNode, section: ViewSection): readonly {
+        label: string;
+        node: StructuredNode;
+    }[];
+    tableOtherFields(node: StructuredNode, section: ViewSection): readonly {
+        label: string;
+        node: StructuredNode;
+    }[];
+    tableFallbackNode(node: StructuredNode): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<StructuredDataViewerComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<StructuredDataViewerComponent, "sneat-structured-data-viewer", never, { "document": { "alias": "document"; "required": false; }; "view": { "alias": "view"; "required": false; }; "activeSectionId": { "alias": "activeSectionId"; "required": false; }; "diagnostics": { "alias": "diagnostics"; "required": false; }; "sourceText": { "alias": "sourceText"; "required": false; }; "showRawFallback": { "alias": "showRawFallback"; "required": false; }; "limits": { "alias": "limits"; "required": false; }; }, { "sourcePositionSelected": "sourcePositionSelected"; "sectionSelected": "sectionSelected"; }, never, never, true, never>;
+}
+
+export { DEFAULT_LIMITS, StructuredDataViewerComponent, parseHclText, parseJsonText, parseRelativePointer, parseStructuredText, parseViewConfigText, parseYamlText, resolveViewRule, selectRelative, selectViewPath, validateViewConfig };
+export type { BlocksSection, CollectionPresentation, EntriesSection, FieldsSection, HclAttribute, HclBlock, HclBody, InitialExpansion, OrderedViewConfigDocument, ParseResult, ResolutionResult, ResolveViewOptions, ScalarListLayout, SelectionResult, SourcePosition, SourceRange, StructuredArray, StructuredBoolean, StructuredDiagnostic, StructuredDiagnosticCode, StructuredDocument, StructuredExpression, StructuredFormat, StructuredLimits, StructuredNode, StructuredNull, StructuredNumber, StructuredObject, StructuredObjectEntry, StructuredSectionSelection, StructuredString, StructuredValue, StructuredViewConfig, TableSection, ValidationResult, ValueSection, ViewColumn, ViewEntryLayout, ViewField, ViewRowContext, ViewRule, ViewSection, ViewSectionBase, ViewTitle };