/**
 * Dashboard documents — `apps/<app>/dashboards/<id>.dqld`.
 *
 * `.dqld` is JSON. A dashboard composes certified blocks (or notebook cells
 * bound to block files) into an explicit grid layout with params, filters,
 * and a viz config per item. Distinct from `.dqlnb` notebooks, which are a
 * linear cell sequence.
 *
 * The reference shape allows two forms:
 * - by-id  : `{ "blockId": "revenue_total" }` — resolved at compile time
 *            against the manifest's blocks map.
 * - by-path: `{ "ref": "blocks/revenue_total.dql" }` — resolved against the
 *            block scanner's path-to-name map.
 *
 * Either form may also pin a git SHA (`"version": "git:abc123"`).
 */
export type DashboardParam = {
    id: string;
    type: 'string' | 'number' | 'boolean' | 'date' | 'daterange';
    default?: unknown;
    description?: string;
};
export type DashboardFilter = {
    id: string;
    type: 'string' | 'number' | 'boolean' | 'date' | 'daterange' | 'relative_date' | 'select' | 'multiselect' | 'search' | 'number_range';
    label?: string;
    default?: unknown;
    /** For 'select': allowed values. */
    options?: string[];
    /** Optional dimension reference the filter binds to. */
    bindsTo?: string;
    /** Qualified identity; display names alone are never sufficient binding proof. */
    field?: {
        name: string;
        relation?: string;
        semanticModel?: string;
        provider?: string;
    };
    required?: boolean;
    multiple?: boolean;
    scope?: {
        page?: string;
        tileIds?: string[];
    };
    optionSource?: {
        mode: 'static' | 'distinct_query';
        sourceRef?: string;
        field?: string;
        snapshotId?: string;
        limit?: number;
    };
    dependsOn?: string[];
};
export type DashboardBlockRef = {
    blockId: string;
    version?: string;
} | {
    ref: string;
    version?: string;
};
export type DashboardVizConfig = {
    /** Chart kind. The renderer picks the matching @duckcodeailabs/dql-charts component. */
    type: 'single_value' | 'grouped_bar' | 'stacked_bar' | 'line' | 'bar' | 'area' | 'pie' | 'donut' | 'scatter' | 'heatmap' | 'histogram' | 'waterfall' | 'gauge' | 'table' | 'pivot' | 'map' | 'funnel' | 'sankey' | 'kpi' | 'text' | 'heading';
    /** Free-form per-renderer options (axes, colors, etc.). */
    options?: Record<string, unknown>;
};
export type DashboardDisplayMode = 'manual' | 'ai_generated' | 'block_hint';
export type DashboardDisplayComponent = 'BusinessBrief' | 'KpiMetric' | 'TrendPanel' | 'RankingPanel' | 'EvidenceTable' | 'PivotTable' | 'TrustCallout' | 'NarrativePanel' | 'ResearchActions';
export type DashboardDisplayLayoutIntent = 'auto' | 'compact' | 'standard' | 'wide' | 'tall' | 'full';
export type DashboardDisplayTrustState = 'certified' | 'review_required' | 'draft_ready';
export type DashboardDisplayReviewStatus = 'certified' | 'draft_ready' | 'review_required';
export type DashboardDisplayMetadata = {
    /** Presentation source. The block remains the data contract; this is consumer-level UI metadata. */
    mode: DashboardDisplayMode;
    component: DashboardDisplayComponent;
    defaultVisualization: DashboardVizConfig['type'];
    allowedVisualizations: DashboardVizConfig['type'][];
    fieldHints?: Record<string, string>;
    layoutIntent: DashboardDisplayLayoutIntent;
    rationale: string;
    trustState: DashboardDisplayTrustState;
    reviewStatus: DashboardDisplayReviewStatus;
};
export type DashboardTileFilterBinding = {
    /** Dashboard/app filter id such as `period`, `region`, or `season`. */
    filter: string;
    /** Physical column/expression or semantic field this filter can bind to. */
    binding?: string;
    /** Whether this becomes a block parameter or an outer predicate at execution time. */
    mode?: 'parameter' | 'predicate' | 'semantic';
    /** Block parameter names controlled by this app filter. */
    paramNames?: string[];
    /** If true, the tile should warn when the filter is missing. */
    required?: boolean;
    /** Populated when a global filter intentionally does not apply to this tile. */
    unsupportedReason?: string;
    /** Explicit capability prevents a global filter from appearing silently partial. */
    capability?: 'supported' | 'unsupported' | 'preflight_required';
};
export type DashboardTileParameterBinding = {
    /** Block parameter name. */
    param: string;
    /** Where the parameter value comes from on the consumption surface. */
    source: 'dashboard_filter' | 'constant' | 'persona' | 'variable';
    filter?: string;
    field?: string;
    value?: unknown;
    /** Typed block contract metadata used to render the correct consumer control. */
    parameterType?: 'string' | 'number' | 'boolean' | 'date' | 'string[]' | 'number[]' | 'date[]';
    required?: boolean;
    default?: unknown;
    policy?: 'dynamic' | 'static' | 'business' | 'derived' | 'optional' | 'ambiguous_review_required';
};
export type DashboardTileSourceEvidence = {
    source: string;
    reason: string;
    kind?: string;
    nodeId?: string;
    path?: string;
    trustState?: DashboardDisplayTrustState;
};
export type DashboardTextTile = {
    markdown: string;
};
export type DashboardAiPinRef = {
    id: string;
};
/** Git-owned, review-required App analysis. SQL lives in the referenced DQL
 * draft, never inline in the dashboard document. */
export type DashboardDraftAnalysisRef = {
    ref: string;
    artifactFingerprint: string;
    snapshotId?: string;
    executionReceiptId?: string;
};
export type DashboardTileSourceClass = 'certified_block' | 'governed_semantic' | 'exploratory_analysis' | 'narrative';
export type DashboardTileReview = {
    status: 'not_required' | 'required' | 'approved';
    sourceFingerprint?: string;
    preflightReceiptId?: string;
    reviewedAt?: string;
    reviewedBy?: string;
};
/** Canonical governed semantic query. This stores intent and reviewed semantic
 * references, never copied/generated SQL. The runtime compiles it against the
 * active snapshot before every execution. */
export type DashboardSemanticQueryRef = {
    id: string;
    provider: 'metricflow' | 'native';
    metrics: string[];
    dimensions?: string[];
    filters?: Array<{
        field: string;
        operator: string;
        value: unknown;
    }>;
    timeDimension?: string;
    orderBy?: Array<{
        field: string;
        direction: 'asc' | 'desc';
    }>;
    limit?: number;
    semanticModelRefs: string[];
    /** Qualified snapshot identities; names above remain the v1 execution projection. */
    qualifiedMetricIds?: string[];
    qualifiedModelIds?: string[];
    resolvedPlanFingerprint?: string;
    definitionFingerprint: string;
    snapshotId?: string;
};
export type DashboardStoryEvidencePlan = {
    version: 1;
    goal: string;
    audience?: string;
    /** Tile ids eligible to contribute facts. Empty means every governed data tile. */
    eligibleTileIds?: string[];
    /** Tile ids whose verified results may support driver language. */
    driverTileIds?: string[];
    /** Preferred business terms to retain in the story. */
    vocabulary?: string[];
};
export type DashboardStoryFact = {
    id: string;
    tileId: string;
    kind: 'value' | 'rank' | 'share' | 'delta' | 'trend' | 'driver' | 'scope' | 'freshness';
    label: string;
    value: string | number | boolean | null;
    unit?: string;
    comparison?: {
        baseline: string | number;
        delta?: string | number;
    };
    grain?: string;
    filters?: Record<string, unknown>;
    evidenceRef: string;
    trustState: DashboardDisplayTrustState;
};
export type DashboardStoryClaim = {
    text: string;
    factIds: string[];
    kind: 'observation' | 'comparison' | 'driver' | 'implication' | 'caveat';
};
export type DashboardStoryBrief = {
    headline: string;
    paragraphs: string[];
    implication?: string;
    caveat?: string;
    claims: DashboardStoryClaim[];
    evidenceRefs: string[];
    trustState: DashboardDisplayTrustState;
    generatedBy: 'deterministic' | 'ai';
};
export type DashboardGridItem = {
    /** Stable layout id — used by the grid editor for positioning persistence. */
    i: string;
    x: number;
    y: number;
    w: number;
    h: number;
    /**
     * Canonical AppBuildDraft source binding. App Studio v3 writes this for
     * every data tile; legacy published dashboards remain readable without it.
     */
    sourceId?: string;
    /** Snapshot-bound source revision selected by App Studio. */
    sourceRevision?: string;
    /** Certified/shared block source. Existing dashboards use this shape. */
    block?: DashboardBlockRef;
    /** Local narrative/section text tile. */
    text?: DashboardTextTile;
    /** Local AI-generated answer pin stored in .dql/local/apps.sqlite. */
    aiPin?: DashboardAiPinRef;
    /** Governed semantic query compiled against the current snapshot. */
    semantic?: DashboardSemanticQueryRef;
    /** Explicitly accepted, app-scoped exploratory DQL draft. */
    draftAnalysis?: DashboardDraftAnalysisRef;
    viz: DashboardVizConfig;
    /** Governed GenUI/display contract for this specific App or notebook tile. */
    display?: DashboardDisplayMetadata;
    /** App-level filter compatibility and binding metadata for this tile. */
    filterBindings?: DashboardTileFilterBinding[];
    /** Runtime parameter binding metadata for this tile. */
    parameterBindings?: DashboardTileParameterBinding[];
    /** Evidence used by AI/App Builder to choose this tile and presentation. */
    sourceEvidence?: DashboardTileSourceEvidence[];
    sourceClass?: DashboardTileSourceClass;
    review?: DashboardTileReview;
    /** Denormalized trust marker for stakeholder and source-control surfaces. */
    trustState?: DashboardDisplayTrustState;
    /** Denormalized review marker for stakeholder and source-control surfaces. */
    reviewStatus?: DashboardDisplayReviewStatus;
    /** Optional human-readable title shown in the tile header. */
    title?: string;
    /** Story layout: which dashboard section this tile belongs to (optional, additive). */
    sectionId?: string;
};
/**
 * Story-layout section (optional, additive): groups tiles into a narrated flow —
 * executive summary → KPI band → per-question insights → review appendix.
 * Dashboards without sections render as the classic grid.
 */
export type DashboardSection = {
    id: string;
    title: string;
    kind: 'exec_summary' | 'kpi_band' | 'insight' | 'appendix';
    /** Narrated intro for the section (real numbers from executed results). */
    narrative?: string;
    order: number;
};
export type DashboardGridLayout = {
    kind: 'grid';
    cols: number;
    rowHeight: number;
    items: DashboardGridItem[];
};
export type DashboardResponsiveLayouts = {
    /** Canonical authoring geometry. Existing v1 layout is treated as `wide`. */
    wide?: DashboardGridLayout;
    medium?: DashboardGridLayout;
    narrow?: DashboardGridLayout;
};
export interface DashboardDocument {
    version: 1 | 2;
    id: string;
    metadata: {
        title: string;
        description?: string;
        domain?: string;
        subdomain?: string;
        groups?: string[];
        audience?: string;
        visibility?: 'shared' | 'private' | 'template';
        lifecycle?: 'draft' | 'review' | 'certified' | 'deprecated';
        tags?: string[];
        businessOutcome?: string;
        businessOwner?: string;
        decisionUse?: string;
        reviewCadence?: string;
        businessRules?: string[];
        caveats?: string[];
    };
    params?: DashboardParam[];
    filters?: DashboardFilter[];
    /** Story layout sections (optional). Old dashboards simply have none. */
    sections?: DashboardSection[];
    /** Runtime story evidence contract. Result-specific prose is never persisted. */
    story?: DashboardStoryEvidencePlan;
    layout: DashboardGridLayout & {
        responsive?: DashboardResponsiveLayouts;
    };
}
export interface DashboardParseError {
    path: string;
    message: string;
}
export interface DashboardLoadResult {
    document: DashboardDocument | null;
    errors: DashboardParseError[];
}
export declare function parseDashboardDocument(text: string, path?: string): DashboardLoadResult;
export declare function loadDashboardDocument(filePath: string): DashboardLoadResult;
/** Return the absolute paths of every `.dqld` file under `<appDir>/dashboards/`. */
export declare function findDashboardsForApp(appDir: string): string[];
/** Return the absolute paths of every `.dqld` file under any `apps/<id>/dashboards/`. */
export declare function findAllDashboards(projectRoot: string): string[];
/** True when the layout item references a block by id (vs by path). */
export declare function isBlockIdRef(ref: DashboardBlockRef): ref is {
    blockId: string;
    version?: string;
};
/** Extract every block name/id referenced from a dashboard, regardless of ref form. */
export declare function extractDashboardBlockRefs(doc: DashboardDocument): {
    byId: string[];
    byPath: string[];
};
//# sourceMappingURL=dashboard-document.d.ts.map