@bitcobblers/wod-wiki-ui 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,882 @@
+import { QueryOptions, QueryResult, ParsedFindQuery, FindOptions, FindQueryResult, ParsedRowsQuery, RowsQueryResult, ParsedQuery, DashboardToken, DashboardDocument, DashboardWidget, Series, RowsRun } from '@bitcobblers/wod-wiki-wql';
+export { FindOptions, FindQueryResult, ParsedFindQuery, ParsedQuery, ParsedRowsQuery, QueryOptions, QueryResult, RowsQueryResult, RowsRun } from '@bitcobblers/wod-wiki-wql';
+import * as react from 'react';
+import { ReactNode, ComponentType } from 'react';
+import { Segment, StoredOutputStatement, BlockIndexRow, ScriptBlock, ICodeStatement, IMetric } from '@bitcobblers/wod-wiki-core';
+import * as _codemirror_state from '@codemirror/state';
+import { Extension, Facet, EditorState, StateField } from '@codemirror/state';
+import { ViewPlugin, DecorationSet, ViewUpdate, EditorView, Decoration, WidgetType } from '@codemirror/view';
+import { Diagnostic } from '@codemirror/lint';
+import { CompletionContext, CompletionResult } from '@codemirror/autocomplete';
+import { ClassValue } from 'clsx';
+
+interface QueryExecutor {
+    runQuery(query: string, options?: QueryOptions): Promise<QueryResult>;
+    runFind(parsed: ParsedFindQuery, options?: FindOptions): Promise<FindQueryResult>;
+    runRows(parsed: ParsedRowsQuery, options?: {
+        anchorNow?: number;
+    }): Promise<RowsQueryResult>;
+    run?(parsed: ParsedQuery, options?: QueryOptions): Promise<QueryResult>;
+}
+
+interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem?(key: string): void;
+}
+
+declare const CODEMIRROR_SINGLETON_DEPS: readonly ["@codemirror/autocomplete", "@codemirror/commands", "@codemirror/lang-markdown", "@codemirror/language", "@codemirror/lint", "@codemirror/search", "@codemirror/state", "@codemirror/theme-one-dark", "@codemirror/view", "@lezer/common", "@lezer/highlight", "@lezer/lr", "@lezer/markdown"];
+
+interface WidgetFrameProps {
+    title: string;
+    question: string;
+    query: string;
+    span?: string;
+    children: ReactNode;
+}
+declare function WidgetFrame({ title, question, query, span, children }: WidgetFrameProps): react.JSX.Element;
+
+interface QueryValueProps {
+    result: QueryResult;
+    unit?: string;
+    label: string;
+    thresholds?: {
+        green: [number, number];
+        red: [number, number];
+    };
+}
+declare function QueryValue({ result, unit: unitProp, label, thresholds }: QueryValueProps): react.JSX.Element;
+
+interface WqlTimeseriesProps {
+    result: QueryResult;
+    unit?: string;
+}
+declare function WqlTimeseries({ result, unit: unitProp }: WqlTimeseriesProps): react.JSX.Element;
+
+interface WqlBarsProps {
+    result: QueryResult;
+    unit?: string;
+}
+declare function WqlBars({ result, unit: unitProp }: WqlBarsProps): react.JSX.Element;
+
+interface WqlTableProps {
+    result: QueryResult;
+    unit?: string;
+}
+declare function WqlTable({ result, unit: unitProp }: WqlTableProps): react.JSX.Element;
+
+interface WidgetChartProps {
+    /** Raw widget type from the fence suffix; '' picks the dashboard default (table). */
+    type: string;
+    result: QueryResult | undefined;
+    /** Fallback label for value widgets (widget title or metric). */
+    label?: string;
+    unit?: string;
+    /** Positional widget parameters from the block body (e.g. goal target or zone targets). */
+    params?: string[];
+}
+declare function WidgetChart({ type, result, label, unit, params }: WidgetChartProps): react.JSX.Element;
+declare function WidgetProblemBadge({ message }: {
+    message: string;
+}): react.JSX.Element;
+declare function ProposedMetricBadge({ metric }: {
+    metric: string;
+}): react.JSX.Element;
+
+interface DashboardTokenControlsProps {
+    tokens: DashboardToken[];
+    /** Current value per token name (defaults applied by the caller). */
+    values: Record<string, string>;
+    /** Present when the note is editable — changes write back to frontmatter. */
+    onChange?: (name: string, value: string) => void;
+}
+/**
+ * DashboardTokenControls — the control row a dashboard note's frontmatter
+ * tokens render as (#899): scalar tokens become inputs, list tokens segmented
+ * controls (first entry = default). Read-only views (no onChange) render the
+ * current values as static text.
+ */
+declare function DashboardTokenControls({ tokens, values, onChange }: DashboardTokenControlsProps): react.JSX.Element | null;
+
+interface DashboardViewProps {
+    /** Parsed dashboard note (buildDashboardDocument). */
+    document: DashboardDocument;
+    /** Injected QueryExecutor for executing WQL queries. Zero singleton coupling. */
+    executor?: QueryExecutor;
+    /** Optional rollup fact warmer callback. */
+    onEnsureRollupFacts?: () => Promise<void>;
+    /** Current token values; defaults to each token's declared default. */
+    tokenValues?: Record<string, string>;
+    /** Present when the note is editable — control changes write back to frontmatter. */
+    onTokenChange?: (name: string, value: string) => void;
+    /** Present when the host offers query editing (composer modal owned by the host). */
+    onEditQuery?: (widget: DashboardWidget) => void;
+    /** Optional execution range (ms epoch). Omit to use each query's own window. */
+    rangeStart?: number;
+    rangeEnd?: number;
+    preferredUnit?: string;
+}
+/**
+ * DashboardView — the state-free dashboard renderer (#900, format locked in #899).
+ *
+ * Takes a parsed DashboardDocument + current token values, runs all widget
+ * queries concurrently via the injected QueryExecutor, and renders the responsive CSS grid.
+ */
+declare function DashboardView({ document, executor, onEnsureRollupFacts, tokenValues, onTokenChange, onEditQuery, rangeStart, rangeEnd, preferredUnit, }: DashboardViewProps): react.JSX.Element;
+
+interface WqlEmptyStateProps {
+    result: QueryResult | undefined;
+    className?: string;
+}
+declare function WqlEmptyState({ result, className }: WqlEmptyStateProps): react.JSX.Element | null;
+
+interface TopListProps {
+    result: QueryResult;
+    unit?: string;
+    limit?: number;
+}
+declare function TopList({ result, unit: unitProp, limit }: TopListProps): react.JSX.Element;
+
+interface StackedBarProps {
+    result: QueryResult;
+    unit?: string;
+}
+declare function StackedBar({ result, unit: unitProp }: StackedBarProps): react.JSX.Element;
+
+interface GoalRingsProps {
+    result: QueryResult | undefined;
+    params?: string[];
+    label?: string;
+    unit?: string;
+}
+declare function GoalRings({ result, params, label, unit }: GoalRingsProps): react.JSX.Element;
+
+interface ZoneDistributionProps {
+    result: QueryResult | undefined;
+    params?: string[];
+    unit?: string;
+}
+declare function ZoneDistribution({ result, params }: ZoneDistributionProps): react.JSX.Element;
+
+type AnalyticsRangeWeeks = 4 | 8 | 16;
+interface RangeSelectorProps {
+    weeks?: number;
+    onWeeksChange?: (weeks: number) => void;
+    className?: string;
+}
+declare function RangeSelector({ weeks: weeksProp, onWeeksChange, className }: RangeSelectorProps): react.JSX.Element;
+
+interface AnalyticsQueryDef {
+    key: string;
+    query: string;
+}
+interface AnalyticsQueriesState {
+    results: Record<string, QueryResult>;
+    loading: boolean;
+}
+declare function useAnalyticsQueries(queries: AnalyticsQueryDef[], weeks: number, executor?: QueryExecutor, refreshKey?: number, preferredUnit?: string, onEnsureRollupFacts?: () => Promise<void>): AnalyticsQueriesState;
+
+type ChartShape = {
+    kind: 'error';
+    message: string;
+} | {
+    kind: 'empty';
+} | {
+    kind: 'scalar';
+    value: number;
+} | {
+    kind: 'bars';
+} | {
+    kind: 'timeseries';
+};
+declare function useChartShape(result: QueryResult | undefined): ChartShape;
+
+/** Series palette for analytics charts — maps onto the metric token set. */
+declare const SERIES_COLORS: string[];
+
+interface MergedPoint {
+    ts: number;
+    [label: string]: number | string;
+}
+declare function mergeSeries(series: Series[]): MergedPoint[];
+declare function compactNumber(value: number): string;
+declare function formatTimestamp(ts: number): string;
+declare function tooltipTimestamp(ts: number): string;
+
+declare const ANALYTICS_UNIT_STORAGE_KEY = "wod.analytics.unit";
+declare const DEFAULT_ANALYTICS_UNIT = "kg";
+type AnalyticsUnit = 'kg' | 'lb';
+declare function readStoredUnit(storage?: StorageLike): AnalyticsUnit;
+declare function useAnalyticsUnitPreference(customStorage?: StorageLike): {
+    unit: AnalyticsUnit;
+    setUnit: (next: AnalyticsUnit) => void;
+    toggleUnit: () => void;
+};
+declare function getEffectiveAnalyticsUnit(query: string, preferredUnit: AnalyticsUnit): {
+    unit: AnalyticsUnit;
+    forced: boolean;
+};
+declare function getDashboardEffectiveUnit(queries: AnalyticsQueryDef[], preferredUnit: AnalyticsUnit): {
+    unit: AnalyticsUnit;
+    forced: boolean;
+};
+interface AnalyticsUnitPreferenceProps {
+    className?: string;
+    unit?: AnalyticsUnit;
+    forced?: boolean;
+    storage?: StorageLike;
+}
+declare function AnalyticsUnitPreference({ className, unit: unitProp, forced, storage }: AnalyticsUnitPreferenceProps): react.JSX.Element;
+
+interface RowsTableProps {
+    result: RowsQueryResult;
+    /** Optional per-run chrome rendered inside the section header (#948 RPE). */
+    renderRunHeaderExtra?: (run: RowsRun) => ReactNode;
+    /** Optional segment grid renderer (e.g. app's ReviewGrid). Default: clean plain table rows. */
+    renderSegments?: (segments: Segment[], run: RowsRun) => ReactNode;
+}
+declare function RowsTable({ result, renderRunHeaderExtra, renderSegments, }: RowsTableProps): react.JSX.Element;
+
+interface QueryBlockViewProps {
+    /** Raw text between the ```query fences — the WQL query string or block source. */
+    query: string;
+    /** Injected QueryExecutor for executing WQL queries (zero singleton coupling). */
+    executor?: QueryExecutor;
+    /** Optional callback or subscription hook for when a result is saved, replacing hardcoded resultRecorder coupling. */
+    onResultSaved?: (callback: () => void) => (() => void) | void;
+    /** Present when the query block is editable — opens the WQL composer. */
+    onSaveQuery?: (nextQuery: string) => void;
+    /** When multiple queries appear in one block, the index of this query. */
+    queryIndex?: number;
+    /** When true, editing the query is disallowed. */
+    readOnly?: boolean;
+    /** Fence-suffix widget type override (e.g. `query:chart`, `query:value`). */
+    widgetType?: string;
+    /** Frontmatter/syntax parse error for the enclosing widget block. */
+    widgetError?: string;
+    /** Token values from the note's frontmatter, for `$token` substitution. */
+    tokenValues?: Record<string, string>;
+    /** Optional RPE capture handler. */
+    onCaptureRpe?: (resultId: string, rpe: number) => Promise<void>;
+    /** Optional custom segment grid renderer. */
+    renderSegments?: (segments: Segment[], run: RowsRun) => React.ReactNode;
+}
+declare function QueryBlockView({ query, executor, onResultSaved, onSaveQuery, queryIndex: _queryIndex, readOnly, widgetType, widgetError, tokenValues, onCaptureRpe, renderSegments, }: QueryBlockViewProps): react.JSX.Element;
+
+declare function readSessionRpe(logs: StoredOutputStatement[] | undefined): number | undefined;
+interface RowsResultsChromeProps {
+    /** The session result id from the written `rows:{result:…}` query. */
+    resultId: string;
+    /** The session-scoped rows result (one run). */
+    sessionResult: RowsQueryResult;
+    /** Injected QueryExecutor for widened query execution. */
+    executor?: QueryExecutor;
+    /** Optional RPE capture handler. */
+    onCaptureRpe?: (resultId: string, rpe: number) => Promise<void>;
+    /** Re-run the parent query after a capture so the grid reflects the RPE. */
+    onCaptured?: () => void;
+    /** Optional segment grid renderer. */
+    renderSegments?: (segments: Segment[], run: RowsRun) => React.ReactNode;
+}
+declare function RowsResultsChrome({ resultId, sessionResult, executor, onCaptureRpe, onCaptured, renderSegments, }: RowsResultsChromeProps): react.JSX.Element;
+
+interface WqlQueryInspectorModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    initialQuery: string;
+    onApply: (newQuery: string) => void;
+    title?: string;
+    subtitle?: string;
+    executor?: QueryExecutor;
+}
+declare function WqlQueryInspectorModal({ isOpen, onClose, initialQuery, onApply, title, subtitle, executor, }: WqlQueryInspectorModalProps): react.JSX.Element | null;
+
+type AnyParsedQuery = ParsedQuery | ParsedFindQuery | ParsedRowsQuery;
+type WqlExecutor = (ast: AnyParsedQuery) => Promise<FindQueryResult | QueryResult>;
+type WqlStageCounts = {
+    kind: 'find';
+    selected: number;
+    matched: number;
+} | {
+    kind: 'aggregate';
+    selected: number;
+    buckets: number;
+    aggregated: number;
+    groups: number;
+};
+declare const DEFAULT_DIAGNOSTICS_DEBOUNCE_MS = 150;
+declare function useWqlStageCounts(ast: AnyParsedQuery, valid: boolean, execute: WqlExecutor | undefined, debounceMs?: number): WqlStageCounts | undefined;
+
+/**
+ * Shared query-clause model + WQL compiler for the WqlComposer.
+ *
+ * Source-pivot model (issue #838, decision #836): a single `source` head
+ * slot — journal | collections | feeds | notes | blocks | efforts | metrics —
+ * pivots the query kind. Content sources compile the `find:` skeleton; `metrics`
+ * compiles the aggregate skeleton (`agg:metric{filters} by {dims}.rollup(p)
+ * [in unit] [where find:…]`). The find target and scope are derived from the
+ * source value (the legacy `target`/`scope` clause types are retired).
+ *
+ * Static option lists live here; dynamic typeahead data sources live in
+ * ./suggestionSources (issue #831). All vocab is sourced from the canonical
+ * modules (@bitcobblers/wod-wiki-engine) — never hardcoded in the composer (decision #824).
+ *
+ * Supports freeform token slots, placeholder guidance, and keyboard navigation.
+ */
+type ClauseType = 'source' | 'text' | 'catalog' | 'tag' | 'effort' | 'discipline' | 'intensity' | 'origin' | 'type' | 'has' | 'time' | 'where' | 'agg' | 'metric' | 'groupby' | 'rollup' | 'unit' | 'result' | 'block' | 'note' | 'output';
+interface QueryClause {
+    id: string;
+    /** Built-in ClauseType or a custom slot type id from the ComposerRegistry. */
+    type: string;
+    label: string;
+    value: string;
+    inputType?: 'radio' | 'freetext' | 'select';
+    placeholder?: string;
+    icon?: string;
+    prefix?: string;
+}
+/** Content sources compile `find:note in <scope>`; notes/blocks use `all`. */
+declare const CONTENT_SOURCES: ("journal" | "collections" | "feeds" | "notes" | "blocks" | "efforts")[];
+/** The plane a source value belongs to — everything but `metrics` is content. */
+declare function sourcePlane(source: string): 'content' | 'metrics';
+declare const SOURCE_OPTIONS: {
+    value: string;
+    label: string;
+    description: string;
+}[];
+declare const TIME_OPTIONS: {
+    value: string;
+    label: string;
+}[];
+/** Aggregate head vocab — canonical homes (decision #824). */
+declare const AGG_OPTIONS: {
+    value: "max" | "min" | "sum" | "avg" | "count" | "last" | "delta";
+    label: "max" | "min" | "sum" | "avg" | "count" | "last" | "delta";
+}[];
+declare const ROLLUP_OPTIONS: {
+    value: "1d" | "1w";
+    label: string;
+}[];
+declare const GROUPBY_OPTIONS: {
+    value: "result" | "day" | "origin" | "page" | "round" | "metric" | "note" | "week" | "effort" | "discipline" | "intensity" | "block" | "session" | "grain" | "tags";
+    label: "result" | "day" | "origin" | "page" | "round" | "metric" | "note" | "week" | "effort" | "discipline" | "intensity" | "block" | "session" | "grain" | "tags";
+}[];
+declare const METRIC_OPTIONS: {
+    value: "totalVolume" | "totalDistance" | "tis" | "sessionLoad" | "reps" | "distance" | "resistance" | "elapsed" | "power" | "pace" | "calc.metMinutes" | "calc.acwr" | "calc.monotony" | "calc.strain" | "calc.e1rm" | "calc.ctl" | "calc.atl" | "calc.tsb" | "calc.soreness" | "calc.sleep" | "calc.hrv" | "calc.readiness" | "calc.mvcBw" | "calc.ef" | "calc.adherence" | "calc.pct1rm" | "calc.sends";
+    label: "totalVolume" | "totalDistance" | "tis" | "sessionLoad" | "reps" | "distance" | "resistance" | "elapsed" | "power" | "pace" | "calc.metMinutes" | "calc.acwr" | "calc.monotony" | "calc.strain" | "calc.e1rm" | "calc.ctl" | "calc.atl" | "calc.tsb" | "calc.soreness" | "calc.sleep" | "calc.hrv" | "calc.readiness" | "calc.mvcBw" | "calc.ef" | "calc.adherence" | "calc.pct1rm" | "calc.sends";
+}[];
+declare const UNIT_OPTIONS: {
+    value: "kg" | "lb";
+    label: "kg" | "lb";
+}[];
+/**
+ * Where-join editor vocab — the same source of truth the analytics composer
+ * completes against (src/parser/wql-language.ts, aggregators from the AST
+ * contract in services/analytics/query/wql.ts). Issue #831.
+ */
+declare const WHERE_AGGREGATORS: readonly string[];
+declare const WHERE_METRICS: readonly string[];
+declare const WHERE_OPERATORS: readonly string[];
+interface ClauseMeta {
+    label: string;
+    inputType: 'radio' | 'freetext' | 'select';
+    placeholder: string;
+    placeholderText: string;
+    icon: string;
+    description: string;
+    prefix?: string;
+    required?: boolean;
+}
+declare const CLAUSE_META: Record<ClauseType, ClauseMeta>;
+/**
+ * Metadata lookup for pills, popovers, and menus: built-in clauses come from
+ * CLAUSE_META; custom slot types resolve through the ComposerRegistry;
+ * anything else gets a generic fallback so a stale clause still renders.
+ */
+declare function getClauseMeta(type: string): ClauseMeta;
+/**
+ * Maps a single clause to its WQL fragment syntax.
+ */
+declare function clauseToWql(clause: QueryClause): {
+    key?: string;
+    filterStr?: string;
+};
+/**
+ * Composes a full WQL string from an array of QueryClauses.
+ *
+ * Content planes: find:<target>{<filters>} in <scope> [last <n><unit>] [where <join>]
+ *   — target/scope derived from `source` (journal|collections|feeds → note in
+ *   <source>; notes → note in all; blocks → block in all; anything else →
+ *   note in <verbatim value>, the salvage path for exotic scopes).
+ * Metrics plane:   <agg>:<metric>{<filters>} [by {<dims>}] [.rollup(<p>)] [in <unit>] [where <find join>]
+ */
+declare function clausesToWql(clauses: QueryClause[]): string;
+/**
+ * Restore composer clauses from a WQL string — the inverse of
+ * `clausesToWql`, used to hydrate composer state from the URL.
+ *
+ * Unlike `parseQuery`, this is a *salvage* parser: it mirrors the compiler's
+ * structure on both planes without validating the fragments, so composer-
+ * reachable states that are WQL-invalid (e.g. `text:hello world`, a `1m`
+ * rollup period, an empty metric) still restore exactly — the diagnostics
+ * strip then attributes the parse error to the offending slot.
+ *
+ * Returns null when the string cannot be a composer product: a negated
+ * filter, or an unknown/custom-less filter key.
+ */
+declare function wqlToClauses(wql: string): QueryClause[] | null;
+/**
+ * Set the aggregate metric, re-basing the clause list on the metrics plane
+ * when needed (sidebar / launcher flows, issue #839): content planes pivot
+ * via `pivotClauses` (shared filters survive), a missing source or metric
+ * clause is seeded, and the metric value lands on the first metric clause.
+ */
+declare function setMetricClause(clauses: QueryClause[], metric: string): QueryClause[];
+/**
+ * Re-base the clause list on a new source value (decision #836): shared
+ * filter clauses survive the pivot; kind-specific clauses are dropped
+ * (content plane: time/where and any metrics head; metrics plane: time/
+ * where). Pivoting to metrics seeds the head slots (agg=sum, metric empty
+ * for placeholder guidance).
+ */
+declare function pivotClauses(clauses: QueryClause[], source: string): QueryClause[];
+declare function defaultClauses(): QueryClause[];
+/** Default clauses for aggregate/metrics queries (source=metrics, agg=sum, empty metric). */
+declare function defaultMetricsClauses(): QueryClause[];
+/**
+ * Value of the first clause of `type`, trimmed, or `fallback` when absent or
+ * empty. Mirrors the lookup/defaulting `clausesToWql` performs, so consumers
+ * (e.g. the Library shelf) share one defaulting rule with the compiler.
+ */
+declare function clauseValue(clauses: QueryClause[], type: string, fallback?: string): string;
+
+interface WqlValidationState {
+    /** True when the composed WQL parses without error. */
+    valid: boolean;
+    /** Parser error message when invalid. */
+    error?: string;
+}
+interface WqlComposerProps {
+    /** Seed clauses for uncontrolled usage. Defaults to source/time. */
+    initialClauses?: QueryClause[];
+    /** Controlled clauses. When provided, the component does not own clause state. */
+    clauses?: QueryClause[];
+    /** Fired whenever the clause list changes (add / edit / remove). */
+    onClausesChange?: (clauses: QueryClause[]) => void;
+    /** Fired (including on mount) with the composed WQL string. */
+    onWqlChange?: (wql: string) => void;
+    /** Fired (including on mount) with parse validation state. */
+    onValidationChange?: (state: WqlValidationState) => void;
+    /** Fired (including on mount) with the parsed AST. */
+    onAstChange?: (ast: AnyParsedQuery) => void;
+    /**
+     * Fired on Enter when no free text is pending — the run-on-submit signal
+     * for hosts like the analytics explorer. Receives the composed WQL.
+     */
+    onSubmit?: (wql: string) => void;
+    /** Render the diagnostics strip (badge, AST summary, stage counts). Default true. */
+    showDiagnostics?: boolean;
+    /**
+     * Executor for live stage counts in the diagnostics strip.
+     */
+    execute?: WqlExecutor;
+    /** Debounce for live execution feedback. Default 150ms. */
+    debounceMs?: number;
+    /** Extension point: extra content rendered inside the bar, after the free-text input. */
+    customSlots?: ReactNode;
+    /** Host actions appended on the diagnostics line. */
+    diagnosticsActions?: ReactNode;
+    /**
+     * Clause types kept in the model but NOT rendered as pills.
+     */
+    hiddenClauseTypes?: ClauseType[];
+    /** Focus the free-text input on mount. */
+    autoFocus?: boolean;
+    /** Free-text input placeholder. */
+    placeholder?: string;
+    className?: string;
+}
+declare function WqlComposer({ initialClauses, clauses: controlledClauses, onClausesChange, onWqlChange, onValidationChange, onAstChange, onSubmit, showDiagnostics, execute, debounceMs, customSlots, diagnosticsActions, hiddenClauseTypes, autoFocus, placeholder, className, }: WqlComposerProps): react.JSX.Element;
+
+interface CustomSlotEditorProps<TValue> {
+    value: TValue | undefined;
+    onChange: (value: TValue) => void;
+    onClose: () => void;
+}
+interface CustomSlotDefinition<TValue = unknown> {
+    type: string;
+    label: string;
+    icon: string;
+    placeholder: string;
+    placeholderText: string;
+    description: string;
+    Editor: ComponentType<CustomSlotEditorProps<TValue>>;
+    wqlGenerator: (value: TValue) => string;
+    formatValue?: (value: TValue) => string;
+    parseValue?: (raw: string) => TValue | undefined;
+    validate?: (value: TValue) => string | null;
+    wqlValidator?: (wql: string) => string | null;
+    plane?: 'content' | 'metrics' | 'both';
+}
+declare class ComposerRegistry {
+    private readonly slots;
+    private readonly listeners;
+    private cachedList;
+    registerSlot<TValue>(def: CustomSlotDefinition<TValue>): () => void;
+    unregisterSlot(type: string): void;
+    getSlot(type: string): CustomSlotDefinition<any> | undefined;
+    listSlots(): CustomSlotDefinition<any>[];
+    getAllSlots(): CustomSlotDefinition<any>[];
+    subscribe(listener: () => void): () => void;
+    private notify;
+}
+declare const composerRegistry: ComposerRegistry;
+declare function useComposerSlots(registry?: ComposerRegistry): CustomSlotDefinition<any>[];
+
+interface TokenSlotPillProps {
+    clause: QueryClause;
+    isActive?: boolean;
+    invalid?: boolean;
+    invalidReason?: string;
+    onClick?: () => void;
+    onRemove?: () => void;
+    onChange?: (patch: Partial<QueryClause>) => void;
+    compact?: boolean;
+    placeholderOverride?: string;
+}
+declare function TokenSlotPill({ clause, isActive, invalid, invalidReason, onClick, onRemove, onChange, compact, placeholderOverride, }: TokenSlotPillProps): react.JSX.Element;
+declare const MULTI_VALUE_TYPES: Record<string, true>;
+declare function ClausePopover({ clause, onClose, onChange, }: {
+    clause: QueryClause;
+    onClose: () => void;
+    onChange: (patch: Partial<QueryClause>) => void;
+}): react.JSX.Element;
+declare function CustomSlotPopover<TValue>({ clause, definition, onClose, onChange, }: {
+    clause: QueryClause;
+    definition: CustomSlotDefinition<TValue>;
+    onClose: () => void;
+    onChange: (value: TValue) => void;
+}): react.JSX.Element;
+declare function AddFilterDropdown({ clauses, onAdd, }: {
+    clauses: QueryClause[];
+    onAdd: (clause: QueryClause) => void;
+}): react.JSX.Element;
+declare function AddCalcDropdown({ clauses, onAdd, }: {
+    clauses: QueryClause[];
+    onAdd: (clause: QueryClause) => void;
+}): react.JSX.Element | null;
+
+interface DateRange {
+    start: string;
+    end: string;
+}
+declare const dateRangeSlot: CustomSlotDefinition<DateRange>;
+
+interface SuggestionItem {
+    value: string;
+    label?: string;
+    description?: string;
+    icon?: string;
+}
+type SuggestionCachePolicy = 'static' | {
+    ttlMs: number;
+};
+interface SuggestionBinding {
+    load: () => Promise<SuggestionItem[]>;
+    cache: SuggestionCachePolicy;
+    open: boolean;
+    emptyText: string;
+}
+declare function tagsFromStaticBlocks(blocks: BlockIndexRow[]): string[];
+declare function catalogIdsFromBlocks(blocks: BlockIndexRow[]): string[];
+declare function blockTypesFromBlocks(blocks: BlockIndexRow[]): string[];
+declare function mergeTagSuggestions(userLabels: string[], corpusLabels: string[]): string[];
+declare const SUGGESTION_BINDINGS: Record<string, SuggestionBinding>;
+declare function setSuggestionBinding(type: string, binding: SuggestionBinding | undefined): void;
+declare function getSuggestionBinding(type: string): SuggestionBinding | undefined;
+declare function loadSuggestions(type: string): Promise<SuggestionItem[]>;
+declare function invalidateSuggestions(type?: string): void;
+
+interface ClauseSuggestions {
+    items: SuggestionItem[];
+    /** True while the first load for this slot is in flight. */
+    loading: boolean;
+    /** The slot's binding (cache policy, open flag, empty-state copy). */
+    binding?: SuggestionBinding;
+}
+declare function useSuggestions(type: string): ClauseSuggestions;
+
+interface WqlDiagnostics {
+    valid: boolean;
+    /** The composed WQL string for the current clause set. */
+    wql: string;
+    ast: AnyParsedQuery;
+    error?: string;
+    offendingClauseId?: string;
+}
+interface WqlFindSummary {
+    target: string;
+    scope: string;
+    timeWindow?: string;
+    hasJoin: boolean;
+    filterCount: number;
+}
+declare function summarizeFind(ast: ParsedFindQuery): WqlFindSummary;
+interface WqlAggregateSummary {
+    agg: string;
+    metric: string;
+    groupBy?: string;
+    rollup?: string;
+    unit?: string;
+    timeWindow?: string;
+    hasJoin: boolean;
+    filterCount: number;
+}
+declare function summarizeAggregate(ast: ParsedQuery): WqlAggregateSummary;
+declare function diagnoseClauses(clauses: QueryClause[]): WqlDiagnostics;
+
+interface WqlDiagnosticsStripProps {
+    diagnostics: WqlDiagnostics;
+    offendingLabel?: string;
+    stages?: WqlStageCounts;
+    actions?: ReactNode;
+    className?: string;
+}
+declare function WqlDiagnosticsStrip({ diagnostics, offendingLabel, stages, actions, className, }: WqlDiagnosticsStripProps): react.JSX.Element;
+
+declare function editorTheme(isDark: boolean): Extension;
+
+/**
+ * Extension that adds ID attributes to line elements in the editor.
+ */
+declare const lineIdsExtension: ViewPlugin<{
+    decorations: DecorationSet;
+    update(update: ViewUpdate): void;
+    getDecorations(view: EditorView): _codemirror_state.RangeSet<Decoration>;
+}, undefined>;
+
+type NavigationHook = (url: string, view: EditorView) => void;
+declare const navigationFacet: Facet<NavigationHook, NavigationHook | null>;
+declare function urlAtPos(view: EditorView, pos: number): string | null;
+declare const linkOpen: Extension;
+
+declare function findWorkoutErrors(content: string, offsetInDoc: number): Diagnostic[];
+declare function workoutLintSource(view: EditorView): Diagnostic[];
+declare const wodLinter: _codemirror_state.Extension;
+
+declare function fenceCompletion(context: CompletionContext): CompletionResult | null;
+declare function wrapInTimeFence(view: EditorView): boolean;
+declare function handleFenceAutoWrap(event: InputEvent, view: EditorView): boolean;
+declare const wodAutoWrap: Extension;
+declare const wodEditorKeymap: Extension;
+declare const wodAutocompletion: Extension;
+
+type EditorDialect = "time" | "log";
+type EditorSectionType = "markdown" | "time" | "log" | "frontmatter" | "code" | "widget" | "embed" | "query";
+type EditorSectionSubtype = "heading" | "paragraph" | "list" | "blockquote" | "table" | "unknown";
+type EmbedType = "image" | "link" | "youtube";
+interface EditorSection {
+    id: string;
+    type: EditorSectionType;
+    subtype?: EditorSectionSubtype;
+    from: number;
+    to: number;
+    startLine: number;
+    endLine: number;
+    contentFrom?: number;
+    contentTo?: number;
+    sport?: string;
+    widgetName?: string;
+    contentId?: string;
+    queryType?: string;
+    queryError?: string;
+    embed?: {
+        type: EmbedType;
+        url: string;
+        label: string;
+        videoId?: string;
+        height?: number;
+    };
+}
+interface SectionState {
+    sections: EditorSection[];
+}
+declare const forceSectionParse: _codemirror_state.StateEffectType<null>;
+declare function blockContentId(content: string): string;
+declare const sectionField: StateField<SectionState>;
+declare function sectionAtPos(state: EditorState, pos: number): EditorSection | null;
+declare function activeCursorSection(state: EditorState): EditorSection | null;
+
+interface SectionRect {
+    sectionId: string;
+    top: number;
+    height: number;
+    type: EditorSection["type"];
+    subtype?: EditorSection["subtype"];
+    widgetName?: string;
+}
+type GeometryListener = (rects: SectionRect[], docVersion: number) => void;
+declare class SectionGeometryPlugin {
+    private view;
+    rects: SectionRect[];
+    docVersion: number;
+    private listeners;
+    constructor(view: EditorView);
+    update(update: ViewUpdate): void;
+    addListener(fn: GeometryListener): () => void;
+    private measure;
+    private notify;
+    destroy(): void;
+}
+declare const sectionGeometry: ViewPlugin<SectionGeometryPlugin, undefined>;
+
+declare const previewDecorations: Extension;
+
+declare const embedPreviewDecorations: Extension;
+
+declare class DefaultFrontmatterWidget extends WidgetType {
+    readonly props: Record<string, string>;
+    constructor(props: Record<string, string>);
+    eq(other: DefaultFrontmatterWidget): boolean;
+    toDOM(): HTMLElement;
+}
+declare const frontmatterPreviewField: StateField<DecorationSet>;
+declare const frontmatterPreview: Extension;
+
+declare function markdownSyntaxHiding(): Extension;
+
+declare const markdownTablePreview: Extension;
+
+declare const setGutterHighlights: _codemirror_state.StateEffectType<Set<number>>;
+declare const gutterHighlightsField: StateField<Set<number>>;
+declare const gutterUnified: (_codemirror_state.Extension | StateField<Set<number>>)[];
+declare function dispatchGutterHighlights(view: EditorView, lineNumbers: number[]): void;
+
+type ButtonAction = (action: string, params: Record<string, string>) => void;
+declare function inlineButtonDecoration(onAction: ButtonAction): Extension;
+
+interface RuntimePanelEntry {
+    sectionId: string;
+    block: ScriptBlock;
+    afterPos: number;
+    expanded?: boolean;
+}
+declare const addRuntimePanel: _codemirror_state.StateEffectType<RuntimePanelEntry>;
+declare const removeRuntimePanel: _codemirror_state.StateEffectType<{
+    sectionId: string;
+}>;
+declare const expandRuntimePanel: _codemirror_state.StateEffectType<{
+    sectionId: string;
+    expanded: boolean;
+}>;
+declare const runtimePanelField: StateField<Map<string, RuntimePanelEntry>>;
+declare function dispatchAddRuntimePanel(view: EditorView, sectionId: string, block: ScriptBlock, afterPos: number, expanded?: boolean): void;
+declare function dispatchRemoveRuntimePanel(view: EditorView, sectionId: string): void;
+declare function dispatchExpandRuntimePanel(view: EditorView, sectionId: string, expanded: boolean): void;
+
+declare function sessionQueryWql(resultId: string): string;
+declare function sessionQueryInsert(state: EditorState, blockId: string, resultId: string, runBlock?: {
+    id?: string;
+    contentId?: string;
+}): {
+    from: number;
+    insert: string;
+} | null;
+
+declare const smartIncrement: Extension;
+
+interface OverlayAction {
+    label: string;
+    icon: string;
+    action: (view: EditorView, section: EditorSection) => void;
+}
+declare function configureOverlayActions(actions: OverlayAction[]): void;
+declare function getOverlayActions(): OverlayAction[];
+declare const wodOverlayPanel: Extension;
+
+interface CursorFocusState {
+    sectionId: string;
+    section: EditorSection;
+    lineFrom: number;
+    docLine: number;
+    statementIndex: number;
+    statement: ICodeStatement;
+    focusedMetric: IMetric | null;
+    focusedMetricIndex: number;
+    allStatements: ICodeStatement[];
+}
+declare function getCursorFocusState(state: EditorState): CursorFocusState | null;
+declare const cursorFocusExtension: Extension;
+
+interface QueryBlockPreviewOptions {
+    executor?: QueryExecutor;
+    onResultSaved?: (callback: () => void) => (() => void) | void;
+    readOnly?: boolean;
+    onSaveQuery?: (sectionId: string, nextQuery: string) => void;
+}
+declare function saveBlockQuerySource(view: EditorView, sectionId: string, newQuery: string, queryIndex?: number): {
+    ok: boolean;
+    patchedContent?: string;
+    message?: string;
+};
+declare function findQueryBlockSection(view: EditorView, sectionId: string): EditorSection | null;
+declare function queryBlockPreview(options?: QueryBlockPreviewOptions): Extension;
+
+/** Parsed JSON object passed into a widget component. */
+type WidgetConfig = Record<string, unknown>;
+/** Props passed to every registered widget component. */
+interface WidgetProps {
+    /** Parsed JSON object from the fenced widget body. */
+    config: WidgetConfig;
+    /** Exact source text between the opening and closing fences. */
+    rawContent: string;
+    /** Stable section identifier generated by section-state.ts. */
+    sectionId: string;
+}
+/** Registry of widget names to React components. */
+type WidgetRegistry = Map<string, react.ComponentType<WidgetProps>>;
+/** Effect to toggle edit mode for a specific widget block */
+declare const toggleWidgetEdit: _codemirror_state.StateEffectType<{
+    sectionId: string;
+    editing: boolean;
+}>;
+/** StateField to track which widgets are currently being edited as raw text */
+declare const editingWidgetsField: StateField<Set<string>>;
+/**
+ * Create a CM6 Extension that replaces widget fenced blocks with React components.
+ * Block decorations MUST come from a StateField (not a ViewPlugin) per CM6 constraints.
+ */
+declare function widgetBlockPreview(registry: WidgetRegistry): Extension;
+
+interface EditorPresetOptions {
+    dialect?: 'wod' | 'whiteboard' | 'wql' | 'markdown' | string;
+    isDark?: boolean;
+    readOnly?: boolean;
+    lineNumbers?: boolean;
+    lineWrapping?: boolean;
+    executor?: QueryExecutor;
+    onResultSaved?: (callback: () => void) => (() => void) | void;
+    extensions?: Extension[];
+}
+declare function editorPreset(optionsOrDialect?: string | EditorPresetOptions): Extension[];
+
+declare function cn(...inputs: ClassValue[]): string;
+declare function hashCode(str: string): number;
+
+/**
+ * blockQueryPatcher — utilities to extract and patch WQL queries inside ```query
+ * fenced block sources (#842).
+ *
+ * Supports both plain line queries and structured YAML key-value blocks.
+ * Preserves sibling keys, comments, formatting, and quotes when patching.
+ */
+interface ExtractedQuery {
+    queryIndex: number;
+    query: string;
+    isYamlKey: boolean;
+    lineIndex: number;
+}
+declare function extractBlockQueries(blockContent: string): ExtractedQuery[];
+declare function patchBlockQuery(blockContent: string, newQuery: string, queryIndex?: number): string;
+
+export { AGG_OPTIONS, ANALYTICS_UNIT_STORAGE_KEY, AddCalcDropdown, AddFilterDropdown, type AnalyticsQueriesState, type AnalyticsQueryDef, type AnalyticsRangeWeeks, type AnalyticsUnit, AnalyticsUnitPreference, type AnalyticsUnitPreferenceProps, type ButtonAction, CLAUSE_META, CODEMIRROR_SINGLETON_DEPS, CONTENT_SOURCES, type ChartShape, type ClauseMeta, ClausePopover, type ClauseSuggestions, type ClauseType, ComposerRegistry, type CursorFocusState, type CustomSlotDefinition, type CustomSlotEditorProps, CustomSlotPopover, DEFAULT_ANALYTICS_UNIT, DEFAULT_DIAGNOSTICS_DEBOUNCE_MS, DashboardTokenControls, type DashboardTokenControlsProps, DashboardView, type DashboardViewProps, type DateRange, DefaultFrontmatterWidget, type EditorDialect, type EditorPresetOptions, type EditorSection, type EditorSectionSubtype, type EditorSectionType, type EmbedType, type ExtractedQuery, GROUPBY_OPTIONS, type GeometryListener, GoalRings, type GoalRingsProps, METRIC_OPTIONS, MULTI_VALUE_TYPES, type MergedPoint, type NavigationHook, type OverlayAction, ProposedMetricBadge, type QueryBlockPreviewOptions, QueryBlockView, type QueryBlockViewProps, type QueryClause, type QueryExecutor, QueryValue, type QueryValueProps, ROLLUP_OPTIONS, RangeSelector, type RangeSelectorProps, RowsResultsChrome, type RowsResultsChromeProps, RowsTable, type RowsTableProps, type RuntimePanelEntry, SERIES_COLORS, SOURCE_OPTIONS, SUGGESTION_BINDINGS, type SectionRect, type SectionState, StackedBar, type StackedBarProps, type StorageLike, type SuggestionBinding, type SuggestionCachePolicy, type SuggestionItem, TIME_OPTIONS, TokenSlotPill, type TokenSlotPillProps, TopList, type TopListProps, UNIT_OPTIONS, WHERE_AGGREGATORS, WHERE_METRICS, WHERE_OPERATORS, WidgetChart, type WidgetChartProps, type WidgetConfig, WidgetFrame, type WidgetFrameProps, WidgetProblemBadge, type WidgetProps, type WidgetRegistry, type WqlAggregateSummary, WqlBars, type WqlBarsProps, WqlComposer, type WqlComposerProps, type WqlDiagnostics, WqlDiagnosticsStrip, type WqlDiagnosticsStripProps, WqlEmptyState, type WqlEmptyStateProps, type WqlExecutor, type WqlFindSummary, WqlQueryInspectorModal, type WqlQueryInspectorModalProps, type WqlStageCounts, WqlTable, type WqlTableProps, WqlTimeseries, type WqlTimeseriesProps, type WqlValidationState, ZoneDistribution, type ZoneDistributionProps, activeCursorSection, addRuntimePanel, blockContentId, blockTypesFromBlocks, catalogIdsFromBlocks, clauseToWql, clauseValue, clausesToWql, cn, compactNumber, composerRegistry, configureOverlayActions, cursorFocusExtension, dateRangeSlot, defaultClauses, defaultMetricsClauses, diagnoseClauses, dispatchAddRuntimePanel, dispatchExpandRuntimePanel, dispatchGutterHighlights, dispatchRemoveRuntimePanel, editingWidgetsField, editorPreset, editorTheme, embedPreviewDecorations, expandRuntimePanel, extractBlockQueries, fenceCompletion, findQueryBlockSection, findWorkoutErrors, forceSectionParse, formatTimestamp, frontmatterPreview, frontmatterPreviewField, getClauseMeta, getCursorFocusState, getDashboardEffectiveUnit, getEffectiveAnalyticsUnit, getOverlayActions, getSuggestionBinding, gutterHighlightsField, gutterUnified, handleFenceAutoWrap, hashCode, inlineButtonDecoration, invalidateSuggestions, lineIdsExtension, linkOpen, loadSuggestions, markdownSyntaxHiding, markdownTablePreview, mergeSeries, mergeTagSuggestions, navigationFacet, patchBlockQuery, pivotClauses, previewDecorations, queryBlockPreview, readSessionRpe, readStoredUnit, removeRuntimePanel, runtimePanelField, saveBlockQuerySource, sectionAtPos, sectionField, sectionGeometry, sessionQueryInsert, sessionQueryWql, setGutterHighlights, setMetricClause, setSuggestionBinding, smartIncrement, sourcePlane, summarizeAggregate, summarizeFind, tagsFromStaticBlocks, toggleWidgetEdit, tooltipTimestamp, urlAtPos, useAnalyticsQueries, useAnalyticsUnitPreference, useChartShape, useComposerSlots, useSuggestions, useWqlStageCounts, widgetBlockPreview, wodAutoWrap, wodAutocompletion, wodEditorKeymap, wodLinter, wodOverlayPanel, workoutLintSource, wqlToClauses, wrapInTimeFence };