@mono-lit/helper 0.0.0-stage → 0.0.1

package/dist/src/components/card/card-core.d.ts

@@ -0,0 +1,74 @@
+import { LitElement } from 'lit';
+import { CardSize, CardVariant, CardColor, CardRounded, CardMediaPosition, CardCssClass } from './card-types.js';
+import { Constructor } from '../../composables/hybird-prop';
+import { buildSizeStyle, CssSizeValue } from '../../composables/css-size';
+type CardRootElement = HTMLDivElement | HTMLAnchorElement;
+/** Slot regions the card lays out. `default` is the unnamed body region. */
+export type CardSlotName = 'media' | 'icon' | 'title' | 'subtitle' | 'header' | 'actions' | 'footer' | 'default';
+/** Public + shared-protected surface added by the core mixin. */
+export declare class MonoCardCoreInterface {
+    size: CardSize;
+    variant: CardVariant;
+    color: CardColor;
+    rounded?: CardRounded;
+    mediaPosition: CardMediaPosition;
+    /** Header headline. `heading` is the old name, kept as an alias. */
+    title: string;
+    /** Header secondary line. `subheading` is the old name, kept as an alias. */
+    subtitle: string;
+    /** @deprecated alias of `title` */
+    heading?: string;
+    /** @deprecated alias of `subtitle` */
+    subheading?: string;
+    bordered: boolean;
+    hoverable: boolean;
+    clickable: boolean;
+    selected: boolean;
+    disabled: boolean;
+    loading: boolean;
+    width?: CssSizeValue;
+    height?: CssSizeValue;
+    minWidth?: CssSizeValue;
+    maxWidth?: CssSizeValue;
+    minHeight?: CssSizeValue;
+    maxHeight?: CssSizeValue;
+    headerDivider: boolean;
+    footerDivider: boolean;
+    href?: string;
+    target?: string;
+    ariaLabelText?: string;
+    cssClass: CardCssClass;
+    focus(): void;
+    blur(): void;
+    click(): void;
+    protected _hasMedia: boolean;
+    protected _hasIcon: boolean;
+    protected _hasTitle: boolean;
+    protected _hasSubtitle: boolean;
+    protected _hasHeaderSlot: boolean;
+    protected _hasActions: boolean;
+    protected _hasFooter: boolean;
+    protected _hasDefault: boolean;
+    protected _cardElement?: CardRootElement;
+    protected _cls(base: string, key: keyof CardCssClass): string;
+    protected _sizeStyle(): ReturnType<typeof buildSizeStyle>;
+    protected get _isInteractive(): boolean;
+    protected get _isDisabled(): boolean;
+    protected get _hasHeader(): boolean;
+    protected get _cardClasses(): string;
+    protected _handleClick(event: MouseEvent): void;
+    protected _handleKeyDown(event: KeyboardEvent): void;
+}
+/**
+ * `MonoCardCore` — all render-mode-agnostic logic for `mono-card`: reactive
+ * props, hybrid aliases, the camelCase attribute fallbacks, slot-presence
+ * `@state`, class/getter computation, click/keyboard interactivity, and the
+ * imperative `focus/blur/click`. No `render()` — the light build keeps its
+ * `[data-mono-slot]` capture strategy and the shadow build uses native `<slot>`
+ * (each ships its own `render()`, mirroring `mono-input`).
+ *
+ * SSR-safe: no `document`/`window` access. `_cardElement` (`@query`) is lazy and
+ * `focus/blur/click` + the `HTMLAnchorElement` check only run client-side.
+ */
+export declare const MonoCardCore: <T extends Constructor<LitElement>>(superClass: T) => Constructor<MonoCardCoreInterface> & T;
+export {};

package/dist/src/components/card/card-types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Card Component Type Definitions
+ */
+/**
+ * Content scale of the card — padding, title and subtitle type, the header /
+ * actions / subtitle gaps and the header icon box. The same 6-step scale
+ * accordion, modal, drawer and the form controls use.
+ *
+ * It does **not** set the card's width or height. That is what the `width` /
+ * `height` / `min-*` / `max-*` props (and `--mono-card-*`) are for, so a compact
+ * `size="xs"` card can still be wide. Corner radius is the `shape` prop's job,
+ * not this one.
+ *
+ * Before 2026-08-18 this was a 3-step density scale
+ * (`'compact' | 'md' | 'comfortable'`) that only changed the padding; `compact`
+ * is roughly `sm` and `comfortable` roughly `lg`.
+ */
+export type CardSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+/**
+ * Visual style of the card.
+ *
+ * `'gradient'` was removed with the Basecoat port (2026-09): the design system
+ * has no colour gradients. Use `'tonal'` for a tinted surface.
+ */
+export type CardVariant = 'elevated' | 'outlined' | 'flat' | 'tonal' | 'glass';
+export type CardColor = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'teal' | 'purple' | 'dark' | 'neutral' | 'light';
+export type CardRounded = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl' | 'full';
+export type CardMediaPosition = 'top' | 'bottom';
+/**
+ * Per-element class overrides.
+ *
+ * Example:
+ * cssClass={{
+ *   root: 'my-card',
+ *   header: 'my-card-header',
+ *   body: 'my-card-body',
+ *   actions: 'my-card-actions'
+ * }}
+ */
+export interface CardCssClass {
+    root?: string;
+    media?: string;
+    header?: string;
+    icon?: string;
+    headerContent?: string;
+    title?: string;
+    subtitle?: string;
+    body?: string;
+    actions?: string;
+    footer?: string;
+    loading?: string;
+}
+export interface CardProps {
+    /**
+     * Content scale — padding, type, gaps and the header icon. Not a dimension:
+     * use `width` / `height` for that. See {@link CardSize}.
+     */
+    size?: CardSize;
+    /** Visual style variant of the card. */
+    variant?: CardVariant;
+    /** Color theme of the card. */
+    color?: CardColor;
+    /** Corner radius of the card. */
+    rounded?: CardRounded;
+    /** Position of the media slot (top or bottom). */
+    mediaPosition?: CardMediaPosition;
+    'media-position'?: CardMediaPosition;
+    mediaposition?: CardMediaPosition;
+    /**
+     * Title text shown in the card header. `slot="title"` replaces it, and
+     * `slot="header"` replaces the icon, title and subtitle together.
+     */
+    title?: string;
+    /** Subtitle text shown under the title. `slot="subtitle"` replaces it. */
+    subtitle?: string;
+    /** @deprecated Old name of `title`, still accepted. */
+    heading?: string;
+    /** @deprecated Old name of `subtitle`, still accepted. */
+    subheading?: string;
+    /** Adds a border around the card. */
+    bordered?: boolean;
+    /** Adds a hover elevation effect. */
+    hoverable?: boolean;
+    /** Makes the card interactive and clickable. */
+    clickable?: boolean;
+    /** Applies the selected highlight state. */
+    selected?: boolean;
+    /** Disables interaction and dims the card. */
+    disabled?: boolean;
+    /** Shows a loading overlay on the card. */
+    loading?: boolean;
+    /**
+     * Explicit sizing. Each accepts a CSS length string (`"320px"`, `"80%"`) or a
+     * number (interpreted as px). Use `width="100%"` for a full-width card.
+     */
+    width?: string | number;
+    height?: string | number;
+    minWidth?: string | number;
+    'min-width'?: string | number;
+    maxWidth?: string | number;
+    'max-width'?: string | number;
+    minHeight?: string | number;
+    'min-height'?: string | number;
+    maxHeight?: string | number;
+    'max-height'?: string | number;
+    /** Shows a divider below the header. */
+    headerDivider?: boolean;
+    'header-divider'?: boolean;
+    headerdivider?: boolean;
+    /** Shows a divider above the footer. */
+    footerDivider?: boolean;
+    'footer-divider'?: boolean;
+    footerdivider?: boolean;
+    /** Renders the card as an anchor with this URL. */
+    href?: string;
+    /** Anchor target window when href is set. */
+    target?: string;
+    /** Accessible label text for screen readers. */
+    ariaLabelText?: string;
+    ariaLabel?: string;
+    'aria-label'?: string;
+    'aria-label-text'?: string;
+    arialabel?: string;
+    arialabeltext?: string;
+    /** Per-element class overrides. */
+    cssClass?: CardCssClass;
+    'css-class'?: CardCssClass;
+}
+export interface CardClickEventDetail {
+    originalEvent: MouseEvent | KeyboardEvent;
+}
+export type CardClickEvent = CustomEvent<CardClickEventDetail>;
+export interface CardEvents {
+    click: CardClickEvent;
+    'mno-click': CardClickEvent;
+    mnoClick: CardClickEvent;
+}

package/dist/src/components/card/card-utils.d.ts

@@ -0,0 +1,23 @@
+import { CardVariant, CardColor } from './card-types.js';
+/**
+ * Validate card props
+ */
+export declare function validateCardProps(props: {
+    variant?: CardVariant;
+    color?: CardColor;
+}): boolean;
+/**
+ * Generate root CSS classes for card
+ */
+export declare function generateCardRootClasses(props: {
+    variant?: CardVariant;
+    color?: CardColor;
+    bordered?: boolean;
+    hoverable?: boolean;
+    clickable?: boolean;
+    disabled?: boolean;
+}): string;
+/**
+ * Generate ARIA attributes for accessibility
+ */
+export declare function generateCardAttributes(clickable: boolean, hoverable: boolean, label: string | undefined): Record<string, string | boolean | undefined>;

package/dist/src/components/card/index.d.ts

@@ -0,0 +1,4 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoCard } from './mono-card.js';
+export type { CardSize, CardRounded, CardVariant, CardColor, CardCssClass, CardMediaPosition, CardProps, CardEvents } from './card-types.js';
+export { validateCardProps, generateCardAttributes } from './card-utils.js';

package/dist/src/components/card/index.shadow.d.ts

@@ -0,0 +1,6 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoCardShadow } from './mono-card.shadow.js';
+export { MonoCardCore } from './card-core.js';
+export type { CardSlotName } from './card-core.js';
+export type { CardSize, CardRounded, CardVariant, CardColor, CardCssClass, CardMediaPosition, CardProps, CardEvents, } from './card-types.js';
+export { validateCardProps, generateCardAttributes, } from './card-utils.js';

package/dist/src/components/card/mono-card.d.ts

@@ -0,0 +1,56 @@
+import { LitElement, TemplateResult } from 'lit';
+declare const MonoCard_base: import('../../composables/hybird-prop').Constructor<import('./card-core.js').MonoCardCoreInterface> & typeof LitElement;
+/**
+ * Light-DOM `mono-card` (default build, `@mono-lit/helper/ui/card`).
+ *
+ * Renders into the host (`createRenderRoot`→`this`, styled by the global
+ * `dist/ui/index.css`) with the light-DOM slot strategy: `slot="media|icon|…"`
+ * children are captured in `connectedCallback`, the template renders empty
+ * `[data-mono-slot]` regions, and the captured nodes are re-appended in
+ * `updated()`. Capture/placement lives in `composables/light-slots`, which is
+ * careful to carry the consumer framework's positional anchors (Vue's
+ * `<!--v-if-->` comments and zero-length Fragment text nodes) into the region
+ * alongside their siblings — deleting them used to detach Vue's vnode anchors and
+ * crash its next patch with `Cannot read properties of null`. The first render is
+ * forced **synchronously** from `connectedCallback` (see there) so the detach and
+ * re-attach happen in one uninterrupted step, which is what lets cards nest freely.
+ *
+ * All render-mode-agnostic logic lives in `MonoCardCore`. The shadow build
+ * (`@mono-lit/helper/ui/shadow/card`) shares the mixin but uses native `<slot>` and
+ * registers a distinct `<mono-shadow-card>` tag, so both builds can load in the
+ * same document.
+ */
+export declare class MonoCard extends MonoCard_base {
+    static styles: import('lit').CSSResult[];
+    protected createRenderRoot(): HTMLElement;
+    private _slotsCaptured;
+    private _buckets;
+    private _renderMedia;
+    private _renderHeader;
+    /**
+     * The body is the only region rendered unconditionally.
+     *
+     * It's the home for the fallback bucket, which holds the consumer framework's
+     * positional anchors. Those need a live parent even when the card starts with
+     * no visible body content — that's what lets a `v-if` flipping on later insert
+     * *inside* the card instead of beside it, and it stops Lit from ever destroying
+     * a container that holds the consumer's nodes. `.mono-card-body:empty` collapses
+     * it while it holds nothing but anchors.
+     */
+    private _renderBody;
+    private _renderActions;
+    private _renderFooter;
+    private _renderLoading;
+    private _renderContent;
+    protected render(): TemplateResult;
+    connectedCallback(): void;
+    private _captureSlots;
+    protected updated(changed: Map<string, unknown>): void;
+    private _parked?;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'mono-card': MonoCard;
+    }
+}
+export {};

package/dist/src/components/card/mono-card.shadow.d.ts

@@ -0,0 +1,52 @@
+import { LitElement, TemplateResult } from 'lit';
+declare const MonoCardShadow_base: import('../../composables/hybird-prop').Constructor<import('./card-core.js').MonoCardCoreInterface> & typeof LitElement;
+/**
+ * Shadow-DOM card (the opt-in SSR build, `@mono-lit/helper/ui/shadow/card`).
+ *
+ * Registered as `<mono-shadow-card>` — a DISTINCT tag from the light build's
+ * `<mono-card>` — so the two can be loaded side by side (e.g. the VitePress docs
+ * render both live). Like every shadow component, it registers a `mono-shadow-*`
+ * tag; consumers of `@mono-lit/helper/ui/shadow/card` write `<mono-shadow-card>`.
+ *
+ * Real shadow root + `static styles`, so `@lit-labs/ssr` serializes it to
+ * Declarative Shadow DOM and styles are scoped (`mono-card`→`:host`). Slotting
+ * uses native `<slot>`. During SSR the element has no light children, so every
+ * `_has…` defaults `false` (hydration-matching) and the decorative regions render
+ * `mono-empty` (hidden by card.css itself); real presence is corrected in
+ * `firstUpdated()` (DSD assigns slotted content at parse time → `slotchange`
+ * doesn't fire after upgrade → scan `assignedNodes()`; `slotchange` is kept for
+ * later dynamic changes). `<slot name="title">${title}</slot>` carries the prop
+ * text as native fallback so it shows with no JS. The body/default region is
+ * always visible so main content never flashes. Shares all logic with the light
+ * build via `MonoCardCore`.
+ */
+export declare class MonoCardShadow extends MonoCardShadow_base {
+    static styles: import('lit').CSSResult[];
+    firstUpdated(changed: Map<string, unknown>): void;
+    private _slotFor;
+    /**
+     * Whether something is ASSIGNED to this slot. Not `flatten: true`: for an
+     * empty slot that returns the FALLBACK content, and `<slot name="header">`'s
+     * fallback is the title/subtitle markup — every card would look like it had a
+     * header slot and hide its icon.
+     */
+    private _slotHasContent;
+    private _setSlotState;
+    private _onSlotChange;
+    private _slot;
+    private _renderMedia;
+    private _renderHeader;
+    private _renderBody;
+    private _renderActions;
+    private _renderFooter;
+    private _renderLoading;
+    private _renderContent;
+    protected render(): TemplateResult;
+    connectedCallback(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'mono-shadow-card': MonoCardShadow;
+    }
+}
+export {};

package/dist/src/components/chart/chart-core.d.ts

@@ -0,0 +1,43 @@
+import { LitElement, TemplateResult } from 'lit';
+import { Constructor } from '../../composables/hybird-prop';
+import { CssSizeValue } from '../../composables/css-size';
+import { ChartCssClass, MonoChartColor, MonoChartController, MonoChartData, MonoChartType } from './chart-types.js';
+export declare function loadChartJs(): Promise<any>;
+/** Public surface added by the chart core mixin. */
+export declare class MonoChartCoreInterface {
+    dataChart?: MonoChartController;
+    /** Pull `controlMonoChart({ props })` onto this element. */
+    protected _applyControllerProps(): void;
+    type?: MonoChartType;
+    /** Set by the presets to lock their type; undefined on the generic element. */
+    protected _presetType?: MonoChartType;
+    /** The shared template — each build calls this from its own `render()`. */
+    protected renderChart(): TemplateResult;
+    data?: MonoChartData;
+    chartOptions?: Record<string, unknown>;
+    width?: CssSizeValue;
+    height?: CssSizeValue;
+    aspectRatio: number;
+    legend: boolean | string;
+    title: string;
+    stacked: boolean;
+    color?: MonoChartColor | string;
+    colors?: string | string[];
+    cssClass: ChartCssClass;
+    cssClassName: string;
+    /** The live chart.js instance, or null. */
+    readonly chart: unknown;
+    /** Force a full teardown + recreate. */
+    rebuild(): void;
+}
+/**
+ * `MonoChartCore` — render-mode-agnostic logic for the chart elements.
+ *
+ * It owns the imperative Chart.js lifecycle, following the same shape as the
+ * flatpickr wrapper in `date-core.ts`: create in `firstUpdated` behind an
+ * `isServer` guard and a dynamic import, split `updated()` into a cheap data
+ * update vs a full rebuild, and destroy in `disconnectedCallback` BEFORE
+ * `super`. A `ResizeObserver` is added on top because, unlike flatpickr, a
+ * canvas needs to be told when its box changes.
+ */
+export declare const MonoChartCore: <T extends Constructor<LitElement>>(superClass: T) => Constructor<MonoChartCoreInterface> & T;

package/dist/src/components/chart/chart-odata.d.ts

@@ -0,0 +1,52 @@
+import { arrayToODataString } from '../filter/filter-odata.js';
+import { MonoDataSourceOptions } from '../../utils/data-source-options.js';
+import { MonoChartAggregateCtx, MonoChartSeries } from './chart-types.js';
+/**
+ * Build `groupby((<groupBy>),aggregate(<field> with <agg> as <field>, …))`.
+ *
+ * Each aggregate is aliased back to **its own series field**, which is what lets
+ * the result flow through the chart's existing projection untouched: one row per
+ * bucket, and re-aggregating a single value is the identity. No special-casing
+ * downstream, and a client-side roll-up and a server-side one render identically.
+ *
+ * `count` has no operand, so it emits `$count as <field>`.
+ */
+export declare function buildChartApply(groupBy: string, series?: readonly MonoChartSeries[]): string;
+/**
+ * Compose a filter with a groupby: `filter(<expr>)/groupby(…)`.
+ *
+ * Filtering INSIDE `$apply` (rather than as a sibling `$filter`) is what keeps the
+ * two composable — the filter runs first and the aggregation sees only matching
+ * rows, which is the whole point of doing this server-side.
+ */
+export declare function composeApply(apply: string, filter: unknown): string;
+/** Re-exported so an `aggregate()` hook can convert a devextreme filter itself. */
+export { arrayToODataString as chartODataFilter };
+/** What `buildChartOdataRequest` hands to the transport. */
+export interface MonoChartOdataRequest {
+    /** devextreme load options for the DataSource `monoOdataFetch` builds. */
+    options: Record<string, unknown>;
+    /** Raw query-string parameters (`$apply`, custom keys) — sent verbatim. */
+    params: Record<string, unknown>;
+    /** Whether the rows will come back rolled up (an `$apply` was built). */
+    aggregated: boolean;
+}
+/**
+ * Compose the request an `odata` chart sends — pure, so the merge of
+ * `odata.options` with the controller's base (`dataSourceOptions` /
+ * `odataOptions`) and the `$apply` folding can be asserted without a network.
+ *
+ * The base's `filter` is AND-ed under `odata.options.filter`; its `select` /
+ * `expand` / `sort` / `paginate` become load options; its `customQueryParams`
+ * become raw params beside `$apply`. On the `$apply` path the composed filter
+ * travels INSIDE the clause (that is what keeps it composable with the grouping)
+ * and is removed from the load options so it is not also sent as a sibling
+ * `$filter`; `paginate` is forced off so every bucket comes back.
+ */
+export declare function buildChartOdataRequest(input: {
+    options?: Record<string, unknown>;
+    base?: MonoDataSourceOptions;
+    aggregate?: (ctx: MonoChartAggregateCtx) => string;
+    groupBy?: string;
+    series: readonly MonoChartSeries[];
+}): MonoChartOdataRequest;