@mono-lit/helper 0.0.2 → 0.0.4

package/dist/src/composables/data-source-controller.d.ts

@@ -1,20 +1,21 @@
-import { ReactiveController, ReactiveControllerHost } from 'lit';
-import { DescribedError } from '../utils/normalize-error';
+import { DescribedError } from "../utils/normalize-error.js";
+import { ReactiveController, ReactiveControllerHost } from "lit";
+//#region src/composables/data-source-controller.d.ts
 /**
  * Minimal structural shape of a devextreme DataSource. Declared locally so
  * @mono-lit/helper stays dependency-free; a real devextreme DataSource satisfies it.
  */
 export interface MonoDataSource<T = unknown> {
-    load: () => PromiseLike<T[]> | T[];
-    items: () => T[];
-    isLoading?: () => boolean;
-    on(event: string, handler: (...args: unknown[]) => void): void;
-    off(event: string, handler: (...args: unknown[]) => void): void;
-    paginate?(value?: boolean): boolean;
-    pageSize?(value?: number): number;
-    pageIndex?(value?: number): number;
-    isLastPage?: () => boolean;
-    totalCount?: () => number;
+  load: () => PromiseLike<T[]> | T[];
+  items: () => T[];
+  isLoading?: () => boolean;
+  on(event: string, handler: (...args: unknown[]) => void): void;
+  off(event: string, handler: (...args: unknown[]) => void): void;
+  paginate?(value?: boolean): boolean;
+  pageSize?(value?: number): number;
+  pageIndex?(value?: number): number;
+  isLastPage?: () => boolean;
+  totalCount?: () => number;
 }
 /**
  * Incremental loading mode. Works with BOTH a paged DataSource and a plain
@@ -24,16 +25,16 @@ export interface MonoDataSource<T = unknown> {
  */
 export type LoadMoreMode = 'button' | 'scroll';
 export interface DataSourceControllerOptions<T> {
-    /** Current bound DataSource (or null) — read live from the host property. */
-    getDataSource: () => MonoDataSource<T> | null;
-    /** The raw plain `items` array, used when no DataSource is bound. */
-    getItems: () => T[];
-    /** Auto-load the source on attach when it has no items yet. */
-    getImmediate: () => boolean;
-    /** Effective load-more mode, or undefined when disabled. */
-    getLoadMoreMode: () => LoadMoreMode | undefined;
-    /** Sanitized chunk size (>= 1) for array-mode paging. */
-    getPageSize: () => number;
+  /** Current bound DataSource (or null) — read live from the host property. */
+  getDataSource: () => MonoDataSource<T> | null;
+  /** The raw plain `items` array, used when no DataSource is bound. */
+  getItems: () => T[];
+  /** Auto-load the source on attach when it has no items yet. */
+  getImmediate: () => boolean;
+  /** Effective load-more mode, or undefined when disabled. */
+  getLoadMoreMode: () => LoadMoreMode | undefined;
+  /** Sanitized chunk size (>= 1) for array-mode paging. */
+  getPageSize: () => number;
 }
 /**
  * Encapsulates the generic DataSource + incremental-loading logic shared by
@@ -44,70 +45,71 @@ export interface DataSourceControllerOptions<T> {
  * Every state mutation calls `host.requestUpdate()` so the host re-renders.
  */
 export declare class DataSourceController<T = unknown> implements ReactiveController {
-    private readonly host;
-    private readonly opts;
-    private _dsItems;
-    private _dsLoading;
-    private _loadingMore;
-    private _isLastPage;
-    private _error;
-    private _hasLoaded;
-    private _retrying;
-    private _visibleCount;
-    private _internalLoad;
-    private _bound;
-    constructor(host: ReactiveControllerHost, opts: DataSourceControllerOptions<T>);
-    hostConnected(): void;
-    hostDisconnected(): void;
-    /** Attach/detach listeners for a (possibly new) DataSource and seed state. */
-    bind(ds: MonoDataSource<T> | null): void;
-    maybeImmediateLoad(): void;
-    /** Call when the load-more mode changes; refreshes paging assumptions. */
-    onLoadMoreModeChange(): void;
-    /** Reset array-mode paging to the first chunk. */
-    resetVisible(): void;
-    /** Load/reveal the next page and append it to the accumulated list. */
-    loadMore(): Promise<void>;
-    /**
-     * Re-run the request after a failure. Reloads the source as it stands, so a
-     * failed search is retried with the same query. While it runs the field is
-     * {@link busy} again.
-     *
-     * `load` replaces the plain `ds.load()` — a host whose failed request was a
-     * search passes one that clears the query on the source and reloads.
-     */
-    retry(load?: () => unknown): Promise<void>;
-    /**
-     * Record a failure from a request the host drove itself (e.g. a server
-     * select-all drain). Cancelled loads are ignored.
-     */
-    setError(raw: unknown): void;
-    /** Raw source array: accumulated DataSource items, or the plain `items`. */
-    get sourceItems(): T[];
-    /** Rows to actually render (array-mode reveals a slice; else everything). */
-    get visibleItems(): T[];
-    get loading(): boolean;
-    get loadingMore(): boolean;
-    /**
-     * The field must be locked: the FIRST load (or a retry) is in flight. A
-     * search / filter reload after the source has answered once does not count —
-     * the person is typing into the field and it must stay usable.
-     */
-    get busy(): boolean;
-    /** The last load failure, described for a person; null once a load succeeds. */
-    get error(): DescribedError | null;
-    /** load-more is driving a plain `items` array (no DataSource bound). */
-    get isArrayLoadMore(): boolean;
-    /** Whether there's nothing left to load/reveal. */
-    get atLastPage(): boolean;
-    private readonly _onChanged;
-    private readonly _onLoadingChanged;
-    private readonly _onLoadError;
-    /** A load answered: the source is usable and any earlier failure is over. */
-    private _markLoaded;
-    private _sync;
-    /** Load the first page, replacing the accumulated list. */
-    private _loadFirstPage;
-    private _detach;
-    private _changed;
+  private readonly host;
+  private readonly opts;
+  private _dsItems;
+  private _dsLoading;
+  private _loadingMore;
+  private _isLastPage;
+  private _error;
+  private _hasLoaded;
+  private _retrying;
+  private _visibleCount;
+  private _internalLoad;
+  private _bound;
+  constructor(host: ReactiveControllerHost, opts: DataSourceControllerOptions<T>);
+  hostConnected(): void;
+  hostDisconnected(): void;
+  /** Attach/detach listeners for a (possibly new) DataSource and seed state. */
+  bind(ds: MonoDataSource<T> | null): void;
+  maybeImmediateLoad(): void;
+  /** Call when the load-more mode changes; refreshes paging assumptions. */
+  onLoadMoreModeChange(): void;
+  /** Reset array-mode paging to the first chunk. */
+  resetVisible(): void;
+  /** Load/reveal the next page and append it to the accumulated list. */
+  loadMore(): Promise<void>;
+  /**
+   * Re-run the request after a failure. Reloads the source as it stands, so a
+   * failed search is retried with the same query. While it runs the field is
+   * {@link busy} again.
+   *
+   * `load` replaces the plain `ds.load()` — a host whose failed request was a
+   * search passes one that clears the query on the source and reloads.
+   */
+  retry(load?: () => unknown): Promise<void>;
+  /**
+   * Record a failure from a request the host drove itself (e.g. a server
+   * select-all drain). Cancelled loads are ignored.
+   */
+  setError(raw: unknown): void;
+  /** Raw source array: accumulated DataSource items, or the plain `items`. */
+  get sourceItems(): T[];
+  /** Rows to actually render (array-mode reveals a slice; else everything). */
+  get visibleItems(): T[];
+  get loading(): boolean;
+  get loadingMore(): boolean;
+  /**
+   * The field must be locked: the FIRST load (or a retry) is in flight. A
+   * search / filter reload after the source has answered once does not count —
+   * the person is typing into the field and it must stay usable.
+   */
+  get busy(): boolean;
+  /** The last load failure, described for a person; null once a load succeeds. */
+  get error(): DescribedError | null;
+  /** load-more is driving a plain `items` array (no DataSource bound). */
+  get isArrayLoadMore(): boolean;
+  /** Whether there's nothing left to load/reveal. */
+  get atLastPage(): boolean;
+  private readonly _onChanged;
+  private readonly _onLoadingChanged;
+  private readonly _onLoadError;
+  /** A load answered: the source is usable and any earlier failure is over. */
+  private _markLoaded;
+  private _sync;
+  /** Load the first page, replacing the accumulated list. */
+  private _loadFirstPage;
+  private _detach;
+  private _changed;
 }
+//#endregion

package/dist/src/composables/element-props.d.ts

@@ -1,3 +1,4 @@
+//#region src/composables/element-props.d.ts
 /**
  * Whether `key` can actually be assigned on `obj` — a plain expando, or an
  * accessor/data property that isn't read-only.
@@ -10,9 +11,7 @@
  */
 export declare function isSettable(obj: object, key: string): boolean;
 /** `{ onChange, onToggle, onLoadingChange, … }` typed from a component's `*Events` interface. */
-export type MonoEventProps<E> = {
-    [K in Extract<keyof E, string> as K extends `${string}-${string}` ? never : `on${Capitalize<K>}`]?: (event: E[K]) => void;
-};
+export type MonoEventProps<E> = { [K in Extract<keyof E, string> as K extends `${string}-${string}` ? never : `on${Capitalize<K>}`]?: (event: E[K]) => void; };
 /** Whether a props key names an event handler (`onClick`, `onLoadingChange`). */
 export declare function isEventHandlerKey(key: string): boolean;
 /**
@@ -44,3 +43,4 @@ export declare function detachEventHandlers(el: object): void;
  * and its failure modes are subtle enough to be worth having in one place.
  */
 export declare function applyProps(el: object, patch: Record<string, unknown> | undefined): boolean;
+//#endregion

package/dist/src/composables/field-icons.d.ts

@@ -1,4 +1,5 @@
-import { TemplateResult } from 'lit';
+import { TemplateResult } from "lit";
+//#region src/composables/field-icons.d.ts
 /** Downward caret — the "this opens a panel" affordance. */
 export declare function caretIcon(): TemplateResult;
 /** The ✕ a clear button and a chip's remove button draw, at the caret's weight. */
@@ -13,3 +14,4 @@ export declare function chevronIcon(dir: -1 | 1): TemplateResult;
 export declare function spinnerIcon(): TemplateResult;
 /** ↻ — the retry affordance a field shows after its data source failed. */
 export declare function refreshIcon(): TemplateResult;
+//#endregion

package/dist/src/composables/hybird-prop.d.ts

@@ -1,3 +1,4 @@
+//#region src/composables/hybird-prop.d.ts
 /** Generic constructor type for Lit mixins: `<T extends Constructor<LitElement>>`. */
 export type Constructor<T = object> = new (...args: any[]) => T;
 export declare function toKebabCase(value: string): string;
@@ -53,12 +54,12 @@ export declare function defineHybridPropAlias<T extends object>(target: T, alias
  */
 export declare function arrayHasChanged(value: unknown, old: unknown): boolean;
 export declare const booleanStringConverter: {
-    fromAttribute(value: unknown): boolean;
-    toAttribute(value: boolean): string | null;
+  fromAttribute(value: unknown): boolean;
+  toAttribute(value: boolean): string | null;
 };
 export declare const numberStringConverter: {
-    fromAttribute(value: string | null): number;
-    toAttribute(value: number): string | null;
+  fromAttribute(value: string | null): number;
+  toAttribute(value: number): string | null;
 };
 /**
  * Like {@link numberStringConverter}, but an absent/blank attribute stays
@@ -70,10 +71,11 @@ export declare const numberStringConverter: {
  * Using the plain number converter there would pin every dialog to `z-index: 0`.
  */
 export declare const optionalNumberConverter: {
-    fromAttribute(value: string | null): number | undefined;
-    toAttribute(value: number | undefined): string | null;
+  fromAttribute(value: string | null): number | undefined;
+  toAttribute(value: number | undefined): string | null;
 };
 export declare const stringConverter: {
-    fromAttribute(value: string | null): string;
-    toAttribute(value: string): string | null;
+  fromAttribute(value: string | null): string;
+  toAttribute(value: string): string | null;
 };
+//#endregion

package/dist/src/composables/hydration-flush.d.ts

@@ -1,18 +1,19 @@
-import { ReactiveElement } from 'lit';
+import { ReactiveElement } from "lit";
+//#region src/composables/hydration-flush.d.ts
 export interface FlushSsrHydrationOptions {
-    /**
-     * Withhold hydration until this returns `true`; polling continues meanwhile.
-     *
-     * Needed for elements that render a LIST from a property the server also
-     * rendered (`:items.prop`): Vue assigns the property asynchronously AFTER
-     * connect, so hydrating early makes the client render fewer children than the
-     * server's `<!--lit-part-->` markers → "Unhandled shorter than expected
-     * iterable" plus a duplicate render. Gate on the client count having caught
-     * up with the server count.
-     */
-    gate?: () => boolean;
-    /** How many ticks to attempt before giving up (default 30). */
-    maxTries?: number;
+  /**
+   * Withhold hydration until this returns `true`; polling continues meanwhile.
+   *
+   * Needed for elements that render a LIST from a property the server also
+   * rendered (`:items.prop`): Vue assigns the property asynchronously AFTER
+   * connect, so hydrating early makes the client render fewer children than the
+   * server's `<!--lit-part-->` markers → "Unhandled shorter than expected
+   * iterable" plus a duplicate render. Gate on the client count having caught
+   * up with the server count.
+   */
+  gate?: () => boolean;
+  /** How many ticks to attempt before giving up (default 30). */
+  maxTries?: number;
 }
 /**
  * Force an SSR'd element's first client update to flush.
@@ -32,3 +33,4 @@ export interface FlushSsrHydrationOptions {
  * on it alone leaves the element frozen until the tab is next painted.
  */
 export declare function flushSsrHydration(el: ReactiveElement, options?: FlushSsrHydrationOptions): void;
+//#endregion

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

@@ -1,4 +1,5 @@
-import { TemplateResult } from 'lit';
+import { TemplateResult } from "lit";
+//#region src/composables/icon.d.ts
 /**
  * Detect whether an icon string is an iconify utility class — e.g.
  * `i-mdi-close`, `i-tabler-upload`. UnoCSS's preset-icons resolves these to a
@@ -15,3 +16,4 @@ export declare function isIconifyClass(icon: string | undefined | null): boolean
  * glyph is not bundled (see `scripts/mdi-glyphs.mjs`), so a caller can fall back.
  */
 export declare function mdiGlyph(icon: string | undefined | null): TemplateResult | undefined;
+//#endregion

package/dist/src/composables/layout-var.d.ts

@@ -1,3 +1,4 @@
+//#region src/composables/layout-var.d.ts
 /**
  * Refcounted document-level layout variables.
  *
@@ -32,3 +33,4 @@ export declare function claimLayoutVar(name: string, owner: object, value: strin
  * that owner's last published value is restored instead.
  */
 export declare function releaseLayoutVar(name: string, owner: object): void;
+//#endregion

package/dist/src/composables/light-slots.d.ts

@@ -1,15 +1,16 @@
+//#region src/composables/light-slots.d.ts
 /** Captured nodes, keyed by slot name, in document order. */
 export type LightSlotBuckets = Map<string, Node[]>;
 export interface CaptureLightSlotsOptions {
-    /** Named `slot="…"` values this component lays out. */
-    names: readonly string[];
-    /** Bucket for unnamed content and framework anchors. Default `'default'`. */
-    fallback?: string;
-    /**
-     * Install the `textContent` guard on the host (default `true`). Opt out only for
-     * a component that never renders a `[data-mono-slot]` region for `fallback`.
-     */
-    guardTextContent?: boolean;
+  /** Named `slot="…"` values this component lays out. */
+  names: readonly string[];
+  /** Bucket for unnamed content and framework anchors. Default `'default'`. */
+  fallback?: string;
+  /**
+   * Install the `textContent` guard on the host (default `true`). Opt out only for
+   * a component that never renders a `[data-mono-slot]` region for `fallback`.
+   */
+  guardTextContent?: boolean;
 }
 /**
  * Take ownership of the host's current children. Run **once**, from
@@ -20,14 +21,14 @@ export interface CaptureLightSlotsOptions {
  */
 export declare function captureLightSlots(host: HTMLElement, options: CaptureLightSlotsOptions): LightSlotBuckets;
 export interface HostTextGuardOptions {
-    /** Bucket a bare text write lands in. Default `'default'`. */
-    fallback?: string;
-    /**
-     * Ran after a write that changed the captured content — normally
-     * `requestUpdate()`, because slot emptiness is read during render and is not
-     * itself reactive.
-     */
-    onWrite?: () => void;
+  /** Bucket a bare text write lands in. Default `'default'`. */
+  fallback?: string;
+  /**
+   * Ran after a write that changed the captured content — normally
+   * `requestUpdate()`, because slot emptiness is read during render and is not
+   * itself reactive.
+   */
+  onWrite?: () => void;
 }
 /**
  * Redirect `host.textContent = …` into the captured default region.
@@ -115,19 +116,20 @@ export declare function bucketHasContent(nodes: Node[] | undefined): boolean;
  * build, and all it needs is connect/disconnect.
  */
 export declare class LateSlotWatcher {
-    private readonly host;
-    private readonly name;
-    private readonly onFound;
-    private _observer?;
-    constructor(host: Element, name: string, onFound: () => void);
-    /**
-     * The host's own child carrying `slot="<name>"`, or `null`.
-     *
-     * Walks `children` rather than running a `:scope >` selector — only a DIRECT child is
-     * assignable to a slot, and this way the check is one cheap loop over a handful of nodes with
-     * no selector engine involved.
-     */
-    find(): Element | null;
-    start(): void;
-    stop(): void;
+  private readonly host;
+  private readonly name;
+  private readonly onFound;
+  private _observer?;
+  constructor(host: Element, name: string, onFound: () => void);
+  /**
+   * The host's own child carrying `slot="<name>"`, or `null`.
+   *
+   * Walks `children` rather than running a `:scope >` selector — only a DIRECT child is
+   * assignable to a slot, and this way the check is one cheap loop over a handful of nodes with
+   * no selector engine involved.
+   */
+  find(): Element | null;
+  start(): void;
+  stop(): void;
 }
+//#endregion

package/dist/src/composables/mdi-glyphs.d.ts

@@ -1,4 +1,6 @@
+//#region src/composables/mdi-glyphs.d.ts
 /** `i-mdi-<name>` → the inner SVG markup of that glyph, on a 24x24 viewBox. */
 export declare const MDI_GLYPHS: Readonly<Record<string, string>>;
 /** The artwork for an `i-mdi-*` class, or `undefined` when it is not bundled. */
 export declare function mdiGlyphBody(icon: string | undefined | null): string | undefined;
+//#endregion

package/dist/src/composables/mono-element.d.ts

@@ -1,3 +1,4 @@
+//#region src/composables/mono-element.d.ts
 type ElementClass = CustomElementConstructor;
 /** Register `cls` as `tag` with the app-wide defaults applied. Returns the registered class. */
 export declare function defineMonoElement<T extends ElementClass>(tag: string, cls: T): T;
@@ -6,4 +7,5 @@ export declare function defineMonoElement<T extends ElementClass>(tag: string, c
  * `createMonoUI` defaults apply and `pending` exists) and replaces the class binding with it.
  */
 export declare function customElement(tag: string): <T extends ElementClass>(cls: T) => T;
-export {};
+//#endregion
+export {};

package/dist/src/composables/mono-event.d.ts

@@ -1,18 +1,19 @@
+//#region src/composables/mono-event.d.ts
 /** Options for {@link dispatchMonoEvent}. */
 export interface MonoEventOptions {
-    /**
-     * The native DOM event this mono event was derived from, if any. Defaults to
-     * `detail.sourceEvent` when that is an `Event` — which is what every model
-     * detail already carries.
-     */
-    sourceEvent?: Event | null;
-    /**
-     * The plain (unprefixed) name to emit. Defaults to `name`. Give a different
-     * one when the mono name is not what the plain event means — `mno-click` on
-     * a modal is an open-state change, so its plain name is `toggle`. `false`
-     * emits no plain event at all.
-     */
-    alias?: string | false;
+  /**
+   * The native DOM event this mono event was derived from, if any. Defaults to
+   * `detail.sourceEvent` when that is an `Event` — which is what every model
+   * detail already carries.
+   */
+  sourceEvent?: Event | null;
+  /**
+   * The plain (unprefixed) name to emit. Defaults to `name`. Give a different
+   * one when the mono name is not what the plain event means — `mno-click` on
+   * a modal is an open-state change, so its plain name is `toggle`. `false`
+   * emits no plain event at all.
+   */
+  alias?: string | false;
 }
 /**
  * Device-originated event names — decorated when native, never synthesized.
@@ -53,3 +54,4 @@ export declare function decorateEvent<T>(event: Event, detail: T): void;
  *   dispatchMonoEvent(this, 'loading-change', detail)                  // loading-change + loadingChange + mno-loading-change + mnoLoadingChange
  */
 export declare function dispatchMonoEvent<T>(target: EventTarget, name: string, detail: T, options?: MonoEventOptions): void;
+//#endregion

package/dist/src/composables/mono-pending.d.ts

@@ -1,8 +1,10 @@
-import { LitElement } from 'lit';
-import { Constructor } from './hybird-prop';
+import { Constructor } from "./hybird-prop.js";
+import { LitElement } from "lit";
+//#region src/composables/mono-pending.d.ts
 /**
  * Applied to every registered element class by the mono `customElement` decorator.
  * The property itself is registered separately (`registerPendingProperty`) so it lands in
  * Lit's attribute map before `customElements.define`.
  */
 export declare function withMonoPending<T extends Constructor<LitElement>>(superClass: T, tag: string): T;
+//#endregion