@mono-lit/helper 0.0.2 → 0.0.3

package/dist/src/import/types.d.ts

@@ -1,3 +1,4 @@
+//#region src/import/types.d.ts
 /**
  * Public types for `table.import()` — reading an edited spreadsheet back into
  * the grid as *staged* changes.
@@ -10,144 +11,145 @@ export type MonoImportValueType = 'string' | 'number' | 'date' | 'boolean';
 export type MonoImportNumberFormat = 'auto' | 'us' | 'eu';
 /** One leg of the composite key that pairs a sheet row with a table row. */
 export interface MonoImportMatch<T = any> {
-    /** Header text in the sheet. */
-    excel: string;
-    /** Field on the table row. */
-    field: string;
-    /**
-     * Normalise this key part before comparing — applied to **both** sides, so a
-     * sheet's `"  PT  Mono "` can match a row's `"PT Mono"`. Runs on top of the
-     * default normalisation (trim, collapse whitespace, lowercase).
-     */
-    transform?: (value: unknown, side: 'excel' | 'table') => unknown;
+  /** Header text in the sheet. */
+  excel: string;
+  /** Field on the table row. */
+  field: string;
+  /**
+   * Normalise this key part before comparing — applied to **both** sides, so a
+   * sheet's `"  PT  Mono "` can match a row's `"PT Mono"`. Runs on top of the
+   * default normalisation (trim, collapse whitespace, lowercase).
+   */
+  transform?: (value: unknown, side: 'excel' | 'table') => unknown;
 }
 /** A column the sheet is allowed to write into a matched row. */
 export interface MonoImportColumn<T = any> {
-    /** Header text in the sheet. */
-    excel: string;
-    /** Field on the table row to stage. */
+  /** Header text in the sheet. */
+  excel: string;
+  /** Field on the table row to stage. */
+  field: string;
+  /** How to interpret the cell (default `'string'`). */
+  type?: MonoImportValueType;
+  /** Post-process the parsed value; return `undefined` to skip the cell. */
+  transform?: (value: unknown, ctx: {
+    row: T;
     field: string;
-    /** How to interpret the cell (default `'string'`). */
-    type?: MonoImportValueType;
-    /** Post-process the parsed value; return `undefined` to skip the cell. */
-    transform?: (value: unknown, ctx: {
-        row: T;
-        field: string;
-        raw: unknown;
-    }) => unknown;
+    raw: unknown;
+  }) => unknown;
 }
 /** A sheet row that produced no staged change, and why. */
 export interface MonoImportRejection {
-    /** Zero-based index within the sheet's data rows. */
-    index: number;
-    /** The sheet row as `{ header: value }`. */
-    row: Record<string, unknown>;
-    /** Human-readable cause. */
-    reason?: string;
+  /** Zero-based index within the sheet's data rows. */
+  index: number;
+  /** The sheet row as `{ header: value }`. */
+  row: Record<string, unknown>;
+  /** Human-readable cause. */
+  reason?: string;
 }
 /** A sheet row that matched more than one table row. */
 export interface MonoImportAmbiguity extends MonoImportRejection {
-    /** How many table rows the strongest usable key resolved to. */
-    candidates: number;
+  /** How many table rows the strongest usable key resolved to. */
+  candidates: number;
 }
 /** One row's staged patch. */
 export interface MonoImportChange<T = any> {
-    /** The controller's string row key. */
-    rowKey: string;
-    /** The row's `keyExpr` value, for a store update. */
-    key: unknown;
-    /** The matched table row (pre-change). */
-    row: T;
-    /** field → new value. */
-    patch: Record<string, unknown>;
+  /** The controller's string row key. */
+  rowKey: string;
+  /** The row's `keyExpr` value, for a store update. */
+  key: unknown;
+  /** The matched table row (pre-change). */
+  row: T;
+  /** field → new value. */
+  patch: Record<string, unknown>;
 }
 export interface MonoImportOptions<T = any> {
-    /** The spreadsheet file, or the text pasted out of one. */
-    data: File | Blob | ArrayBuffer | Uint8Array | string;
-    /** Force the reader; inferred from `data` when omitted. */
-    type?: MonoImportType;
-    /** Worksheet name or zero-based index (`'excel'` only; default: the first). */
-    sheet?: string | number;
-    /** 1-based row holding the headers (default `1`). */
-    headerRow?: number;
-    /** Column delimiter for pasted text. Auto-detects tab / `;` / `,`. */
-    delimiter?: string;
-    /**
-     * Composite key pairing a sheet row with a table row. Required — an import
-     * with no key would have nowhere to put its values.
-     */
-    match: Array<MonoImportMatch<T>>;
-    /** The columns the sheet may write. Required. */
-    columns: Array<MonoImportColumn<T>>;
-    /** Extra header spellings to accept, e.g. `{ 'JAN': ['Januari', 'Jan-26'] }`. */
-    headerAliases?: Record<string, string[]>;
-    /**
-     * Smallest number of key fields allowed to identify a row (default `2`).
-     * Raise it when a single shared field would produce false matches.
-     */
-    minKeyFields?: number;
-    /** Override key normalisation (applied to both sides). */
-    normalizeKey?: (value: unknown) => string;
-    /**
-     * Rows to match against. Defaults to every row the grid can produce
-     * (`table.getData()`), not just the visible page.
-     */
-    target?: T[];
-    /** Skip sheet rows — summary/total lines, blank separators, … */
-    rowFilter?: (sheetRow: Record<string, unknown>, index: number) => boolean;
-    /** Restrict which table rows may be written at all. */
-    targetFilter?: (row: T) => boolean;
-    /**
-     * Veto a write. Return `true` (or a string reason) to refuse. The reason is
-     * surfaced in `skippedRows`, so the user can be told *which* rows were
-     * ignored and why instead of silently losing them.
-     */
-    readOnly?: (row: T, field: string) => boolean | string;
-    /**
-     * `'stage'` (default) writes the changes into the grid's staged buffer.
-     * `'none'` computes everything and hands back `result.apply()`, so the result
-     * can be validated — and the import abandoned — before anything is staged.
-     */
-    apply?: 'stage' | 'none';
-    /** Decimal/grouping convention for `number` columns (default `'auto'`). */
-    numberFormat?: MonoImportNumberFormat;
-    /** Accept negative numbers, including `(1.234)` (default `true`). */
-    allowNegative?: boolean;
-    /** Sheet rows processed between yields (default `300`). */
-    chunkSize?: number;
-    /** Milliseconds to yield between chunks so the UI stays responsive (default `0`). */
-    yieldMs?: number;
-    /** Progress across the sheet's data rows. */
-    onProgress?: (done: number, total: number) => void;
-    /** Log matching decisions to the console. */
-    debug?: boolean;
+  /** The spreadsheet file, or the text pasted out of one. */
+  data: File | Blob | ArrayBuffer | Uint8Array | string;
+  /** Force the reader; inferred from `data` when omitted. */
+  type?: MonoImportType;
+  /** Worksheet name or zero-based index (`'excel'` only; default: the first). */
+  sheet?: string | number;
+  /** 1-based row holding the headers (default `1`). */
+  headerRow?: number;
+  /** Column delimiter for pasted text. Auto-detects tab / `;` / `,`. */
+  delimiter?: string;
+  /**
+   * Composite key pairing a sheet row with a table row. Required — an import
+   * with no key would have nowhere to put its values.
+   */
+  match: Array<MonoImportMatch<T>>;
+  /** The columns the sheet may write. Required. */
+  columns: Array<MonoImportColumn<T>>;
+  /** Extra header spellings to accept, e.g. `{ 'JAN': ['Januari', 'Jan-26'] }`. */
+  headerAliases?: Record<string, string[]>;
+  /**
+   * Smallest number of key fields allowed to identify a row (default `2`).
+   * Raise it when a single shared field would produce false matches.
+   */
+  minKeyFields?: number;
+  /** Override key normalisation (applied to both sides). */
+  normalizeKey?: (value: unknown) => string;
+  /**
+   * Rows to match against. Defaults to every row the grid can produce
+   * (`table.getData()`), not just the visible page.
+   */
+  target?: T[];
+  /** Skip sheet rows — summary/total lines, blank separators, … */
+  rowFilter?: (sheetRow: Record<string, unknown>, index: number) => boolean;
+  /** Restrict which table rows may be written at all. */
+  targetFilter?: (row: T) => boolean;
+  /**
+   * Veto a write. Return `true` (or a string reason) to refuse. The reason is
+   * surfaced in `skippedRows`, so the user can be told *which* rows were
+   * ignored and why instead of silently losing them.
+   */
+  readOnly?: (row: T, field: string) => boolean | string;
+  /**
+   * `'stage'` (default) writes the changes into the grid's staged buffer.
+   * `'none'` computes everything and hands back `result.apply()`, so the result
+   * can be validated — and the import abandoned — before anything is staged.
+   */
+  apply?: 'stage' | 'none';
+  /** Decimal/grouping convention for `number` columns (default `'auto'`). */
+  numberFormat?: MonoImportNumberFormat;
+  /** Accept negative numbers, including `(1.234)` (default `true`). */
+  allowNegative?: boolean;
+  /** Sheet rows processed between yields (default `300`). */
+  chunkSize?: number;
+  /** Milliseconds to yield between chunks so the UI stays responsive (default `0`). */
+  yieldMs?: number;
+  /** Progress across the sheet's data rows. */
+  onProgress?: (done: number, total: number) => void;
+  /** Log matching decisions to the console. */
+  debug?: boolean;
 }
 export interface MonoImportResult<T = any> {
-    /** Every considered sheet row matched exactly one table row. */
-    ok: boolean;
-    /** Sheet rows considered (after `rowFilter`). */
-    total: number;
-    /** Rows that resolved to exactly one table row. */
-    matched: number;
-    /** Rows that resolved to none. */
-    unmatched: number;
-    /** Rows whose strongest usable key hit several table rows. */
-    ambiguous: number;
-    /** Matched rows that actually produced a change. */
-    changed: number;
-    /** Cells refused by `targetFilter` / `readOnly`. */
-    skipped: number;
-    /** Headers found in the sheet. */
-    headers: string[];
-    /** Headers named in `match` / `columns` that the sheet doesn't have. */
-    missingHeaders: string[];
-    /** The staged (or stageable) patches. */
-    changes: Array<MonoImportChange<T>>;
-    unmatchedRows: MonoImportRejection[];
-    ambiguousRows: MonoImportAmbiguity[];
-    skippedRows: MonoImportRejection[];
-    /** `target` with every patch applied — for validating before committing. */
-    merged: T[];
-    /** Stage the changes now. A no-op when they were already staged. */
-    apply: () => void;
+  /** Every considered sheet row matched exactly one table row. */
+  ok: boolean;
+  /** Sheet rows considered (after `rowFilter`). */
+  total: number;
+  /** Rows that resolved to exactly one table row. */
+  matched: number;
+  /** Rows that resolved to none. */
+  unmatched: number;
+  /** Rows whose strongest usable key hit several table rows. */
+  ambiguous: number;
+  /** Matched rows that actually produced a change. */
+  changed: number;
+  /** Cells refused by `targetFilter` / `readOnly`. */
+  skipped: number;
+  /** Headers found in the sheet. */
+  headers: string[];
+  /** Headers named in `match` / `columns` that the sheet doesn't have. */
+  missingHeaders: string[];
+  /** The staged (or stageable) patches. */
+  changes: Array<MonoImportChange<T>>;
+  unmatchedRows: MonoImportRejection[];
+  ambiguousRows: MonoImportAmbiguity[];
+  skippedRows: MonoImportRejection[];
+  /** `target` with every patch applied — for validating before committing. */
+  merged: T[];
+  /** Stage the changes now. A no-op when they were already staged. */
+  apply: () => void;
 }
+//#endregion

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

@@ -1,94 +1,96 @@
 /// <reference path="../../vue.d.ts" />
-import { NuxtModule } from '@nuxt/schema';
-import { MonoSsrOptions } from '../vite';
-import { MonoTooltipGlobalOptions } from '../components/tooltip/tooltip-types';
-import { MonoUIConfig } from '../composables/mono-ui';
-import { MonoSkeletonDefaults } from '../composables/mono-skeleton';
+import { MonoTooltipGlobalOptions } from "../components/tooltip/tooltip-types.js";
+import { MonoSkeletonDefaults } from "../composables/mono-skeleton.js";
+import { MonoUIConfig } from "../composables/mono-ui.js";
+import { MonoSsrOptions } from "../vite/index.js";
+import { NuxtModule } from "@nuxt/schema";
+//#region src/nuxt/index.d.ts
 export interface MonoHelperModuleOptions extends MonoSsrOptions {
-    /** Auto-add `@mono-lit/helper/ui/index.css` to nuxt css. Default true. */
-    css?: boolean;
-    /** Register `<prefix*>` tags as custom elements (composed). Default true. */
-    customElement?: boolean;
-    /**
-     * Auto-wire SSR for shadow builds: importing `@mono-lit/helper/ui/shadow/<c>` in a
-     * `.vue` file makes its `<mono-c>` server-render (Declarative Shadow DOM) — no
-     * manual `litElementPrefix` / `exclude` lists, and nothing for the app to
-     * install (`nuxt-ssr-lit` ships as a @mono-lit/helper dependency). Default true.
-     * Set false (or keep a manual `nuxt-ssr-lit` module entry) to use the legacy
-     * manual wiring.
-     */
-    ssr?: boolean;
-    /**
-     * Wrap every LIGHT `<prefix*>` in `<ClientOnly>`. Default: **`nuxt.options.ssr !== false`**.
-     *
-     * The wrap exists so the server never renders a light-DOM custom element. It has a cost:
-     * Nuxt's `<ClientOnly>` renders its slot one tick AFTER it mounts, so the owning page's
-     * `onMounted` runs before the `<mono-*>` element exists and a `controlMonoTable(ref)` /
-     * `controlMonoForm(ref)` bound there sees `null`. Hence:
-     *  - `ssr: false` app: nothing renders on the server — no wrap, no `nuxt-ssr-lit`
-     *    (set `true` to force the legacy wrap anyway).
-     *  - `ssr: true` app: wrapped by default. Set `false` when the pages are client-only as a
-     *    WHOLE (route `mode: 'client'`, or `<ClientOnly><NuxtPage/>`) and only a shadow-built
-     *    shell server-renders: light tags are then left alone (they SSR as inert tags and
-     *    upgrade in the browser), while the server import-stub and the `<LitWrapper>` wrap of
-     *    the shadow tags a file imports stay on.
-     */
-    clientOnly?: boolean;
-    /**
-     * Tags to ALWAYS treat as shadow (SSR-wrapped) regardless of per-file imports
-     * — for components registered once in a shared plugin (e.g. nav/sidebar).
-     */
-    shadow?: string[];
-    /**
-     * Packages to add to `vite.resolve.dedupe`. Defaults to the lit family, which
-     * MUST resolve to one instance — @mono-lit/helper's externalized shadow build and
-     * `@lit-labs/ssr` / `nuxt-ssr-lit` otherwise get separate lit-html copies and
-     * hydration dies with `currentDirective._$initialize is not a function`.
-     * Merged with whatever the app already lists. Pass `false` to opt out.
-     */
-    dedupe?: string[] | false;
-    /**
-     * Packages to add to `vite.optimizeDeps.include`. Pre-bundling these keeps the
-     * optimize-deps hash stable, so Vite doesn't discover them mid-session on the
-     * first federated-route visit, re-optimize, and re-fetch @mono-lit/helper's chunks
-     * under a new `?v=` — which re-evaluates its `@customElement()` side effects
-     * and throws `'mono-nav' has already been defined`.
-     *
-     * Defaults to `['@mono-lit/devextreme']`. Entries that don't resolve from the app
-     * are dropped, because Vite hard-fails on an unresolvable include. Add your
-     * app's own federated-only deps here (or keep them in `vite.optimizeDeps`).
-     * Pass `false` to opt out.
-     */
-    optimizeInclude?: string[] | false;
-    /**
-     * The tooltip addon — the Nuxt twin of `createMonoTooltip({...})` in a Vue
-     * `main.ts`. `true` (or an options object) turns on the `mono-tooltip-content`
-     * attributes app-wide; the options WIN over those passed to `controlMonoTooltip`.
-     * Applied by a client-only plugin, so they must be JSON (no `content` /
-     * `onShow` functions, no nodes). Needs the optional peers `@floating-ui/dom` +
-     * `@floating-ui/core`.
-     */
-    tooltip?: MonoTooltipGlobalOptions | boolean;
-    /**
-     * App-wide default props for every mono component — the Nuxt twin of
-     * `createMonoUI({...})` in a Vue `main.ts`:
-     *   ui: { 'mono-button': { size: 'xs' }, 'mono-input': { size: 'sm' } }
-     * One key covers the light and the shadow build. Applied by an EARLY plugin on
-     * the server AND the client (shadow SSR must render with the same defaults the
-     * browser hydrates with). Must be JSON.
-     */
-    ui?: MonoUIConfig;
-    /**
-     * The automatic skeleton (`pending` on every mono element, drawn by phantom-ui). BUILT
-     * IN and ZERO-CONFIG: when the optional peer `@aejkatappaja/phantom-ui` resolves from the
-     * app, the module loads it in a client plugin before anything mounts and tells mono
-     * whether this is an SSR app (`nuxt.options.ssr`, which decides the automatic default of
-     * light elements). Not installed → nothing happens and `pending` is a no-op.
-     * `false` turns it off even when installed; an object sets the GLOBAL phantom defaults
-     * (`{ animation: 'pulse', duration: 1.2 }`) — the same as `createMonoUI({ skeleton })`.
-     * Must be JSON.
-     */
-    skeleton?: false | MonoSkeletonDefaults;
+  /** Auto-add `@mono-lit/helper/ui/index.css` to nuxt css. Default true. */
+  css?: boolean;
+  /** Register `<prefix*>` tags as custom elements (composed). Default true. */
+  customElement?: boolean;
+  /**
+   * Auto-wire SSR for shadow builds: importing `@mono-lit/helper/ui/shadow/<c>` in a
+   * `.vue` file makes its `<mono-c>` server-render (Declarative Shadow DOM) — no
+   * manual `litElementPrefix` / `exclude` lists, and nothing for the app to
+   * install (`nuxt-ssr-lit` ships as a @mono-lit/helper dependency). Default true.
+   * Set false (or keep a manual `nuxt-ssr-lit` module entry) to use the legacy
+   * manual wiring.
+   */
+  ssr?: boolean;
+  /**
+   * Wrap every LIGHT `<prefix*>` in `<ClientOnly>`. Default: **`nuxt.options.ssr !== false`**.
+   *
+   * The wrap exists so the server never renders a light-DOM custom element. It has a cost:
+   * Nuxt's `<ClientOnly>` renders its slot one tick AFTER it mounts, so the owning page's
+   * `onMounted` runs before the `<mono-*>` element exists and a `controlMonoTable(ref)` /
+   * `controlMonoForm(ref)` bound there sees `null`. Hence:
+   *  - `ssr: false` app: nothing renders on the server — no wrap, no `nuxt-ssr-lit`
+   *    (set `true` to force the legacy wrap anyway).
+   *  - `ssr: true` app: wrapped by default. Set `false` when the pages are client-only as a
+   *    WHOLE (route `mode: 'client'`, or `<ClientOnly><NuxtPage/>`) and only a shadow-built
+   *    shell server-renders: light tags are then left alone (they SSR as inert tags and
+   *    upgrade in the browser), while the server import-stub and the `<LitWrapper>` wrap of
+   *    the shadow tags a file imports stay on.
+   */
+  clientOnly?: boolean;
+  /**
+   * Tags to ALWAYS treat as shadow (SSR-wrapped) regardless of per-file imports
+   * — for components registered once in a shared plugin (e.g. nav/sidebar).
+   */
+  shadow?: string[];
+  /**
+   * Packages to add to `vite.resolve.dedupe`. Defaults to the lit family, which
+   * MUST resolve to one instance — @mono-lit/helper's externalized shadow build and
+   * `@lit-labs/ssr` / `nuxt-ssr-lit` otherwise get separate lit-html copies and
+   * hydration dies with `currentDirective._$initialize is not a function`.
+   * Merged with whatever the app already lists. Pass `false` to opt out.
+   */
+  dedupe?: string[] | false;
+  /**
+   * Packages to add to `vite.optimizeDeps.include`. Pre-bundling these keeps the
+   * optimize-deps hash stable, so Vite doesn't discover them mid-session on the
+   * first federated-route visit, re-optimize, and re-fetch @mono-lit/helper's chunks
+   * under a new `?v=` — which re-evaluates its `@customElement()` side effects
+   * and throws `'mono-nav' has already been defined`.
+   *
+   * Defaults to `['@mono-lit/devextreme']`. Entries that don't resolve from the app
+   * are dropped, because Vite hard-fails on an unresolvable include. Add your
+   * app's own federated-only deps here (or keep them in `vite.optimizeDeps`).
+   * Pass `false` to opt out.
+   */
+  optimizeInclude?: string[] | false;
+  /**
+   * The tooltip addon — the Nuxt twin of `createMonoTooltip({...})` in a Vue
+   * `main.ts`. `true` (or an options object) turns on the `mono-tooltip-content`
+   * attributes app-wide; the options WIN over those passed to `controlMonoTooltip`.
+   * Applied by a client-only plugin, so they must be JSON (no `content` /
+   * `onShow` functions, no nodes). Needs the optional peers `@floating-ui/dom` +
+   * `@floating-ui/core`.
+   */
+  tooltip?: MonoTooltipGlobalOptions | boolean;
+  /**
+   * App-wide default props for every mono component — the Nuxt twin of
+   * `createMonoUI({...})` in a Vue `main.ts`:
+   *   ui: { 'mono-button': { size: 'xs' }, 'mono-input': { size: 'sm' } }
+   * One key covers the light and the shadow build. Applied by an EARLY plugin on
+   * the server AND the client (shadow SSR must render with the same defaults the
+   * browser hydrates with). Must be JSON.
+   */
+  ui?: MonoUIConfig;
+  /**
+   * The automatic skeleton (`pending` on every mono element, drawn by phantom-ui). BUILT
+   * IN and ZERO-CONFIG: when the optional peer `@aejkatappaja/phantom-ui` resolves from the
+   * app, the module loads it in a client plugin before anything mounts and tells mono
+   * whether this is an SSR app (`nuxt.options.ssr`, which decides the automatic default of
+   * light elements). Not installed → nothing happens and `pending` is a no-op.
+   * `false` turns it off even when installed; an object sets the GLOBAL phantom defaults
+   * (`{ animation: 'pulse', duration: 1.2 }`) — the same as `createMonoUI({ skeleton })`.
+   * Must be JSON.
+   */
+  skeleton?: false | MonoSkeletonDefaults;
 }
 declare const monoHelperModule: NuxtModule;
-export default monoHelperModule;
+//#endregion
+export { monoHelperModule as default };