@omniviewdev/base-ui 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -241,6 +241,11 @@ declare const AlertDialogTrigger: {
 export declare interface AlertDialogTriggerProps extends Omit<ComponentPropsWithoutRef<typeof AlertDialog_2.Trigger>, 'color'>, StyledComponentProps {
 }
 
+export declare function applyQueryEdit(text: string, edit: QueryEdit): {
+    text: string;
+    selection: number;
+};
+
 export declare const AppShell: AppShellCompound;
 
 declare type AppShellCompound = typeof AppShellRoot & {
@@ -2019,6 +2024,23 @@ export declare interface EmptyStateProps extends HTMLAttributes<HTMLDivElement>
     size?: 'sm' | 'md' | 'lg';
 }
 
+/** Composition only. Hosts retain query leases, routing, rendering and all query semantics. */
+export declare function ExploreWorkspace({ title, scope, query, variables, grouping, results, saveActions, status, inspector, loading, className, }: ExploreWorkspaceProps): JSX.Element;
+
+export declare interface ExploreWorkspaceProps {
+    title?: string;
+    scope: ReactNode;
+    query: ReactNode;
+    variables?: ReactNode;
+    grouping?: ReactNode;
+    results: ReactNode;
+    saveActions?: ReactNode;
+    status?: ReactNode;
+    inspector?: ReactNode;
+    loading?: boolean;
+    className?: string;
+}
+
 /** Any element that has a string `.value` and can receive focus. */
 export declare interface FieldElement {
     value: string;
@@ -2326,6 +2348,15 @@ export declare interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElem
     borderRadius?: ImageBorderRadius;
 }
 
+export declare type IndexFootprint = {
+    kind: 'actual' | 'estimated';
+    value: string;
+    basis: string;
+} | {
+    kind: 'unavailable' | 'not-applicable';
+    reason: string;
+};
+
 /** Internal props injected by StepperRoot via Children.map. */
 declare interface InjectedStepProps {
     /* Excluded from this release type: _index */
@@ -2367,6 +2398,25 @@ declare const InputRoot: ForwardRefExoticComponent<Omit<InputRootProps, "ref"> &
 export declare interface InputRootProps extends Field.Root.Props, StyledComponentProps {
 }
 
+export declare interface InspectorAsyncContext {
+    /** Abort stops waiting for this request. The host decides whether underlying work can stop. */
+    signal: AbortSignal;
+}
+
+/** Presentation contracts only. The host owns planning, validation, matching and index lifecycle. */
+export declare interface InspectorDiagnostic {
+    id: string;
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+}
+
+export declare interface InspectorEvidence {
+    label: string;
+    kind: 'actual' | 'estimated' | 'unavailable';
+    value: string;
+    basis: string;
+}
+
 export declare function isBuiltInThemeId(id: string): id is BuiltInThemeId;
 
 /** True if the `year` is a leap year (Gregorian calendar). */
@@ -2887,6 +2937,428 @@ export declare interface ProgressProps extends Omit<HTMLAttributes<HTMLDivElemen
     size?: ComponentSize;
 }
 
+/** Both drafts are retained. Only an explicit successful host conversion changes mode. */
+export declare function QueryAuthoring({ value, onChange, contextKey, fields, request, renderEditor, toBuilder, toCode, onRun, onCancel, onRefresh, onClear, running, disabled, availability, state, scopes, scope, onScopeChange, inputProps, builderProps, labels, actions, children, className, }: QueryAuthoringProps): JSX.Element;
+
+export declare interface QueryAuthoringLabels {
+    code?: string;
+    builder?: string;
+    run?: string;
+    clear?: string;
+}
+
+export declare interface QueryAuthoringProps {
+    value: QueryAuthoringValue;
+    onChange: (value: QueryAuthoringValue) => void;
+    contextKey: string;
+    fields: QueryBuilderProps['fields'];
+    request?: QueryLanguageService;
+    /** Render the host's code editor without introducing a base-ui/editor dependency. */
+    renderEditor?: (props: QueryEditorRenderProps) => ReactNode;
+    toBuilder?: (document: QueryDocument, context: QueryConversionContext) => Promise<QueryConversionResult<QueryGroup>>;
+    toCode?: (builder: QueryGroup, context: QueryConversionContext) => Promise<QueryConversionResult<string>>;
+    onRun?: (value: QueryAuthoringValue) => void;
+    onCancel?: () => void;
+    onRefresh?: () => void;
+    onClear?: () => void;
+    running?: boolean;
+    disabled?: boolean;
+    availability?: QueryAvailability;
+    state?: QueryPresentationState;
+    scopes?: readonly QueryScopeOption[];
+    scope?: string;
+    onScopeChange?: (scope: string) => void;
+    inputProps?: Pick<QueryInputProps, 'rows' | 'label' | 'placeholder' | 'debounceMs' | 'maxSuggestions'>;
+    builderProps?: Omit<QueryBuilderProps, 'value' | 'onChange' | 'fields' | 'contextKey' | 'availability' | 'disabled'>;
+    labels?: QueryAuthoringLabels;
+    actions?: ReactNode;
+    children?: ReactNode;
+    className?: string;
+}
+
+export declare interface QueryAuthoringValue {
+    mode: 'code' | 'builder';
+    code: QueryDocument;
+    builder: QueryGroup;
+}
+
+export declare interface QueryAvailability {
+    status: 'ready' | 'loading' | 'error' | 'denied' | 'unavailable';
+    message?: string;
+}
+
+export declare function QueryBuilder({ value, onChange, fields, contextKey, disabled, availability, allowNegation, diagnostics, analyze, preview, explanation, examples, className, }: QueryBuilderProps): JSX.Element;
+
+export declare interface QueryBuilderAnalysis {
+    status: QueryServiceStatus;
+    message?: string;
+    diagnostics: readonly QueryBuilderDiagnostic[];
+    preview?: string;
+    explanation?: string;
+}
+
+export declare interface QueryBuilderDiagnostic {
+    nodeId?: string;
+    message: string;
+    severity: 'error' | 'warning' | 'info';
+}
+
+export declare interface QueryBuilderProps {
+    value: QueryGroup;
+    onChange: (value: QueryGroup) => void;
+    fields: readonly QueryField[];
+    contextKey?: string;
+    disabled?: boolean;
+    availability?: QueryAvailability;
+    diagnostics?: readonly QueryBuilderDiagnostic[];
+    /** Host-authorized operation. Negation is whole-clause/group NOT, never inequality. */
+    allowNegation?: boolean;
+    analyze?: (value: QueryGroup, context: QueryConversionContext) => Promise<QueryBuilderAnalysis>;
+    preview?: string;
+    explanation?: string;
+    examples?: readonly {
+        label: string;
+        description: string;
+        value: QueryGroup;
+    }[];
+    className?: string;
+}
+
+export declare interface QueryClause {
+    kind: 'clause';
+    id: string;
+    field?: string;
+    operator?: string;
+    value?: QueryValue;
+    negated?: boolean;
+}
+
+export declare interface QueryCompletion {
+    id: string;
+    label: string;
+    kind: 'field' | 'operator' | 'value' | 'parameter' | 'function';
+    type?: string;
+    description?: string;
+    /** Presentation-only candidate matching and host relevance order. */
+    filterText?: string;
+    sortText?: string;
+    /** Snippets use Monaco/LSP tab-stop syntax; plain edits are the default. */
+    insertTextFormat?: 'plain' | 'snippet';
+    /** Host-provided union/branch applicability. Never inferred by the component. */
+    condition?: string;
+    detail?: string;
+    disabledReason?: string;
+    edit: QueryEdit;
+}
+
+export declare interface QueryConversionContext {
+    contextKey: string;
+    signal: AbortSignal;
+}
+
+export declare type QueryConversionResult<T> = {
+    status: 'ready';
+    value: T;
+    message?: string;
+} | {
+    status: 'unsupported' | 'error' | 'denied' | 'unavailable';
+    message: string;
+};
+
+export declare interface QueryDiagnostic {
+    id: string;
+    severity: 'error' | 'warning' | 'info' | 'hint';
+    message: string;
+    range: QueryRange;
+    fix?: QueryEdit;
+}
+
+export declare interface QueryDocument {
+    text: string;
+    version: number;
+    /** Optional editor-owned identity; authoring adapters must isolate distinct models. */
+    uri?: string;
+}
+
+export declare interface QueryEdit {
+    range: QueryRange;
+    text: string;
+}
+
+/** Dependency-injected code surface. Base UI owns controls and drafts, never Monaco. */
+export declare interface QueryEditorRenderProps {
+    document: QueryDocument;
+    onChange: (text: string) => void;
+    contextKey: string;
+    request?: QueryLanguageService;
+    availability?: QueryAvailability;
+    disabled?: boolean;
+    onSubmit?: () => void;
+    label?: string;
+    placeholder?: string;
+    debounceMs?: number;
+    maxSuggestions?: number;
+}
+
+export declare interface QueryExplain {
+    queryLabel: string;
+    scope: string;
+    coverage: string;
+    freshness: string;
+    selectionReason: string;
+    measuredAt?: string;
+    stages: readonly {
+        id: string;
+        label: string;
+        description: string;
+        indexIds: readonly string[];
+        work: readonly InspectorEvidence[];
+    }[];
+    diagnostics: readonly InspectorDiagnostic[];
+}
+
+export declare function QueryExplainPanel({ explain, state, message }: QueryExplainPanelProps): JSX.Element;
+
+export declare interface QueryExplainPanelProps {
+    explain?: QueryExplain;
+    state?: 'ready' | 'loading' | 'denied' | 'unavailable';
+    message?: string;
+}
+
+export declare interface QueryField {
+    id: string;
+    label: string;
+    type: string;
+    description?: string;
+    condition?: string;
+    disabledReason?: string;
+    operators: readonly QueryOperator[];
+}
+
+export declare interface QueryGroup {
+    kind: 'group';
+    id: string;
+    combinator: 'and' | 'or';
+    children: readonly QueryNode[];
+    negated?: boolean;
+}
+
+export declare interface QueryHoverResponse {
+    documentVersion: number;
+    contextKey: string;
+    status: QueryServiceStatus;
+    message?: string;
+    /** Untrusted Markdown documentation for a checked source range. */
+    hover?: {
+        range: QueryRange;
+        contents: string;
+    };
+}
+
+export declare type QueryHoverService = (request: QueryLanguageRequest) => Promise<QueryHoverResponse>;
+
+/** Compact native editing mechanics: no CEL parser, schema walker, Monaco model or worker. */
+export declare function QueryInput({ document, onChange, contextKey, request, onSubmit, label, placeholder, disabled, readOnly, availability, debounceMs, maxSuggestions, rows, className, }: QueryInputProps): JSX.Element;
+
+export declare interface QueryInputProps {
+    document: QueryDocument;
+    onChange: (text: string) => void;
+    contextKey: string;
+    request?: QueryLanguageService;
+    onSubmit?: () => void;
+    label?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    readOnly?: boolean;
+    availability?: QueryAvailability;
+    debounceMs?: number;
+    /** Bounded visible suggestions; the service must also enforce its own response limit. */
+    maxSuggestions?: number;
+    rows?: number;
+    className?: string;
+}
+
+export declare interface QueryLanguageRequest {
+    document: QueryDocument;
+    cursor: {
+        offset: number;
+        unit: 'utf8-byte';
+    };
+    contextKey: string;
+    signal: AbortSignal;
+}
+
+export declare interface QueryLanguageResponse {
+    documentVersion: number;
+    contextKey: string;
+    status: QueryServiceStatus;
+    message?: string;
+    completions: readonly QueryCompletion[];
+    diagnostics: readonly QueryDiagnostic[];
+    /** Suggestions are bounded observations, not exhaustive inventory/schema facts. */
+    incomplete?: boolean;
+}
+
+export declare type QueryLanguageService = (request: QueryLanguageRequest) => Promise<QueryLanguageResponse>;
+
+export declare type QueryNode = QueryClause | QueryGroup;
+
+export declare interface QueryOperator {
+    id: string;
+    label: string;
+    description?: string;
+    /** Omit for host-defined state clauses such as present/absent/null. */
+    value?: QueryValueDefinition;
+    disabledReason?: string;
+}
+
+export declare interface QueryOptionRequest {
+    contextKey: string;
+    search: string;
+    signal: AbortSignal;
+}
+
+export declare interface QueryOptionResponse {
+    contextKey: string;
+    status: QueryServiceStatus;
+    options: readonly QueryValueOption[];
+    message?: string;
+    incomplete?: boolean;
+}
+
+export declare interface QueryPresentationState {
+    status: 'idle' | 'loading' | 'live' | 'snapshot' | 'stale' | 'partial' | 'error' | 'denied' | 'unavailable';
+    message: string;
+    detail?: ReactNode;
+}
+
+/** Local presentation contracts, not a host wire protocol. Source offsets are zero-based,
+ * half-open UTF-8 byte offsets. The adapter converts DOM UTF-16 offsets explicitly. */
+export declare interface QueryRange {
+    start: number;
+    end: number;
+    unit: 'utf8-byte';
+}
+
+export declare interface QueryScopeOption {
+    id: string;
+    label: string;
+    description?: string;
+    disabledReason?: string;
+}
+
+export declare type QueryServiceStatus = 'ready' | 'empty' | 'error' | 'denied' | 'unavailable';
+
+export declare interface QuerySignatureResponse {
+    documentVersion: number;
+    contextKey: string;
+    status: QueryServiceStatus;
+    message?: string;
+    signature?: {
+        label: string;
+        documentation?: string;
+        parameters: readonly {
+            label: string;
+            documentation?: string;
+        }[];
+        activeParameter: number;
+    };
+}
+
+export declare type QuerySignatureService = (request: QueryLanguageRequest) => Promise<QuerySignatureResponse>;
+
+/** Numeric and timestamp drafts remain text. Host validation/admission owns conversion,
+ * exactness, ranges, timezone policy, nullability, defaults and execution binding. */
+export declare type QueryValue = {
+    kind: 'string' | 'integer' | 'number' | 'timestamp';
+    value: string;
+} | {
+    kind: 'boolean';
+    value: boolean;
+} | {
+    kind: 'enum';
+    value: string;
+} | {
+    kind: 'list';
+    value: readonly string[];
+} | {
+    kind: 'record';
+    value: Readonly<Record<string, QueryValue | undefined>>;
+};
+
+/** Host-defined compound inputs preserve correlations (for example a tag key/value
+ * pair). Their field IDs are opaque and do not imply paths or query semantics. */
+export declare type QueryValueDefinition = QueryValueDefinitionBase & ({
+    kind: Exclude<QueryValue['kind'], 'record'>;
+} | {
+    kind: 'record';
+    fields: readonly {
+        id: string;
+        label: string;
+        definition: QueryValueDefinition;
+        required?: boolean;
+    }[];
+});
+
+declare interface QueryValueDefinitionBase {
+    placeholder?: string;
+    description?: string;
+    options?: readonly QueryValueOption[];
+    loadOptions?: (request: QueryOptionRequest) => Promise<QueryOptionResponse>;
+    /** Host explanation of supported constraints, rendered without reimplementing validation. */
+    constraint?: string;
+}
+
+/** Renders host-declared types. Numeric drafts never pass through Number/parseInt. */
+export declare function QueryValueInput({ definition, value, onChange, contextKey, label, disabled, sensitive, required, error, }: QueryValueInputProps): JSX.Element;
+
+export declare interface QueryValueInputProps {
+    definition: QueryValueDefinition;
+    value?: QueryValue;
+    onChange: (value: QueryValue | undefined) => void;
+    contextKey?: string;
+    label?: string;
+    disabled?: boolean;
+    sensitive?: boolean;
+    required?: boolean;
+    error?: string;
+}
+
+export declare interface QueryValueOption {
+    id: string;
+    label: string;
+    value: string;
+    description?: string;
+    disabledReason?: string;
+}
+
+export declare interface QueryVariable {
+    id: string;
+    label: string;
+    definition: QueryValueDefinition;
+    description?: string;
+    required?: boolean;
+    sensitive?: boolean;
+    disabledReason?: string;
+    defaultValue?: QueryValue;
+    error?: string;
+}
+
+/** Editing drafts only: the host owns defaults, constraints, dependency cycles and binding.
+ * Values never interpolate into query text and sensitive values are never serialized here. */
+export declare function QueryVariables({ variables, value, onChange, contextKey, availability, disabled, diagnostics, }: QueryVariablesProps): JSX.Element;
+
+export declare interface QueryVariablesProps {
+    variables: readonly QueryVariable[];
+    value: Readonly<Record<string, QueryValue | undefined>>;
+    onChange: (value: Readonly<Record<string, QueryValue | undefined>>) => void;
+    /** Include dependency/scope/permission revisions to cancel outdated value lookups. */
+    contextKey?: string;
+    availability?: QueryAvailability;
+    disabled?: boolean;
+    diagnostics?: readonly string[];
+}
+
 export declare const Quote: <C extends QuoteElement = "q">(props: TypographyBaseProps & TruncationProps & {
     as?: C | undefined;
 } & Omit<PropsWithoutRef<ComponentProps<C>>, "color" | "as" | "truncate" | keyof TypographyBaseProps> & {
@@ -2970,6 +3442,118 @@ export declare interface RegisteredTheme extends ThemeSummary {
     definition: ThemeDefinition;
 }
 
+export declare type RelationshipCardinality = 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many';
+
+export declare interface RelationshipCatalog {
+    sourceTypes: readonly RelationshipTypeOption[];
+    targetTypes: readonly RelationshipTypeOption[];
+    scopeMappings: readonly {
+        id: string;
+        label: string;
+        description: string;
+        state: 'available' | 'denied' | 'unavailable';
+    }[];
+    /** Host-supplied operators; compatibility is validated by the host, never inferred here. */
+    operators: readonly {
+        id: string;
+        label: string;
+        description: string;
+    }[];
+}
+
+export declare interface RelationshipCondition {
+    id: string;
+    sourceFieldId: string;
+    operatorId: string;
+    targetFieldId: string;
+}
+
+export declare interface RelationshipEndpoint {
+    label: string;
+    /** Opaque host navigation target, not an inferred identity. Omit for protected endpoints. */
+    navigationId?: string;
+}
+
+export declare interface RelationshipFieldOption {
+    id: string;
+    label: string;
+    type: string;
+}
+
+export declare function RelationshipPreview({ preview, state, message, onNavigate, }: RelationshipPreviewProps): JSX.Element;
+
+export declare interface RelationshipPreviewData {
+    scope: string;
+    coverage: string;
+    limit: number;
+    truncated: boolean;
+    summary: string;
+    diagnostics: readonly InspectorDiagnostic[];
+    edges: readonly {
+        id: string;
+        source: RelationshipEndpoint;
+        target?: RelationshipEndpoint;
+        state: 'matched' | 'unmatched' | 'ambiguous' | 'denied' | 'unavailable';
+        detail: string;
+        provenance: {
+            origin: 'provider' | 'user';
+            ruleLabel: string;
+            condition: string;
+            scopeMapping: string;
+        };
+    }[];
+}
+
+export declare interface RelationshipPreviewProps {
+    preview?: RelationshipPreviewData;
+    state?: 'ready' | 'loading' | 'denied' | 'unavailable';
+    message?: string;
+    onNavigate?: (navigationId: string) => void;
+}
+
+export declare interface RelationshipRuleDraft {
+    id: string;
+    name: string;
+    sourceTypeId: string;
+    targetTypeId: string;
+    scopeMappingId: string;
+    cardinality: RelationshipCardinality;
+    conditions: readonly RelationshipCondition[];
+    enabled: boolean;
+    origin: 'user' | 'provider';
+}
+
+export declare function RelationshipRuleEditor({ draft, catalog, onChange, onSave, onPreview, onSetEnabled, validation, preview, previewIsCurrent, onNavigate, state, message, }: RelationshipRuleEditorProps): JSX.Element;
+
+export declare interface RelationshipRuleEditorProps {
+    draft: RelationshipRuleDraft;
+    catalog: RelationshipCatalog;
+    onChange: (draft: RelationshipRuleDraft) => void;
+    onSave: (draft: RelationshipRuleDraft, context: InspectorAsyncContext) => Promise<void>;
+    onPreview: (draft: RelationshipRuleDraft, context: InspectorAsyncContext) => Promise<void>;
+    onSetEnabled: (enabled: boolean, context: InspectorAsyncContext) => Promise<void>;
+    /** Must describe the current controlled draft. Unknown/pending drafts cannot be saved. */
+    validation: RelationshipValidation;
+    preview?: RelationshipPreviewData;
+    /** The host confirms the preview belongs to this exact draft/access context. Defaults to false. */
+    previewIsCurrent?: boolean;
+    onNavigate?: (navigationId: string) => void;
+    state?: 'ready' | 'loading' | 'denied' | 'unavailable';
+    message?: string;
+}
+
+export declare interface RelationshipTypeOption {
+    id: string;
+    label: string;
+    provider: string;
+    fields: readonly RelationshipFieldOption[];
+}
+
+export declare interface RelationshipValidation {
+    state: 'unchecked' | 'pending' | 'valid' | 'invalid' | 'denied' | 'unavailable';
+    diagnostics: readonly InspectorDiagnostic[];
+}
+
 export declare type ReorderMeta = {
     id: TabId;
     from: number;
@@ -2997,6 +3581,200 @@ export declare interface ResizableSplitPaneProps extends HTMLAttributes<HTMLDivE
     children: [ReactNode, ReactNode];
 }
 
+export declare function ResourceGroupingControls({ fields, value, onChange, loading, error, disabled, className, }: ResourceGroupingControlsProps): JSX.Element;
+
+export declare interface ResourceGroupingControlsProps {
+    fields: readonly ResourceGroupingField[];
+    value: ResourceGroupingValue;
+    onChange: (value: ResourceGroupingValue) => void;
+    loading?: boolean;
+    error?: string;
+    disabled?: boolean;
+    className?: string;
+}
+
+export declare interface ResourceGroupingField {
+    id: string;
+    label: string;
+    groupable: boolean;
+    splittable: boolean;
+    reason?: string;
+    applicability?: string;
+}
+
+export declare interface ResourceGroupingValue {
+    groupBy: readonly string[];
+    splitBy: readonly string[];
+}
+
+export declare type ResourceIndexAction = {
+    kind: 'create';
+    definition: ResourceIndexDefinition;
+} | {
+    kind: 'rebuild' | 'drop';
+    indexId: string;
+} | {
+    kind: 'cancel';
+    operationId: string;
+};
+
+export declare interface ResourceIndexAdvice {
+    id: string;
+    viewLabel: string;
+    queryLabel: string;
+    proposalId?: string;
+    indexIds: readonly string[];
+    recommendation: string;
+    confidence: string;
+    basis: string;
+    benefit: InspectorEvidence;
+    memory: IndexFootprint;
+    disk: IndexFootprint;
+    writeCost: InspectorEvidence;
+    beforeAfter?: {
+        before: string;
+        after: string;
+        basis: string;
+    };
+}
+
+export declare interface ResourceIndexDefinition {
+    id: string;
+    label: string;
+    provider: string;
+    resourceType: string;
+    scope: string;
+    path: string;
+    valueType: string;
+    schema: string;
+    storage: 'memory' | 'persisted';
+    dataPolicy: string;
+}
+
+export declare interface ResourceIndexInventory extends ResourceIndexDefinition {
+    kind: 'metadata' | 'document';
+    state: 'ready' | 'building' | 'catching-up' | 'stale' | 'failed' | 'canceled' | 'unavailable' | 'denied';
+    coverage: string;
+    freshness: string;
+    generation?: string;
+    memory: IndexFootprint;
+    disk: IndexFootprint;
+    quota?: string;
+    references: readonly {
+        id: string;
+        label: string;
+        queryLabel: string;
+    }[];
+    fallback: string;
+    failure?: string;
+    operation?: {
+        id: string;
+        label: string;
+        progress?: number;
+        cancellable: boolean;
+    };
+    /** Host-authorized actions; absence never means allowed. */
+    actions: readonly ('rebuild' | 'drop')[];
+}
+
+export declare function ResourceIndexManager({ indexes, proposals, advice, onAction, state, message, }: ResourceIndexManagerProps): JSX.Element;
+
+export declare interface ResourceIndexManagerProps {
+    indexes: readonly ResourceIndexInventory[];
+    /** Host-admitted create definitions, including schema/scope/storage/data policy. */
+    proposals: readonly ResourceIndexDefinition[];
+    advice: readonly ResourceIndexAdvice[];
+    onAction: (action: ResourceIndexAction, context: InspectorAsyncContext) => Promise<void>;
+    state?: 'ready' | 'loading' | 'denied' | 'unavailable';
+    message?: string;
+}
+
+export declare interface ResourceNavigationResult<TResource> {
+    label: string;
+    provenance: string;
+    resource: TResource;
+    disabledReason?: string;
+}
+
+export declare function ResourceResultNavigation<TResource, TContext>({ result, context, requestKey, onNavigate, }: ResourceResultNavigationProps<TResource, TContext>): JSX.Element;
+
+export declare interface ResourceResultNavigationProps<TResource, TContext> {
+    result: ResourceNavigationResult<TResource>;
+    /** Passed intact to the host so opening a drawer/route can retain the originating workspace. */
+    context: TContext;
+    /** Host destination/context generation. Change to cancel a pending navigation; object identity is irrelevant. */
+    requestKey: string | number;
+    onNavigate: (result: ResourceNavigationResult<TResource>, context: TContext, signal: AbortSignal) => Promise<WorkspaceActionResult>;
+}
+
+export declare function ResourceScopePicker({ targets, value, onChange, loading, error, disabled, className, }: ResourceScopePickerProps): JSX.Element;
+
+export declare interface ResourceScopePickerProps {
+    targets: readonly ResourceScopeTarget[];
+    value: readonly ResourceScopeSelection[];
+    onChange: (value: readonly ResourceScopeSelection[]) => void;
+    loading?: boolean;
+    error?: string;
+    disabled?: boolean;
+    className?: string;
+}
+
+/** Empty/missing dimensions stay unresolved; this control never broadens them. */
+export declare interface ResourceScopeSelection {
+    targetId: string;
+    dimensions: Readonly<Record<string, readonly string[] | 'any'>>;
+}
+
+/** Host catalog identifiers are opaque; display labels never become resource identity. */
+export declare interface ResourceScopeTarget {
+    id: string;
+    provider: string;
+    connection: string;
+    resourceType: string;
+    description?: string;
+    status?: 'ready' | 'loading' | 'partial' | 'denied' | 'offline' | 'unsupported';
+    reason?: string;
+    dimensions?: readonly {
+        id: string;
+        label: string;
+        allowAny?: boolean;
+        values: readonly {
+            id: string;
+            label: string;
+            disabledReason?: string;
+        }[];
+    }[];
+}
+
+/** The host supplies already bounded/ranked results; no client filtering or indexing. */
+export declare interface ResourceSearchItem<TPayload> {
+    id: string;
+    kind: 'command' | 'setting' | 'navigation' | 'resource';
+    label: string;
+    description?: string;
+    provenance?: string;
+    disabledReason?: string;
+    payload: TPayload;
+    decoration?: ReactNode;
+}
+
+export declare function ResourceSearchResults<TPayload>({ query, onQueryChange, items, onActivate, onDismiss, loading, error, status, scopeStatus, stale, }: ResourceSearchResultsProps<TPayload>): JSX.Element;
+
+export declare interface ResourceSearchResultsProps<TPayload> {
+    query: string;
+    onQueryChange: (query: string) => void;
+    items: readonly ResourceSearchItem<TPayload>[];
+    onActivate: (item: ResourceSearchItem<TPayload>, signal: AbortSignal) => Promise<WorkspaceActionResult>;
+    onDismiss?: () => void;
+    loading?: boolean;
+    error?: string;
+    /** Host-supplied permission, freshness, partial-source and bounded-result explanations. */
+    status?: ReactNode;
+    scopeStatus?: ReactNode;
+    /** The host can disable older results while replacing its query generation. */
+    stale?: boolean;
+}
+
 /** A span value can be a plain number or a per-breakpoint responsive object. */
 export declare type ResponsiveSpan = number | Partial<Record<GridBreakpoint, number>>;
 
@@ -3053,6 +3831,66 @@ export declare interface RowListRootProps extends ListRootProps {
     onSortChange?: (sort: SortState) => void;
 }
 
+/** Presentation requests only: the host owns document schemas, semantics and persistence. */
+export declare type SavedResourceAction<TDraft> = {
+    type: 'create';
+    name: string;
+    draft: TDraft;
+} | {
+    type: 'rename';
+    id: string;
+    name: string;
+} | {
+    type: 'select';
+    id: string | null;
+} | {
+    type: 'save';
+    id: string;
+    name: string;
+    draft: TDraft;
+} | {
+    type: 'reset';
+    id: string | null;
+} | {
+    type: 'delete';
+    id: string;
+} | {
+    type: 'import';
+    document: string;
+} | {
+    type: 'export';
+    id: string;
+};
+
+export declare interface SavedResourceItem {
+    id: string;
+    name: string;
+    status?: 'ready' | 'conflict' | 'corrupt' | 'unsupported' | 'denied' | 'unavailable';
+    reason?: string;
+}
+
+export declare function SavedResourceManager<TDraft>({ kind, items, selectedId, nameDraft, onNameDraftChange, importDraft, onImportDraftChange, draft, dirty, onAction, status, loading, disabled, disabledReason, children, className, }: SavedResourceManagerProps<TDraft>): JSX.Element;
+
+export declare interface SavedResourceManagerProps<TDraft> {
+    kind: 'query' | 'view' | 'preset';
+    items: readonly SavedResourceItem[];
+    selectedId: string | null;
+    nameDraft: string;
+    onNameDraftChange: (name: string) => void;
+    importDraft: string;
+    onImportDraftChange: (document: string) => void;
+    /** Opaque configuration. Never interpreted, serialized, or validated by this component. */
+    draft: TDraft;
+    dirty: boolean;
+    onAction: (action: SavedResourceAction<TDraft>, signal: AbortSignal) => Promise<WorkspaceActionResult>;
+    status?: WorkspaceActionResult;
+    loading?: boolean;
+    disabled?: boolean;
+    disabledReason?: string;
+    children?: ReactNode;
+    className?: string;
+}
+
 export declare const ScrollArea: ForwardRefExoticComponent<ScrollAreaProps & RefAttributes<HTMLDivElement>>;
 
 export declare type ScrollAreaOrientation = 'vertical' | 'horizontal' | 'both';
@@ -4873,6 +5711,10 @@ export declare function useTreeItem(store: TreeStore, key: Key_3, textValue?: st
 
 export declare function useTreeStoreContext(): TreeStore;
 
+export declare function utf16ToUtf8(text: string, offset: number): number;
+
+export declare function utf8ToUtf16(text: string, offset: number): number;
+
 /** Validation function. Return a FieldErrors map (empty or all-undefined = valid). */
 export declare type ValidateItem = (key: Key, values: Record<string, string>) => FieldErrors | Promise<FieldErrors>;
 
@@ -4893,6 +5735,127 @@ export declare interface ValidateSectionsResult {
 
 export declare function validateThemeDefinition(input: unknown, supportsColor?: SupportsColor): ThemeDefinition;
 
+/**
+ * Controlled, keyed layout with pointer and keyboard arrangement. Renderers own
+ * acquisition/lifetimes; preview does not silently unmount panels or pause data.
+ */
+export declare function ViewLayout<TItem extends ViewLayoutItem>({ items, onItemsChange, renderItem, onConfigure, editing, disabled, readOnly, columns, rowHeight, maxRowSpan, emptyContent, className, onFocusCapture, ...props }: ViewLayoutProps<TItem>): JSX.Element;
+
+/** Presentation geometry only, not a persisted saved-view document. */
+export declare interface ViewLayoutItem {
+    id: string;
+    title: string;
+    columnSpan: number;
+    rowSpan: number;
+}
+
+export declare interface ViewLayoutProps<TItem extends ViewLayoutItem = ViewLayoutItem> extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    items: readonly TItem[];
+    onItemsChange: (items: TItem[]) => void;
+    renderItem: (item: TItem) => ReactNode;
+    onConfigure?: (id: string) => void;
+    editing?: boolean;
+    /** Prevent layout/configuration changes without disabling rendered panel content. */
+    disabled?: boolean;
+    /** Keep editing controls discoverable, but prevent layout/configuration changes. */
+    readOnly?: boolean;
+    columns?: 1 | 2 | 3 | 4 | 6 | 12;
+    rowHeight?: number;
+    maxRowSpan?: number;
+    emptyContent?: ReactNode;
+}
+
+export declare interface VisualizationBindingDiagnostic {
+    slotId?: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+}
+
+export declare function VisualizationBindingEditor({ slots, fields, value, onChange, diagnostics, disabled, visualizationId, visualizations, onVisualizationChange, children, className, ...props }: VisualizationBindingEditorProps): JSX.Element;
+
+export declare interface VisualizationBindingEditorProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    slots: readonly VisualizationBindingSlot[];
+    /** Host-projected choices. IDs are opaque: this component never resolves paths or compatibility. */
+    fields: readonly VisualizationFieldOption[];
+    value: VisualizationBindings;
+    onChange: (bindings: VisualizationBindings) => void;
+    diagnostics?: readonly VisualizationBindingDiagnostic[];
+    disabled?: boolean;
+    visualizationId?: string;
+    visualizations?: readonly VisualizationOption[];
+    onVisualizationChange?: (id: string) => void;
+}
+
+export declare type VisualizationBindings = Readonly<Record<string, string | undefined>>;
+
+export declare interface VisualizationBindingSlot {
+    id: string;
+    label: string;
+    description?: string;
+    required?: boolean;
+}
+
+/** Values have already been selected/validated by the caller. Exact integers can remain strings. */
+export declare type VisualizationDisplayValue = string | number | boolean | null | readonly VisualizationDisplayValue[] | {
+    readonly [key: string]: VisualizationDisplayValue;
+};
+
+export declare interface VisualizationField {
+    id: string;
+    label: string;
+    value: VisualizationFieldValue;
+}
+
+export declare interface VisualizationFieldOption {
+    id: string;
+    label: string;
+    type: string;
+    description?: string;
+    disabledReason?: string;
+}
+
+/** Bounded presentation only: does not parse field paths, evaluate selectors or fetch resources. */
+export declare function VisualizationFields({ fields, presentation, className, ...props }: VisualizationFieldsProps): JSX.Element;
+
+export declare interface VisualizationFieldsProps extends HTMLAttributes<HTMLDivElement> {
+    fields: readonly VisualizationField[];
+    presentation?: 'stat' | 'list' | 'key-value';
+}
+
+export declare type VisualizationFieldValue = {
+    status: 'ready';
+    value: VisualizationDisplayValue;
+} | {
+    status: 'missing' | 'type-error' | 'unavailable' | 'denied';
+    message: string;
+};
+
+export declare interface VisualizationOption {
+    id: string;
+    label: string;
+    description?: string;
+    disabledReason?: string;
+}
+
+/** Non-ready content is not mounted; each panel fails independently. */
+export declare function VisualizationPanel({ title, status, description, detail, actions, children, className, ...props }: VisualizationPanelProps): JSX.Element;
+
+export declare interface VisualizationPanelProps extends Omit<HTMLAttributes<HTMLElement>, 'color'> {
+    title: string;
+    status: VisualizationStatus;
+    description?: string;
+    /** Safe, host-provided diagnostic; never derives or requests protected data. */
+    detail?: string;
+    actions?: ReactNode;
+}
+
+export declare type VisualizationStatus = 'ready' | 'loading' | 'empty' | 'error' | 'unavailable' | 'denied';
+
 declare type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
 
+export declare type WorkspaceActionResult = {
+    status: 'success' | 'conflict' | 'corrupt' | 'unsupported' | 'denied' | 'unavailable' | 'error';
+    message?: string;
+};
+
 export { }