@mono-lit/helper 0.0.0-stage → 0.0.1

package/dist/src/components/table/mono-table-th.d.ts

@@ -0,0 +1,41 @@
+import { LitElement, TemplateResult } from 'lit';
+import { TableThSlotName, TableThIconName } from './mono-table-th-core.js';
+declare const MonoTableTh_base: import('../../composables/hybird-prop').Constructor<import('./mono-table-th-core.js').MonoTableThCoreInterface> & typeof LitElement;
+/**
+ * Light-DOM `mono-table-th` (default build, `@mono-lit/helper/ui/table`). The unified
+ * column-header cell — place it inside a native `<th>`. Declares the column's
+ * `field`/`caption`, folds sorting into `:sort.prop="{ order?, noClear?, disabled? }"`,
+ * and marks the column editable with `:editable.prop="{ type, editor }"`. The
+ * standalone `mono-table-sort` remains supported.
+ *
+ * Light-DOM Lit replaces the host's children on render, so the user's label nodes
+ * are captured once in `connectedCallback` and re-appended into the
+ * `[data-mono-slot="label"]` placeholder after each render. The sort indicator is
+ * a single global UnoCSS icon that swaps with the direction (neutral
+ * `i-fluent-arrow-sort-16-filled` → `i-ri-arrow-up-long-fill` /
+ * `i-ri-arrow-down-long-fill`); all other logic lives in `MonoTableThCore`.
+ *
+ * @example
+ * <th><mono-table-th :data-grid.prop="table" field="Nama" caption="Name"
+ *      :sort.prop="{ order: 'asc' }"
+ *      :editable.prop="{ type: 'string', editor: 'input-text' }">Name</mono-table-th></th>
+ */
+export declare class MonoTableTh extends MonoTableTh_base {
+    static styles: import('lit').CSSResult[];
+    protected createRenderRoot(): HTMLElement;
+    /** The captured label nodes (the element's original light-DOM children). */
+    private _buckets;
+    private _slotsCaptured;
+    connectedCallback(): void;
+    protected updated(changed: Map<string, unknown>): void;
+    protected renderSlot(_name: TableThSlotName): TemplateResult;
+    protected renderIcon(name: TableThIconName): TemplateResult;
+    private _captureSlots;
+    private _placeSlot;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'mono-table-th': MonoTableTh;
+    }
+}
+export {};

package/dist/src/components/table/mono-table-th.shadow.d.ts

@@ -0,0 +1,19 @@
+import { LitElement, TemplateResult } from 'lit';
+import { TableThSlotName, TableThIconName } from './mono-table-th-core.js';
+declare const MonoTableThShadow_base: import('../../composables/hybird-prop').Constructor<import('./mono-table-th-core.js').MonoTableThCoreInterface> & typeof LitElement;
+/**
+ * Shadow-DOM `mono-table-th` (SSR build, `@mono-lit/helper/ui/shadow/table`). The
+ * header label projects through a native `<slot>`; the sort indicator and the
+ * header-filter funnel are single inline SVGs that swap with their state (the
+ * global `i-*` utility CSS can't reach a shadow root) — the fluent neutral glyph
+ * and the ri up/down arrows, and the mdi outlined/filled funnels, matching the
+ * light build's `i-fluent-*` / `i-ri-*` / `i-mdi-filter*` icons. Shares all other
+ * logic via `MonoTableThCore`.
+ */
+export declare class MonoTableThShadow extends MonoTableThShadow_base {
+    static styles: import('lit').CSSResult[];
+    protected renderSlot(_name: TableThSlotName): TemplateResult;
+    protected renderIcon(name: TableThIconName): TemplateResult;
+    connectedCallback(): void;
+}
+export {};

package/dist/src/components/table/store-group-source.d.ts

@@ -0,0 +1,24 @@
+import { MonoGridSource, MonoServerGroupSource } from './mono-data-grid.js';
+type SummaryType = 'sum' | 'avg' | 'min' | 'max' | 'count';
+export interface StoreGroupSourceConfig {
+    /** The single field to group by. */
+    groupField: string;
+    /** Columns to fetch for a group's rows (omit = all). */
+    select?: string[];
+    /** Columns matched by search. */
+    searchExpr?: string | string[];
+    /** Search operation (default `'contains'`). */
+    searchOperation?: string;
+    /** Per-group aggregates, e.g. `{ TotalBudget: 'sum' }`. */
+    groupSummary?: Record<string, SummaryType>;
+}
+/**
+ * Build a {@link MonoServerGroupSource} that drives **server-side** group paging
+ * straight from a devextreme `DataSource`'s store — no extra fetcher, no custom
+ * callbacks. `loadGroups` issues one cheap grouped query (group keys + counts +
+ * optional summaries, no rows); `loadRows` fetches a single group's page with
+ * `$filter` + `$skip`/`$top`. Returns `null` if the source has no usable store
+ * (e.g. a plain in-memory array), so the caller can fall back to client grouping.
+ */
+export declare function storeGroupSource<T = any>(source: MonoGridSource<T>, config: StoreGroupSourceConfig): MonoServerGroupSource<T> | null;
+export {};

package/dist/src/components/table/table-controller-core.d.ts

@@ -0,0 +1,40 @@
+import { LitElement } from 'lit';
+import { MonoTableController } from './mono-data-grid.js';
+import { Constructor } from '../../composables/hybird-prop';
+/**
+ * Public surface added by the shared controller base mixin (for typing the
+ * per-element cores + wrappers).
+ */
+export declare class MonoTableControllerCoreInterface {
+    dataGrid?: MonoTableController;
+    /** Unsubscribe handle for the current controller subscription (set by `_subscribe`). */
+    protected _off?: () => void;
+    /** (Re)bind the controller subscription; called on connect + `dataGrid` change. */
+    protected _subscribe(): void;
+    /**
+     * Which slot of `monoDataGrid({ props })` this element reads. `'th' | 'sort' |
+     * 'summary'` resolve per column via the element's `field`; the rest are
+     * singletons. Left undefined = the element takes no central props.
+     */
+    protected _propsSlot?: MonoTablePropsSlot;
+    protected _applyControllerProps(): void;
+}
+/** The `props` key an element reads — see {@link MonoTableProps}. */
+export type MonoTablePropsSlot = 'th' | 'sort' | 'summary' | 'search' | 'info' | 'paging' | 'loading' | 'empty' | 'error' | 'pageSize' | 'pagingGroup' | 'detail' | 'checkbox';
+/**
+ * `MonoTableControllerCore` — the render-mode-agnostic plumbing shared by every
+ * `mono-table-*` element: the `dataGrid` controller property (bound via Vue
+ * `.prop`, so `attribute: false`), its hybrid alias, and the
+ * subscribe/unsubscribe lifecycle that re-renders the element whenever the
+ * controller notifies.
+ *
+ * The six per-element cores compose this base, so their light/shadow wrappers
+ * only ever call `MonoTable<El>Core(LitElement)`. Elements needing extra
+ * lifecycle work (e.g. `mono-table-paging-group` registers/clears group paging)
+ * override the lifecycle methods and chain `super.*` to keep this plumbing.
+ *
+ * SSR-safe: holds no `document`/`window` access. `dataGrid` is undefined on the
+ * server (a `.prop` binding can't cross Declarative Shadow DOM), so `_subscribe`
+ * is a no-op there and the element renders its deterministic empty shell.
+ */
+export declare const MonoTableControllerCore: <T extends Constructor<LitElement>>(superClass: T) => Constructor<MonoTableControllerCoreInterface> & T;

package/dist/src/components/table/table-filter-icons.d.ts

@@ -0,0 +1,3 @@
+import { TemplateResult } from 'lit';
+/** One funnel SVG: outlined while the column is unfiltered, filled once it isn't. */
+export declare function filterIndicatorSvg(active: boolean): TemplateResult;

package/dist/src/components/table/table-menu-core.d.ts

@@ -0,0 +1,65 @@
+import { LitElement, TemplateResult } from 'lit';
+import { SortOrder } from './mono-data-grid.js';
+import { MonoTableControllerCoreInterface } from './table-controller-core.js';
+import { Constructor } from '../../composables/hybird-prop';
+import { PopupPortalController } from '../../composables/popup-portal.js';
+/** Resolved sort config — see {@link MonoColumnSort}. */
+export interface MonoResolvedSort {
+    enable: boolean;
+    showIcon: boolean;
+    noClear: boolean;
+    disabled: boolean;
+}
+/** Public surface added by the menu core mixin. */
+export declare class MonoTableMenuCoreInterface extends MonoTableControllerCoreInterface {
+    protected _menuOpen: boolean;
+    protected _sortMenuOpen: boolean;
+    protected _menuPopup?: PopupPortalController;
+    protected _sortMenuPopup?: PopupPortalController;
+    protected _menuPanelEl: HTMLElement | null;
+    protected _cell: HTMLElement | null;
+    protected get _sortDir(): SortOrder;
+    protected resolveSort(raw?: {
+        enable?: boolean;
+        showIcon?: boolean;
+        noClear?: boolean;
+        disabled?: boolean;
+    }): MonoResolvedSort;
+    protected bindContextMenu(wanted: boolean): void;
+    protected detachContextMenu(): void;
+    protected ensurePopups(): void;
+    protected openMenu(e?: Event): void;
+    protected closeMenu(): void;
+    protected _menuKeepsPath(path: EventTarget[]): boolean;
+    protected bindDocListeners(): void;
+    protected teardownDocListeners(): void;
+    protected renderSortMenuItem(): TemplateResult;
+    protected renderSortSubmenu(noClear?: boolean): TemplateResult;
+    protected pickSort(order: SortOrder): Promise<void>;
+    protected clearAllSorts(): Promise<void>;
+    protected _caretIcon(): TemplateResult;
+    protected _sortGlyph(dir: 'asc' | 'desc' | 'clear'): TemplateResult;
+    protected _clearAllIcon(): TemplateResult;
+    protected _checkIcon(): TemplateResult;
+}
+/**
+ * `MonoTableMenuCore` — the header context-menu machinery shared by
+ * `mono-table-th` and the standalone `mono-table-sort`.
+ *
+ * Right-click on the header cell ALWAYS opens the menu; its **Sort** row cascades
+ * into an Ascending / Descending / Clear / Clear-all submenu, and picking a
+ * direction there ACCUMULATES keys (the column's own arrow stays single-key).
+ * Only `mono-table-th` adds a Header Filter row (and its value panel), so the
+ * filter-specific parts deliberately stay in that core — this mixin owns just what
+ * is genuinely common:
+ *
+ *  - the menu + submenu `PopupPortalController`s,
+ *  - the `contextmenu` binding on the closest `th`/`td`,
+ *  - the document `pointerdown` / `Escape` dismissal, with a
+ *    `_menuKeepsPath()` hook subclasses extend for their own popups,
+ *  - the Sort row and submenu rendering.
+ *
+ * It only *declares* `field` / `caption` — both cores already define them as
+ * reactive properties, and re-declaring would shadow them.
+ */
+export declare const MonoTableMenuCore: <T extends Constructor<LitElement>>(superClass: T) => Constructor<MonoTableMenuCoreInterface> & T;

package/dist/src/components/table/table-overlay.d.ts

@@ -0,0 +1,165 @@
+/**
+ * The element an overlay covers: the `<table>` first, the scroll wrapper only as
+ * a fallback.
+ *
+ * The order is the whole point. An absolutely positioned descendant of a SCROLL
+ * CONTAINER scrolls with the content, so covering the wrapper pins the overlay to
+ * the scroll origin at only the scrollport's size — scroll a wide or long table
+ * and the overlay slides away, leaving live rows showing through beside it. The
+ * table's box IS the content, so covering that keeps every column and row under
+ * the overlay at any scroll offset.
+ */
+export declare function overlayHost(el: Element): HTMLElement | null;
+/**
+ * The element whose height is reserved while an overlay is up — NEVER the
+ * `<table>`.
+ *
+ * A `<table>` does not treat a height as "reserve this much space": CSS table
+ * layout DISTRIBUTES any surplus over the rows. Freeze a table at the height it
+ * had when it was full, then let the source clear its rows, and the surplus lands
+ * on the only row left — the header — which stretches into a band hundreds of
+ * pixels tall with its captions floating in the middle of it. That is the
+ * opposite of the collapse this guard exists to prevent.
+ *
+ * A block box just reserves the space, so the hold goes on the scroll wrapper, or
+ * failing that on the table's own parent. If the table has no block ancestor to
+ * hold the space the hold is SKIPPED — a grid that briefly goes short is a
+ * smaller problem than a deformed one.
+ */
+export declare function overlaySizeHost(el: Element): HTMLElement | null;
+/**
+ * Widest header row, counting `colspan` — the span a generated overlay cell
+ * needs.
+ *
+ * Generated and spacer rows are excluded by `data-mono-stripe-skip` rather than
+ * by class name: this has to skip the row the OTHER overlay may have built as
+ * well as its own, and both already carry that attribute for the zebra count.
+ */
+export declare function columnCount(table: HTMLTableElement): number;
+/**
+ * The `<tr>` an overlay lives in, and whether the element built it.
+ *
+ * `generated` decides what disconnect may do: a row the element created is its
+ * own to remove; a row the consumer wrote is theirs, and taking it out from under
+ * a framework that still holds a reference to it is how hydration breaks.
+ */
+export interface RowHost {
+    row: HTMLTableRowElement;
+    generated: boolean;
+}
+/**
+ * Give an overlay a spec-valid home inside the table, and make that home carry
+ * what the styling keys on.
+ *
+ * `<table>`'s content model permits only `caption` / `colgroup` / `thead` /
+ * `tbody` / `tfoot`, and a row section permits only `<tr>` — so a bare custom
+ * element in either is invalid HTML. Vue's compiler warns about it on every
+ * consumer build, and the HTML PARSER foster-parents it out of the table: a
+ * server-rendered `<mono-shadow-table-error>` written straight into `<tbody>`
+ * has left the table before hydration starts, at which point it is not a row and
+ * covers nothing.
+ *
+ * So the form the docs teach is the valid one — `<tr><td colspan>` written by the
+ * consumer — and this function has two jobs:
+ *
+ * 1. **Adopt** a hand-written cell. A row the consumer wrote lacks the three
+ *    things the generated one has: the `rowClass` (which is the ONLY thing the
+ *    padding/border reset in `table.css` keys on — without it a docs-style
+ *    `td { padding }` puts a 14px gutter around the bar), `data-mono-stripe-skip`
+ *    (zebra parity), and a `colspan` that `syncRowSpan` keeps in step with the
+ *    columns. Asking a consumer to remember all three is a trap, so the element
+ *    stamps them on the row it finds itself in. The class is ADDED, never
+ *    replaced — a framework does not patch an attribute it did not bind, so what
+ *    is written here survives their re-renders, and what they wrote survives us.
+ *
+ * 2. **Generate** a row when the element is dropped bare into a table or a row
+ *    section anyway — the client-only fallback that makes an imperative
+ *    `body.appendChild(el)` keep working. Not the taught form, for the reasons
+ *    above.
+ *
+ * A `<caption>` host is left alone: it is valid HTML and its CSS is honoured as
+ * written. Anything else (`undefined`) is not a table position at all.
+ */
+export declare function ensureRowHost(el: HTMLElement, rowClass: string): RowHost | undefined;
+/**
+ * Drop a GENERATED row on disconnect. An empty `<tr>` left behind would still
+ * draw a border and occupy a slot in the zebra parity count.
+ *
+ * An adopted row is never touched: it is the consumer's node, still referenced by
+ * whatever rendered it, and removing it is exactly the "disrupt future
+ * functionality" the Vue warning threatens.
+ */
+export declare function releaseRowHost(el: HTMLElement, host: RowHost | undefined): void;
+/**
+ * Re-widen the row's cell after a column change — generated or adopted.
+ *
+ * `ensureRowHost` sets `colspan` once on a generated cell, from the header as it
+ * stood on connect; a hand-written cell has whatever the consumer typed, which
+ * may be nothing. A grid whose columns are driven by data — a `v-for` over a
+ * props snapshot, a column toggled off — changes that count later, and a stale
+ * span leaves the row short of the table or overflowing it.
+ * `mono-table-detail-core` recomputes for the same reason.
+ *
+ * Only writes when the number actually moved, so this is safe to call from every
+ * `updated()` — and a consumer's correct `colspan` is never rewritten.
+ */
+export declare function syncRowSpan(el: HTMLElement, host: RowHost | undefined): void;
+export interface OverlayHostOptions {
+    /**
+     * The custom property the measured sticky-header height is published on, so the
+     * overlay's content can sit BELOW a frozen header rather than under it.
+     */
+    headVar: string;
+    /**
+     * This overlay's own reservation slot on the size host — must start with
+     * `--mono-table-hold-`. See {@link HOLD_PREFIX} for why each overlay needs one
+     * of its own rather than sharing `min-height`.
+     */
+    holdVar: string;
+    /**
+     * How much room to reserve on the size host while the overlay is up.
+     *
+     * `'measure'` freezes whatever height it currently has — right for an overlay
+     * that appears over a grid which is ABOUT to lose its rows. A length string
+     * sets that height outright, which is what an overlay shown over an already
+     * empty grid needs: there is nothing left to measure but a header.
+     *
+     * A FUNCTION is called after `headVar` has been published, for a caller whose
+     * answer depends on it. Passing the string it would have returned instead reads
+     * the header offset from the PREVIOUS pass — zero on the first one — which is
+     * a whole header's worth of room short.
+     */
+    hold: 'measure' | string | (() => string);
+    /**
+     * When to measure the header into `headVar`.
+     *
+     * `'sticky'` publishes it only for a frozen header, and `0` otherwise — right
+     * for a small glyph that may sit over rows quite happily, and only has to clear
+     * a header that refuses to scroll away.
+     *
+     * `'always'` publishes it whatever the header does. An overlay whose content is
+     * a block of text has to clear the header at rest as well as while scrolling:
+     * with `0` it starts at the table's top and the first line lands ON the header
+     * row. Costs a slightly generous offset once a non-sticky header has scrolled
+     * away, which is invisible; the alternative is text over the column names.
+     */
+    measureHead?: 'sticky' | 'always';
+}
+/**
+ * Give back everything an overlay reserved, from the hosts it remembers.
+ *
+ * Safe to call on an element that never applied anything, and safe to call after
+ * it has been removed from the DOM — which is the point.
+ */
+export declare function releaseOverlayHost(el: HTMLElement): void;
+/**
+ * Make the host a positioning context, publish the header offset, reserve the
+ * space and stretch the overlay — or undo all four.
+ *
+ * **The order is load-bearing, and each step feeds the next.** The header offset
+ * goes first because a configured hold may be a function of it. The hold goes
+ * next because the stretch measures the scroll region the hold has just resized —
+ * do it the other way round and the overlay is stretched to the height the table
+ * had before any room was made, which on an empty grid is a header-high strip.
+ */
+export declare function applyOverlayHost(el: HTMLElement, on: boolean, opts: OverlayHostOptions): void;

package/dist/src/components/table/table-sort-icons.d.ts

@@ -0,0 +1,4 @@
+import { TemplateResult } from 'lit';
+import { SortOrder } from './mono-data-grid.js';
+/** One sort-indicator SVG, glyph chosen by the active direction. */
+export declare function sortIndicatorSvg(current: SortOrder): TemplateResult;

package/dist/src/components/table/table-sort-utils.d.ts

@@ -0,0 +1,20 @@
+import { SortOrder } from './mono-data-grid.js';
+/**
+ * Pure sort-cycle helpers shared by `mono-table-sort` and `mono-table-th` so the
+ * two header controls behave identically. Kept dependency-free (no Lit/DOM) so
+ * both cores can import them.
+ */
+/**
+ * The next direction when a sortable header is clicked.
+ * - default cycle: `null → asc → desc → null`
+ * - `noClear`: `asc ↔ desc` (never returns to `null`)
+ */
+export declare function nextOrder(current: SortOrder, noClear?: boolean): SortOrder;
+/** `aria-sort` value for the parent header cell. */
+export declare function ariaSort(current: SortOrder): string;
+/**
+ * Native tooltip text shown on hover — reflects the current sort direction and,
+ * when more than one column is sorted, this column's precedence (which the
+ * `<sup>` badge shows visually).
+ */
+export declare function sortTitle(current: SortOrder, seq?: number, total?: number): string;