@mono-lit/helper 0.0.0-stage → 0.0.2

package/dist/src/composables/rate-limit.d.ts

@@ -0,0 +1,108 @@
+import { ComplexAttributeConverter } from 'lit';
+/** `p-throttle` options we expose. Mirrors the upstream option names. */
+export interface ThrottleConfig {
+    /** Maximum number of calls within `interval`. Default 1. */
+    limit?: number;
+    /** Timespan for `limit`, in ms. Default 1000. */
+    interval?: number;
+    /** Throttle each call individually instead of using a window. Default false. */
+    strict?: boolean;
+}
+/** `p-debounce` options we expose. Mirrors the upstream option names. */
+export interface DebounceConfig {
+    /** Milliseconds to wait after the last call. Default 300. */
+    wait?: number;
+    /** Run on the leading edge instead of the trailing edge. Default false. */
+    before?: boolean;
+}
+/**
+ * What a rate-limit prop accepts: the config object, a bare number shorthand, a
+ * numeric/JSON string (the attribute form), or a falsy value meaning "off".
+ */
+export type RateLimitOption<C> = C | number | string | boolean | null | undefined;
+export type ResolvedThrottleConfig = Required<ThrottleConfig>;
+export type ResolvedDebounceConfig = Required<DebounceConfig>;
+/**
+ * Normalize a `throttle` prop. A bare number is the *interval*
+ * (`throttle="1000"` → at most one call per second), which is the reading
+ * people expect from `throttle={1000}` elsewhere. Returns `null` when
+ * throttling is off.
+ */
+export declare function normalizeThrottle(value: RateLimitOption<ThrottleConfig>): ResolvedThrottleConfig | null;
+/**
+ * Normalize a `debounce` prop. A bare number is the *wait*
+ * (`debounce="300"` → 300ms). Returns `null` when debouncing is off.
+ */
+export declare function normalizeDebounce(value: RateLimitOption<DebounceConfig>): ResolvedDebounceConfig | null;
+/**
+ * Lit `hasChanged` for a rate-limit prop.
+ *
+ * **This is load-bearing.** In a template, `:throttle.prop="{ limit: 1 }"`
+ * allocates a NEW object on every parent re-render. With Lit's default `!==`
+ * check the element would see a change each time, rebuild the wrapper, and
+ * restart the timer — so on a frequently re-rendering parent a debounced call
+ * could be postponed forever and never fire at all. Comparing by value makes a
+ * re-created but equivalent config a no-op.
+ */
+export declare function rateLimitHasChanged(value: unknown, old: unknown): boolean;
+/**
+ * Lit attribute converter for a rate-limit prop, so the shorthand attribute
+ * forms (`debounce="300"`, `throttle`, `debounce='{"wait":300}'`) work in plain
+ * HTML and SSR without a `.prop` binding.
+ */
+export declare const rateLimitConverter: ComplexAttributeConverter<unknown>;
+/**
+ * Lifecycle of a call through a limiter. `pending` covers the wait — the
+ * debounce timer or the throttle queue — and `running` covers the actual
+ * execution. Consumers typically paint a spinner for both but only block
+ * interaction for `running`, otherwise the first click locks the control and
+ * there is no burst left to collapse.
+ */
+export type RateLimitPhase = 'pending' | 'running' | 'idle';
+export interface RateLimiter {
+    /** Put a call through the limiter. Never rejects on cancellation. */
+    call(...args: unknown[]): Promise<unknown>;
+    /** Drop everything pending. The wrapper is rebuilt on the next `call()`. */
+    cancel(): void;
+    /** Cancel and release the wrapper (use on disconnect). */
+    dispose(): void;
+    /** Calls accepted but not yet settled (waiting *or* executing). */
+    readonly pending: number;
+    /** Calls currently executing `run`. */
+    readonly running: number;
+    /** Derived phase, for reporting. */
+    readonly phase: RateLimitPhase;
+    /** Calls waiting in the throttle queue (always 0 for a debouncer). */
+    readonly queueSize: number;
+}
+export interface CreateRateLimiterOptions {
+    kind: 'throttle' | 'debounce';
+    config: ResolvedThrottleConfig | ResolvedDebounceConfig;
+    /** The work to rate-limit. Its promise defines the `running` phase. */
+    run: (...args: unknown[]) => unknown | Promise<unknown>;
+    /** Called whenever `pending` / `running` change, so the host can re-render. */
+    onChange?: () => void;
+}
+/**
+ * Build a limiter around `run`.
+ *
+ * The wrapper is created lazily on the first `call()`, so nothing schedules a
+ * timer at construction time — important for SSR, where a limiter may be
+ * constructed but never called.
+ *
+ * `pending` counts calls that are still *waiting* — not merely unsettled. The
+ * distinction matters because a debounced burst collapses N calls into one
+ * execution and the losers only settle after it finishes: counting them as
+ * waiting would make the limiter report a phantom `pending` tail once the work
+ * was already done. So waiting is cleared when an execution starts (all of it
+ * for a debounce, one call for a throttle, whose queue really does keep
+ * waiting), and force-cleared whenever no call is outstanding at all — an
+ * invariant that also covers leading-edge debounces, where a trailing call
+ * settles without ever reaching `run`.
+ *
+ * Cancellation goes through an `AbortController`: both libraries take a
+ * `signal` and reject their pending promises when it fires. A signal is
+ * one-shot, so `cancel()` also drops the wrapper and the next `call()` rebuilds
+ * it with a fresh controller.
+ */
+export declare function createRateLimiter(options: CreateRateLimiterOptions): RateLimiter;

package/dist/src/composables/reactive.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Undoing framework reactivity, structurally.
+ *
+ * Vue wraps objects handed to a `ref()` / `reactive()` in a **Proxy**, and a proxy
+ * is a different object identity from the row it wraps. That matters here because
+ * `mono-select` / `mono-tag-input` use the **whole item as the model value** when
+ * no `key-value` is given, and identity is what decides "is this option already
+ * selected". The round trip is asymmetric:
+ *
+ * 1. the element emits the RAW item from its `items` array;
+ * 2. the consumer assigns it into a `ref`, and Vue wraps it;
+ * 3. Vue writes it back through `:model-value.prop` as a PROXY;
+ * 4. `proxy === rawItem` is `false`, and every comparison after that misses.
+ *
+ * Unwrapping both sides before comparing restores the identity the components
+ * rely on. Done by duck-typing Vue's own internal flags so this package still
+ * never imports Vue — the same trick `unwrapReactive` already used for
+ * DataSources, which is why that function now lives here.
+ */
+/**
+ * Unwrap a `ref()` / `computed()` wrapper and a `reactive()` proxy to the raw
+ * target underneath. Returns the value unchanged when it isn't reactive.
+ */
+export declare function unwrapReactive<T = unknown>(value: T): T;
+/**
+ * An option a controller re-reads at query time: the value itself, a getter, or
+ * a `{ value }` box — which is what a Vue `ref()` / `computed()` is, and what a
+ * plain `{ value }` a consumer keeps by hand is too.
+ *
+ * Framework-neutral on purpose. A controller cannot subscribe to a consumer's
+ * reactive state without importing their framework, but it does not need to:
+ * every query the components run (search, sort, page, header filter, scroll)
+ * goes through the controller, and reading the option fresh at that moment is
+ * what makes the CURRENT reactive value the one that lands in the request.
+ */
+export type MaybeReactive<T> = T | (() => T) | {
+    value: T;
+};
+/**
+ * Read a {@link MaybeReactive} option: call a getter, unwrap a ref/computed or a
+ * reactive proxy, unbox a plain `{ value }`. Never caches — the caller decides
+ * when "now" is.
+ */
+export declare function resolveMaybeReactive<T>(option: MaybeReactive<T> | undefined): T | undefined;
+/**
+ * {@link unwrapReactive}, then — for an **array** — unwrap each element too.
+ *
+ * Reading an index off a deep-reactive array yields a proxy of that element, so
+ * unwrapping only the container still leaves proxies inside. One level of
+ * elements is all the value models here need; this deliberately does not recurse
+ * into nested objects, which would rewrite data the consumer owns.
+ */
+export declare function unwrapReactiveDeep<T = unknown>(value: T): T;

package/dist/src/composables/shadow-css.d.ts

@@ -0,0 +1,42 @@
+import { LitElement } from 'lit';
+type Constructor<T = object> = new (...args: any[]) => T;
+export interface ToShadowCssOptions {
+    /**
+     * Element-selector tag to rewrite to `:host` (e.g. `'mono-nav'`). Handles
+     * `tag { … }`, `tag[attr] { … }` and `tag,` — but NOT `.tag` or `tag-suffix`.
+     */
+    host?: string;
+    /**
+     * Prepend `:host { display: <value> }`. Use when the component has no element
+     * selector to rewrite (its state classes live on an inner root) but the host
+     * still needs a display value (e.g. dropdown → `'inline-block'`).
+     */
+    hostDisplay?: string;
+    /** Shadow-only CSS appended verbatim (e.g. `[data-empty] { display: none }`). */
+    append?: string;
+}
+export declare function toShadowCss(css: string, opts?: ToShadowCssOptions): string;
+/**
+ * Adopt the page's icon utility CSS into `root` so `i-…` / `.mono-icon` glyphs
+ * render inside the shadow tree. Idempotent and SSR-safe (no-op on the server).
+ * Call from `firstUpdated` AND `updated` — early calls adopt the (live) shared
+ * sheet; later calls / the scheduled refresh repopulate it once UnoCSS loads.
+ */
+export declare function adoptIconStyles(root: ShadowRoot | null | undefined): void;
+/**
+ * Adopt the page's utility CSS into `root` so consumer `cssClass` utilities
+ * (UnoCSS etc.) render inside the shadow tree. Idempotent and SSR-safe (no-op on
+ * the server). Call from `firstUpdated` AND `updated` — early calls adopt the
+ * (live) shared sheet; the scheduled refresh repopulates it as UnoCSS loads.
+ */
+export declare function adoptUtilityStyles(root: ShadowRoot | null | undefined): void;
+/**
+ * Mixin for `*.shadow.ts` builds: adopts the page's utility CSS into the shadow
+ * root so consumer `cssClass` utilities (UnoCSS etc.) paint inside the tree.
+ * Uses a reactive controller (its `hostUpdated` runs after EVERY render), so it
+ * works regardless of whether a subclass overrides `updated`/`firstUpdated`.
+ * Client-only — skipped entirely on the server (SSR renders unstyled, utilities
+ * snap in on hydration). Apply as `extends withShadowUtilityStyles(XCore(LitElement))`.
+ */
+export declare function withShadowUtilityStyles<T extends Constructor<LitElement>>(superClass: T): T;
+export {};

package/dist/src/composables/visibility.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared `visible` / `visibleType` support for the controls `monoForm` drives.
+ *
+ * Lives here rather than in `form/form-types.ts` because that module already
+ * imports all ten component `*-types.ts` files — declaring the shared props
+ * there and importing them back would be circular.
+ */
+/**
+ * How a hidden control disappears.
+ *
+ * - `'none'` — `display: none`. The control is removed from layout, so it leaves
+ *   no gap in a grid/flex form.
+ * - `'invisible'` — `visibility: hidden`. The control keeps its space, so
+ *   toggling it doesn't shift everything around it.
+ */
+export type MonoVisibleType = 'invisible' | 'none';
+/** The two visibility props shared by every form-driven control. */
+export interface VisibilityProps {
+    /** Whether the control is shown. Defaults to `true`. */
+    visible?: boolean;
+    /** How it hides when `visible` is `false`. Defaults to `'none'`. */
+    visibleType?: MonoVisibleType;
+}
+/**
+ * Write (or clear) the hide style on a HOST element.
+ *
+ * Applied to the host, not to the rendered root: light builds render into `this`,
+ * so hiding the inner root would leave the `<mono-*>` host itself as a flex/grid
+ * item still occupying its cell. Targeting the host also means one code path
+ * covers the light build, the shadow build and whatever layout wraps them.
+ *
+ * Only ever touches the single property it owns, and only via `removeProperty` —
+ * never a blanket `cssText` reset — so an inline style the consumer put on the
+ * host survives a hide/show round trip.
+ */
+export declare function applyVisibility(host: HTMLElement, visible: boolean, type: MonoVisibleType): void;

package/dist/src/data/theme/index.d.ts

@@ -0,0 +1,30 @@
+import { FlavorName, ThemeName } from './presets';
+export interface ThemeConfig {
+    name: ThemeName;
+    displayName: string;
+}
+export interface FlavorConfig {
+    name: FlavorName;
+    displayName: string;
+}
+export declare const themes: Record<ThemeName, ThemeConfig>;
+export declare const flavors: Record<FlavorName, FlavorConfig>;
+export type ApplyThemeInput = ThemeName | {
+    color?: ThemeName;
+    flavor?: FlavorName;
+};
+export declare function applyTheme(input: ApplyThemeInput): void;
+export declare function applyFlavor(flavorName: FlavorName): void;
+export declare function getCurrentTheme(): ThemeName;
+export declare function getCurrentFlavor(): FlavorName;
+export declare function getThemeData(themeName: ThemeName): ThemeConfig | undefined;
+export declare function getFlavorData(flavorName: FlavorName): FlavorConfig | undefined;
+export declare function getAllThemes(): ThemeConfig[];
+export declare function getAllFlavors(): FlavorConfig[];
+export declare function isValidTheme(themeName: string): themeName is ThemeName;
+export declare function isValidFlavor(flavorName: string): flavorName is FlavorName;
+export declare function resetTheme(): void;
+export declare function resetFlavor(): void;
+export declare function createThemeClass(themeName: ThemeName): string;
+/** Structure class for a flavor — empty for `one` (the default, no class). */
+export declare function createFlavorClass(flavorName: FlavorName): string;

package/dist/src/data/theme/presets.d.ts

@@ -0,0 +1,94 @@
+/** Colour presets: ONE (the `:root` default) and Basecoat's own neutral palette. */
+export type ThemeName = 'basecoat' | 'one';
+/** `system` follows `prefers-color-scheme`; the others pin `html.dark` on/off. */
+export type ThemeMode = 'light' | 'dark' | 'system';
+/**
+ * The shadcn / Basecoat token set (`--background` … `--sidebar-ring`). Every
+ * key is optional except the six a palette cannot be derived without; the
+ * generator fills the rest (foregrounds by contrast, popover from card, …).
+ */
+export interface BasecoatTokens {
+    radius?: string;
+    background: string;
+    foreground: string;
+    card?: string;
+    cardForeground?: string;
+    popover?: string;
+    popoverForeground?: string;
+    primary: string;
+    primaryForeground?: string;
+    secondary?: string;
+    secondaryForeground?: string;
+    muted: string;
+    mutedForeground?: string;
+    accent?: string;
+    accentForeground?: string;
+    destructive: string;
+    destructiveForeground?: string;
+    border: string;
+    input?: string;
+    ring?: string;
+    chart1?: string;
+    chart2?: string;
+    chart3?: string;
+    chart4?: string;
+    chart5?: string;
+    sidebar?: string;
+    sidebarForeground?: string;
+    sidebarPrimary?: string;
+    sidebarPrimaryForeground?: string;
+    sidebarAccent?: string;
+    sidebarAccentForeground?: string;
+    sidebarBorder?: string;
+    sidebarRing?: string;
+}
+/** mono's extension roles — Basecoat has only `primary` + `destructive`. */
+export interface MonoRoleTokens {
+    success: string;
+    successForeground?: string;
+    warning: string;
+    warningForeground?: string;
+    info: string;
+    infoForeground?: string;
+    teal: string;
+    tealForeground?: string;
+    purple: string;
+    purpleForeground?: string;
+    neutral: string;
+    neutralForeground?: string;
+    dark: string;
+    darkForeground?: string;
+}
+export type ThemePalette = BasecoatTokens & MonoRoleTokens;
+export interface ThemeColors {
+    displayName: string;
+    /** Light-mode palette. For the `basecoat` preset only the extension roles are listed — the rest is Basecoat's own base.css. */
+    light: Partial<ThemePalette>;
+    /**
+     * Dark-mode overrides; a missing block is derived (see scripts/theme-build.mjs).
+     * `false` = the preset has no dark mode and keeps its light values under `html.dark`.
+     */
+    dark?: Partial<ThemePalette> | false;
+}
+export declare const themePresets: Record<ThemeName, ThemeColors>;
+/** ONE (the default) plus Basecoat's eight styles, mirrored 1:1 as opt-in flavors. */
+export type FlavorName = 'vega' | 'nova' | 'maia' | 'lyra' | 'mira' | 'luma' | 'sera' | 'rhea' | 'one';
+export declare const DEFAULT_THEME: ThemeName;
+export declare const DEFAULT_FLAVOR: FlavorName;
+/**
+ * A flavor is a Basecoat STYLE: it never changes tokens or fonts, only
+ * per-component metrics (the control ladder, radius steps, paddings, text
+ * sizes, whether a shadow is present). ONE is the default (index.css applies
+ * it at :root); every Basecoat style ships as `@mono-lit/helper/ui/theme/<name>.css`
+ * and is activated with `class="theme-<name>"`.
+ */
+export interface ThemeFlavor {
+    displayName: string;
+    /** One line on what the style changes against vega. */
+    summary: string;
+    /** The Basecoat style it mirrors (`one` is mono's own). */
+    vendor?: 'vega' | 'nova' | 'maia' | 'lyra' | 'mira' | 'luma' | 'sera' | 'rhea';
+    /** Control heights (xs … xxl) in rem — the `--mono-control-height-*` ladder. */
+    controlHeights: [number, number, number, number, number, number];
+}
+export declare const flavorPresets: Record<FlavorName, ThemeFlavor>;

package/dist/src/entries/index.d.ts

@@ -0,0 +1,2 @@
+/// <reference path="../../vue.d.ts" />
+export * from './index.node.js';

package/dist/src/entries/index.node.d.ts

@@ -0,0 +1,42 @@
+/// <reference path="../../vue.d.ts" />
+export { monoDataGrid, controlMonoTable } from '../components/table/mono-data-grid';
+export { setErrorMessages, resolveErrorMessages, describeError, errorStatus, normalizeError, DEFAULT_ERROR_MESSAGES } from '../utils/normalize-error';
+export { createMonoUI, getMonoUI, getMonoUIStatus, resetMonoUI } from '../composables/mono-ui';
+export type { MonoUI, MonoUIConfig, MonoUIComponents, MonoUIStatus } from '../composables/mono-ui';
+export { getMonoSkeletonStatus, resetMonoSkeleton, isMonoSsrApp } from '../composables/mono-skeleton';
+export type { MonoPending, MonoPendingOptions, MonoPhantomProps, MonoSkeletonDefaults, MonoSkeletonStatus, } from '../composables/mono-skeleton';
+export type { MonoErrorMessages, MonoErrorMessageKey, DescribedError } from '../utils/normalize-error';
+export { monoForm, controlMonoForm } from '../components/form/mono-form-controller';
+export type { MonoFormOptions, MonoFormController, MonoFormInput, MonoFormInputOf, MonoFormItem, MonoFormRule, MonoFormRuleCtx, MonoFormSchemaLike, MonoFormTiming, MonoFormValidation, MonoFormWatcherCtx, MonoFormComponent, MonoFormComponentProps, MonoFormProps, MonoFormSetProp, MonoFormSetValidation, MonoFormRefLike, } from '../components/form/form-types';
+export { monoModal, controlMonoModal } from '../components/modal/mono-modal-controller';
+export type { MonoModalOptions, MonoModalController, MonoDialogOptions, MonoDialogButton, MonoDialogButtonCtx, MonoDialogController, } from '../components/modal/modal-types';
+export { monoArraySource } from '../components/table/array-source';
+export { buildGroups, flattenLeaves, isGroupNode, collectGroupPaths } from '../components/table/grouping';
+export { isPath, parseFieldPath, getFieldValue, setFieldValue, mergePatch, toODataSelector, toODataClause, } from '../search/field-path';
+export type { FieldSegment, ParsedFieldPath, ODataClause } from '../search/field-path';
+export { monoChart, controlMonoChart } from '../components/chart/mono-data-chart';
+export { buildChartApply, buildChartOdataRequest, composeApply } from '../components/chart/chart-odata';
+export type { MonoChartOdataRequest } from '../components/chart/chart-odata';
+export type { MonoChartAgg, MonoChartController, MonoChartData, MonoChartDataset, MonoChartOptions, MonoChartOdataOptions, MonoChartAggregateCtx, MonoChartProps, MonoChartPointEvent, MonoChartSeries, MonoChartSource, MonoChartType, } from '../components/chart/chart-types';
+export { monoFilterBuilder, controlMonoFilterBuilder } from '../components/filter/filter-builder';
+export { arrayToODataString, arrayToTree, odataStringToArray, treeToArray, } from '../components/filter/filter-odata';
+export { DEFAULT_TEXTS as MONO_FILTER_TEXTS, OPERATOR_ARITY as MONO_FILTER_OPERATOR_ARITY, operatorsFor as monoFilterOperatorsFor, } from '../components/filter/filter-operators';
+export type { MonoFilterBuilderOptions, MonoFilterBuilderProps, MonoFilterController, MonoFilterDataType, MonoFilterExpression, MonoFilterField, MonoFilterGroup, MonoFilterGroupOperator, MonoFilterNode, MonoFilterOperator, MonoFilterOutput, MonoFilterChangeEvent, MonoFilterApplyEvent, MonoFilterClearEvent, MonoFilterChangeEventDetail, MonoFilterClearEventDetail, FilterBuilderEvents, MonoFilterProps, MonoFilterReadOptions, MonoFilterRule, MonoFilterSize, MonoFilterTexts, } from '../components/filter/filter-types';
+export { monoDataDropdown, controlMonoDataDropdown } from '../components/dropdown-table/mono-data-dropdown';
+export type { MonoDropdownController, MonoDropdownItem, MonoDataDropdownOptions, } from '../components/dropdown-table/mono-data-dropdown';
+export { controlMonoTooltip, monoTooltip, destroyAllMonoTooltips, createMonoTooltip, resetMonoTooltip, getMonoTooltipGlobal, } from '../components/tooltip/index';
+export type { MonoTooltipOptions, MonoTooltipGlobalOptions, MonoTooltipGlobal, MonoTooltipController, MonoTooltipTarget, MonoTooltipContent, MonoTooltipPlacement, MonoTooltipTrigger, MonoTooltipVariant, MonoTooltipColor, MonoTooltipSize, } from '../components/tooltip/index';
+export * from '../data/theme/index';
+export * from '../data/theme/presets';
+export { resolveMaybeReactive } from '../composables/reactive';
+export type { MaybeReactive } from '../composables/reactive';
+export type { MonoEventProps } from '../composables/element-props';
+export type { MonoArraySourceOptions } from '../components/table/array-source';
+export type { MonoGroupNode } from '../components/table/grouping';
+export type { SortOrder, GroupPageInfo, MonoDisplayRow, MonoGroupMeta, MonoServerGroupCtx, MonoServerGroupSource, MonoSummaryType, MonoSummarySpec, MonoSummaryFieldSpec, MonoSummaryConfig, MonoSummaryRecalculate, MonoSummaryResult, MonoSummaryHandle, MonoColumnDef, MonoColumnHandle, MonoTableProps, MonoTableColumnProps, MonoSearchTerm, MonoDetailEl, MonoDetailHandle, MonoCheckMode, MonoCheckConfig, MonoCheckHandle, } from '../components/table/mono-data-grid';
+export type { MonoSearchCustomCtx, MonoSearchCustomResult, MonoSearchExpr, MonoSearchExprCustom, MonoSearchExprEntry, } from '../search/search-expr';
+export { DEFAULT_SEARCH_OPERATION, SEARCH_FIELDS_KEYS, parseSearchValue, mergeSearchFields, resolveSearchFields, isFoldableSearch, plainSearchFields, readSearchField, searchRowPredicate, searchRemoteFilter, MonoSourceSearch, } from '../search/data-search';
+export type { MonoSearchValue, MonoSearchFieldsAliases, ResolveSearchFieldsOptions, ApplySourceSearchOptions, SearchableSource, } from '../search/data-search';
+export type { MonoExportColumn, MonoExportDetail, MonoExportDetailBatch, MonoExportFormat, MonoExportFormatOptions, MonoExportOptions, MonoExportResult, MonoExportStyle, MonoExportStyles, } from '../export/types';
+export type { MonoImportAmbiguity, MonoImportChange, MonoImportColumn, MonoImportMatch, MonoImportNumberFormat, MonoImportOptions, MonoImportRejection, MonoImportResult, MonoImportType, MonoImportValueType, } from '../import/types';
+export type { MonoTableController, MonoGridSource, MonoDataGridOptions, MonoDataSourceOptions, MonoOdataOptions, MonoDistinctValuesContext, TableSearchProps, TablePagingProps, TablePageSizeProps, TableInfoProps, TableSortProps, TableThProps, TableThSort, TableLoadingProps, TableSummaryProps, TableDetailProps, TableCheckboxProps, } from '../components/table/table-types';

package/dist/src/entries/search.d.ts

@@ -0,0 +1,3 @@
+/// <reference path="../../vue.d.ts" />
+export { odataSearchExpr } from '../search/odata-search.js';
+export type { MonoODataSearchOptions } from '../search/odata-search.js';

package/dist/src/export/detail.d.ts

@@ -0,0 +1,29 @@
+import { MonoExportDetail } from './types';
+/** One document's resolved rows, plus the key that names its sheet. */
+export interface ResolvedDetail {
+    /** The master row it came from. */
+    row: Record<string, unknown>;
+    /** The value of `detail.key` on that row, as a string. */
+    key: string;
+    rows: unknown[];
+}
+/** A document that will get no sheet, and why. */
+export interface SkippedDetail {
+    key: string;
+    reason: 'empty' | 'failed';
+    /** Present when `reason` is `failed`. */
+    error?: unknown;
+}
+export interface ResolveDetailResult {
+    details: ResolvedDetail[];
+    skipped: SkippedDetail[];
+}
+/**
+ * Turn master rows into per-document detail rows.
+ *
+ * A document with no rows is reported in `skipped` rather than given an empty
+ * sheet — an empty worksheet behind a link is worse than no link, and the
+ * caller gets told which documents those were instead of having to diff the
+ * tab list.
+ */
+export declare function resolveDetails(masterRows: unknown[], detail: MonoExportDetail): Promise<ResolveDetailResult>;

package/dist/src/export/download.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Browser download helper. Kept separate (and DOM-guarded) so the report engine
+ * can still render on a server — where `download()` is simply a no-op warning
+ * rather than a crash.
+ */
+/** MIME type per output format. */
+export declare const MIME: Record<string, string>;
+/** Save a Blob to disk via a transient `<a download>`. Browser only. */
+export declare function downloadBlob(blob: Blob, fileName: string): void;

package/dist/src/export/excel/index.d.ts

@@ -0,0 +1,27 @@
+import { Root } from 'mdast';
+import { MonoExportOptions } from '../types';
+/** What a template writes to link at a sheet it cannot yet name. */
+export declare const SHEET_LINK_PREFIX = "sheet:";
+/** One extra worksheet: a parsed detail report plus the key that links to it. */
+export interface RenderExcelSheet {
+    /** The value the master template linked to, i.e. `sheet:<key>`. */
+    key: string;
+    /** Preferred name. Sanitised and de-duplicated before use. */
+    name: string;
+    ast: Root;
+}
+/**
+ * Options the driver reads.
+ *
+ * Spelled out rather than `Pick<>`-ed from a list that has to be kept in step:
+ * an option added to `MonoExportOptions` and not here silently never reaches
+ * the driver, and nothing fails to compile.
+ */
+export interface RenderExcelOptions extends Pick<MonoExportOptions, 'styles' | 'columns' | 'sheetName' | 'freezeRows'> {
+    /** Extra sheets, rendered after the master and linked from it. */
+    sheets?: RenderExcelSheet[];
+    /** Add a `← Back` link to `A1` of every extra sheet. */
+    back?: boolean;
+}
+/** Build the ExcelJS workbook for a parsed report. */
+export declare function renderExcel(ast: Root, options?: RenderExcelOptions): Promise<any>;

package/dist/src/export/excel/nodes.d.ts

@@ -0,0 +1,123 @@
+import { Root } from 'mdast';
+import { ExcelCellStyle } from '../styles';
+import { MonoExportColumn, MonoExportStyles } from '../types';
+/** A pending image to place once the sheet is written. */
+interface PendingImage {
+    src: string;
+    row: number;
+    col: number;
+    width: number;
+    height: number;
+}
+/** A block that should span the sheet's full width (headings, paragraphs). */
+interface PendingSpan {
+    row: number;
+    from: number;
+}
+export interface WriterContext {
+    styles: MonoExportStyles;
+    columns?: MonoExportColumn[];
+}
+/** Everything the walk produces, handed back to the ExcelJS driver. */
+export interface WorksheetPlan {
+    rows: PlannedRow[];
+    images: PendingImage[];
+    /** Rows to merge across the sheet width (heading / paragraph blocks). */
+    spans: PendingSpan[];
+    /** Explicit merges requested with `{{merge}}`: `[row, col, rowEnd, colEnd]`. */
+    merges: Array<[number, number, number, number]>;
+    /** Widest row, i.e. how many columns the sheet has. */
+    width: number;
+    /** Longest rendered text per column, for auto-fit. */
+    widths: number[];
+}
+export interface PlannedCell {
+    /** The value written into the cell (already typed). */
+    value: string | number | Date | null;
+    /** An Excel formula, replacing `value` when present. */
+    formula?: string;
+    style: ExcelCellStyle;
+    /** Number format from a value directive, layered over the style's. */
+    numFmt?: string;
+    /**
+     * A hyperlink target, straight from the Markdown link the template wrote.
+     *
+     * `sheet:<key>` is resolved to an in-workbook reference once every sheet
+     * exists and its final (sanitised, deduped) name is known — a template cannot
+     * know that name, so it references the key instead. Anything else is passed
+     * through as an external URL.
+     */
+    hyperlink?: string;
+    /**
+     * How wide the cell *displays*, in characters — used for auto-fit. Kept
+     * separate from `value` because a Date's `toString()` is ~55 characters while
+     * the cell shows 10, which would blow the column out.
+     */
+    width: number;
+}
+export interface PlannedRow {
+    cells: PlannedCell[];
+    height?: number;
+}
+/**
+ * Walks an mdast tree and plans a worksheet. Planning (rather than writing
+ * ExcelJS objects directly) keeps this file free of any ExcelJS import, so the
+ * mapping stays testable and a future renderer can reuse the same walk.
+ */
+export declare class WorksheetWriter {
+    private readonly ctx;
+    private readonly plan;
+    /** Header captions of the table currently being written, for `{col:Field}`. */
+    private tableColumns;
+    /** 1-based row index of the current table's first body row. */
+    private tableFirstRow;
+    /** 1-based row index of the current table's last body row. */
+    private tableLastRow;
+    constructor(ctx: WriterContext);
+    /** Resolve a named style, or an empty style when the name is unknown. */
+    private named;
+    write(root: Root): WorksheetPlan;
+    private writeBlocks;
+    private writeBlock;
+    private writeBlockquote;
+    /** A one-cell row that will later be merged across the sheet's full width. */
+    private appendSpanningRow;
+    private writeTable;
+    /** Per-column `numFmt` override from `options.columns`. */
+    private columnStyle;
+    /** Collect `{{style}}` directives into one style object. */
+    private styleFrom;
+    /** Collect `{{rowStyle}}` directives into one style object. */
+    private rowStyleFrom;
+    /** Build one planned cell from flattened inline content plus its style. */
+    private toCell;
+    /**
+     * Substitute the placeholders a template couldn't resolve on its own:
+     * `{row}` (the row about to be written), `{prevRow}` (the one above it),
+     * `{firstRow}` / `{lastRow}` (the current table's body range) and
+     * `{col:Caption}` (that header's column letter).
+     *
+     * `{lastRow}` includes *every* body row — so a total row that lives inside
+     * the same Markdown table must sum `{firstRow}:{prevRow}` to avoid a circular
+     * reference to itself.
+     */
+    private resolveFormula;
+    private placeImages;
+    private applyMerge;
+    /**
+     * Append a row and return its 1-based index. `spanning` rows (headings,
+     * paragraphs) are excluded from auto-fit: they get merged across the whole
+     * sheet, so letting a long title set column A's width would leave a 60-wide
+     * first column next to four narrow ones.
+     */
+    private pushRow;
+}
+/**
+ * Give a plain cell string its most useful type. Text that merely *looks*
+ * numeric (`"00123"`, `"1,234"`) is left alone — coercing it would silently
+ * mangle invoice numbers and phone numbers.
+ */
+export declare function coerceValue(text: string): string | number | Date | null;
+/** 1-based column index → spreadsheet letter (1 → A, 27 → AA). */
+export declare function columnLetter(index: number): string;
+export {};

package/dist/src/export/expression.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Template source preprocessing — everything that must happen *before*
+ * Handlebars sees the template.
+ *
+ * Two rewrites live here, both driven by the same single-pass scanner so that
+ * fenced code blocks and inline code spans are never touched (a template that
+ * *documents* `{{= … }}` in a code block must keep it verbatim):
+ *
+ * 1. `{{= expr }}` → `{{__jexl "expr"}}` — Handlebars has no `{{=` syntax at
+ *    all (it's a parse error), so inline expressions are rewritten into a call
+ *    to the Jexl helper.
+ * 2. Mustaches on a GFM **table row** are wrapped in `{{esc …}}`, so a value
+ *    containing a `|` can't split the cell and shift every column after it.
+ *    `{{{triple}}}` opts out.
+ */
+/**
+ * Evaluate one Jexl expression.
+ *
+ * Jexl is used instead of `eval()` so a template can never reach globals, the
+ * DOM, or `fetch` — the worst a malicious template can do is compute a wrong
+ * number.
+ */
+export declare function evaluateExpression(expression: string, context: unknown): unknown;
+/**
+ * Rewrite a template's mustaches. Single pass, line-aware (for table rows) and
+ * code-aware (fenced blocks + inline spans are copied verbatim).
+ */
+export declare function preprocessTemplate(src: string, opts?: {
+    escapeTableCells?: boolean;
+}): string;
+/**
+ * Escape an interpolated value for a GFM table cell. Registered as the `esc`
+ * helper and applied automatically to table-row mustaches by
+ * {@link preprocessTemplate}; also callable by hand.
+ */
+export declare function escapeForCell(value: unknown): string;