@mono-lit/helper 0.0.0-stage → 0.0.1

package/dist/src/components/tooltip/control-tooltip.d.ts

@@ -0,0 +1,36 @@
+import { MonoTooltipController, MonoTooltipOptions, MonoTooltipTarget } from './tooltip-types';
+/**
+ * A REAL document. `typeof document` is not enough on the server: Lit's SSR DOM shim (loaded by
+ * VitePress / Nuxt SSR through @mono-lit/helper's server entries) defines a global `document` stub with no
+ * `addEventListener`, so a `typeof` guard passed and `createMonoTooltip()` in an app's setup threw
+ * "document.addEventListener is not a function" during server render.
+ */
+export declare function hasLiveDocument(): boolean;
+/** Prefix of the declarative anchor attributes (`mono-tooltip-content`, …). */
+export declare const ANCHOR_ATTR_PREFIX = "mono-tooltip-";
+/**
+ * Attach a tooltip to every element `target` names — now or later.
+ *
+ * ```ts
+ * // <script setup> — the elements need not exist yet
+ * const tip = controlMonoTooltip('.save-btn', { content: 'Save changes', placement: 'bottom' })
+ * onBeforeUnmount(() => tip.destroy())
+ * ```
+ *
+ * `target` is a CSS selector, an element, a list of elements, or a Vue ref /
+ * getter of any of those. Light `<mono-*>` elements, shadow `<mono-shadow-*>`
+ * hosts and elements inside open shadow roots all match.
+ *
+ * Needs the optional peers `@floating-ui/dom` + `@floating-ui/core`, loaded on
+ * the first show. Options set with `createMonoTooltip` override these.
+ */
+export declare function controlMonoTooltip(target: MonoTooltipTarget, options?: MonoTooltipOptions): MonoTooltipController;
+/**
+ * @internal — a controller with a per-anchor options layer. Used by the
+ * declarative `mono-tooltip-*` attributes (`tooltip-declarative.ts`).
+ */
+export declare function createTooltipController(target: MonoTooltipTarget, options: MonoTooltipOptions, anchorOptions: (anchor: Element) => MonoTooltipOptions): MonoTooltipController;
+/** Alias, matching the `monoX` / `controlMonoX` pairs of the other controllers. */
+export declare const monoTooltip: typeof controlMonoTooltip;
+/** @internal — close and forget every live controller. Public as `destroyAllMonoTooltips`. */
+export declare function destroyAllTooltipControllers(): void;

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

@@ -0,0 +1,6 @@
+/// <reference path="../../../vue.d.ts" />
+export { controlMonoTooltip, monoTooltip } from './control-tooltip';
+export { createMonoTooltip, resetMonoTooltip, destroyAllMonoTooltips, readTooltipAttributes, TOOLTIP_ATTRIBUTE_SELECTOR, } from './tooltip-declarative';
+export { getMonoTooltipGlobal, resolveTooltipOptions, DEFAULT_TOOLTIP_OPTIONS } from './tooltip-config';
+export { loadFloatingUi } from './tooltip-loader';
+export type { MonoTooltipOptions, MonoTooltipGlobalOptions, MonoTooltipGlobal, MonoTooltipController, MonoTooltipTarget, MonoTooltipTargetValue, MonoTooltipContent, MonoTooltipPlacement, MonoTooltipTrigger, MonoTooltipVariant, MonoTooltipColor, MonoTooltipSize, } from './tooltip-types';

package/dist/src/components/tooltip/tooltip-config.d.ts

@@ -0,0 +1,27 @@
+import { MonoTooltipGlobalOptions, MonoTooltipOptions } from './tooltip-types';
+export declare const DEFAULT_TOOLTIP_OPTIONS: {
+    allowHTML: false;
+    placement: "top";
+    offset: number;
+    padding: number;
+    flip: true;
+    shift: true;
+    arrow: true;
+    trigger: ("focus" | "hover")[];
+    delay: [number, number];
+    interactive: false;
+    variant: "inverted";
+    size: "md";
+    disabled: false;
+    hideOnClick: true;
+};
+export type ResolvedTooltipOptions = MonoTooltipOptions & typeof DEFAULT_TOOLTIP_OPTIONS;
+/** @internal — written by `createMonoTooltip` / `resetMonoTooltip`. */
+export declare function setMonoTooltipGlobal(options: MonoTooltipGlobalOptions | null): void;
+/** The current global options, or `null` when none were set. */
+export declare function getMonoTooltipGlobal(): Readonly<MonoTooltipGlobalOptions> | null;
+/**
+ * `DEFAULTS ← local ← global ← anchor`, key by key; `undefined` never
+ * overwrites. `anchor` is the options read off the element's own attributes.
+ */
+export declare function resolveTooltipOptions(local?: MonoTooltipOptions | null, anchor?: MonoTooltipOptions | null): ResolvedTooltipOptions;

package/dist/src/components/tooltip/tooltip-declarative.d.ts

@@ -0,0 +1,41 @@
+import { MonoTooltipGlobal, MonoTooltipGlobalOptions, MonoTooltipOptions } from './tooltip-types';
+/** The two text attributes — `message` is an alias of `content`. */
+export declare const TOOLTIP_ATTRIBUTE_SELECTOR = "[mono-tooltip-content], [mono-tooltip-message]";
+/**
+ * Per-element options, from `mono-tooltip-<option>` attributes:
+ *
+ * | attribute | option |
+ * | --- | --- |
+ * | `mono-tooltip-content` / `-message` | `content` (text) |
+ * | `mono-tooltip-placement` / `-variant` / `-color` / `-size` | same name |
+ * | `mono-tooltip-trigger` | `"hover focus"`, `"click"`, … |
+ * | `mono-tooltip-delay` | `"300"` or `"300 100"` |
+ * | `mono-tooltip-offset` / `-padding` | numbers |
+ * | `mono-tooltip-max-width` / `-class` | strings |
+ * | `mono-tooltip-arrow` / `-flip` / `-shift` / `-interactive` / `-html` / `-disabled` / `-hide-on-click` | booleans — present = on, `"false"` = off |
+ */
+export declare function readTooltipAttributes(el: Element): MonoTooltipOptions;
+/**
+ * Set the app-wide tooltip options AND switch on the `mono-tooltip-*` attributes.
+ * Call once — usually in `main.ts`:
+ *
+ * ```ts
+ * app.use(createMonoTooltip({ delay: [300, 0] }))
+ * // or simply
+ * createMonoTooltip()
+ * ```
+ *
+ * The options WIN over the ones passed to `controlMonoTooltip`; an element's own
+ * `mono-tooltip-*` attributes win over them. A later call replaces the previous
+ * global options wholesale. `attributes: false` keeps the options but turns the
+ * declarative attributes off.
+ */
+export declare function createMonoTooltip(options?: MonoTooltipGlobalOptions): MonoTooltipGlobal;
+/**
+ * Close and forget every live tooltip controller — the attribute one included
+ * (a later `createMonoTooltip()` turns the attributes back on). For tests and a
+ * full app teardown; the global options are kept.
+ */
+export declare function destroyAllMonoTooltips(): void;
+/** Drop the global options and turn the attributes off (tests, runtime reconfiguration). */
+export declare function resetMonoTooltip(): void;

package/dist/src/components/tooltip/tooltip-loader.d.ts

@@ -0,0 +1 @@
+export declare function loadFloatingUi(): Promise<typeof import('@floating-ui/dom')>;

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

@@ -0,0 +1,110 @@
+import { MaybeReactive } from '../../composables/reactive';
+type Side = 'top' | 'right' | 'bottom' | 'left';
+export type MonoTooltipPlacement = Side | `${Side}-start` | `${Side}-end`;
+/** What opens the tooltip. `manual` = only `show()` / `hide()` do. */
+export type MonoTooltipTrigger = 'hover' | 'focus' | 'click' | 'manual';
+/** `inverted` = Basecoat's dark-on-light chip (default); `popover` = the dropdown surface. */
+export type MonoTooltipVariant = 'inverted' | 'popover';
+export type MonoTooltipColor = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'teal' | 'purple' | 'neutral' | 'dark';
+export type MonoTooltipSize = 'sm' | 'md' | 'lg';
+/**
+ * The tooltip body. A function is called with the ANCHOR on every show, so one
+ * `controlMonoTooltip('.row-action', …)` can say something different per row.
+ * Returning `null` / `''` skips the show.
+ */
+export type MonoTooltipContent = string | Node | ((anchor: Element) => string | Node | null | undefined);
+/** Anything that names the elements to decorate. */
+export type MonoTooltipTargetValue = string | Element | null | undefined | ArrayLike<Element> | Iterable<Element>;
+/**
+ * A CSS selector (`'.save'`, `'#id'`, `'[data-tip]'`, `'mono-button'`), an element,
+ * a list of elements, or a Vue `ref` / getter of any of those — re-read on every
+ * pointer / focus event, so a ref that is still `null` in `<script setup>` just
+ * starts matching once the element mounts.
+ */
+export type MonoTooltipTarget = MaybeReactive<MonoTooltipTargetValue>;
+export interface MonoTooltipOptions {
+    /**
+     * The text (or node) to show. When omitted the anchor supplies it:
+     * `mono-tooltip-content` → `mono-tooltip-message` → `title` → `aria-label`.
+     */
+    content?: MonoTooltipContent;
+    /** Treat string content as HTML. Default `false` (set as text). */
+    allowHTML?: boolean;
+    /** Preferred side (+ alignment). Default `'top'`. Flipped when there is no room. */
+    placement?: MonoTooltipPlacement;
+    /** Gap between the anchor and the tooltip, px. Default `6`. */
+    offset?: number;
+    /** Viewport padding kept by flip/shift, px. Default `8`. */
+    padding?: number;
+    /** Flip to the opposite side when the preferred one overflows. Default `true`. */
+    flip?: boolean;
+    /** Slide along the anchor to stay inside the viewport. Default `true`. */
+    shift?: boolean;
+    /** Draw the pointer arrow. Default `true`. */
+    arrow?: boolean;
+    /** What opens it. Default `['hover', 'focus']`. */
+    trigger?: MonoTooltipTrigger | MonoTooltipTrigger[];
+    /** Open / close delay in ms — one number for both, or `[show, hide]`. Default `[100, 0]`. */
+    delay?: number | [number, number];
+    /** Keep it open while the pointer is over the tooltip itself (links, buttons inside). Default `false`. */
+    interactive?: boolean;
+    /** CSS `max-width` of the bubble. Default: `--mono-tooltip-max-width`, else `20rem`. */
+    maxWidth?: string;
+    variant?: MonoTooltipVariant;
+    /** Paint the bubble in a palette colour instead of the variant's surface. */
+    color?: MonoTooltipColor;
+    size?: MonoTooltipSize;
+    /** Extra class(es) on the floating element. */
+    class?: string;
+    /** Where the floating element is appended. Default `document.body`. */
+    appendTo?: Element | (() => Element | null);
+    /** Stop opening (an open one closes). Default `false`. */
+    disabled?: boolean;
+    /** Close a hover/focus tooltip when its anchor is clicked. Default `true`. */
+    hideOnClick?: boolean;
+    /** Before it opens — return `false` to cancel. */
+    onShow?: (anchor: Element, tooltip: HTMLElement) => void | boolean;
+    /** Before it closes — return `false` to keep it. */
+    onHide?: (anchor: Element, tooltip: HTMLElement) => void | boolean;
+}
+/**
+ * What `createMonoTooltip` / Nuxt's `mono.helper.tooltip` take: every tooltip
+ * option (applied app-wide) plus the addon switches below. The Nuxt config
+ * additionally has to be JSON — no functions, no nodes.
+ */
+export interface MonoTooltipGlobalOptions extends MonoTooltipOptions {
+    /**
+     * Turn on the declarative attributes — any element (plain HTML, light or
+     * shadow `<mono-*>`) with `mono-tooltip-content="…"` (or `mono-tooltip-message`)
+     * gets a tooltip, no `controlMonoTooltip` call needed. Default `true`.
+     */
+    attributes?: boolean;
+}
+/** What `controlMonoTooltip(...)` returns. */
+export interface MonoTooltipController {
+    /** Open on `anchor` (default: the first element the target currently resolves to). */
+    show(anchor?: Element): Promise<void>;
+    hide(): void;
+    toggle(anchor?: Element): Promise<void>;
+    /** Merge into this controller's own options (global options still win). */
+    update(options: Partial<MonoTooltipOptions>): void;
+    /** Replace the content; an open tooltip re-renders in place. */
+    setContent(content: MonoTooltipContent | undefined): void;
+    enable(): void;
+    disable(): void;
+    /** True while the tooltip is on screen. */
+    readonly isOpen: boolean;
+    /** The element it is currently open on, else `null`. */
+    readonly anchor: Element | null;
+    /** The floating element while open, else `null`. */
+    readonly tooltip: HTMLElement | null;
+    /** Close it and stop listening. Call from `onBeforeUnmount`. */
+    destroy(): void;
+}
+/** What `createMonoTooltip(...)` returns — also a Vue plugin (`app.use(...)`). */
+export interface MonoTooltipGlobal {
+    readonly options: Readonly<MonoTooltipGlobalOptions>;
+    /** Vue plugin hook — a no-op; the options are already applied by the call. */
+    install(app?: unknown): void;
+}
+export {};

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

@@ -0,0 +1,59 @@
+/**
+ * Shared viewport breakpoints — Tailwind's values, so `auto-fullscreen="lg"` in a
+ * mono component and `lg:` in the consumer's utility classes agree on where the
+ * boundary is.
+ *
+ * The library already hard-codes `@media (max-width: 640px)` in `button.css`,
+ * `card.css` and `nav.css`; those stay as they are. This module exists because
+ * `autoFullscreen` needs the same five tokens in two components plus the matching
+ * JS check, and three copies of a magic number is where it stops being fine.
+ *
+ * `sidebar-utils.ts` keeps its own `SIDEBAR_AUTO_BREAKPOINT = 768` deliberately —
+ * re-pointing it here would silently change the sidebar's auto-temporary threshold.
+ */
+export declare const MONO_BREAKPOINTS: {
+    readonly sm: 640;
+    readonly md: 768;
+    readonly lg: 1024;
+    readonly xl: 1280;
+    readonly '2xl': 1536;
+};
+export type MonoBreakpoint = keyof typeof MONO_BREAKPOINTS;
+/**
+ * `autoFullscreen`'s value: `false` off, `true` = the default `sm`, or a token to
+ * move the boundary. "lg" means **lg and below** — i.e. everything Tailwind's `lg:`
+ * prefix does NOT match.
+ */
+export type MonoAutoFullscreen = boolean | MonoBreakpoint;
+/**
+ * Normalise the prop to the breakpoint it should act at, or `null` when off.
+ *
+ * An unrecognised token falls back to `sm` rather than switching the feature off:
+ * the author clearly asked for auto-fullscreen, and silently ignoring them is the
+ * worse failure. Warns once in dev.
+ */
+export declare function resolveAutoFullscreen(value: MonoAutoFullscreen | string | undefined | null): MonoBreakpoint | null;
+/**
+ * Lit converter for the `auto-fullscreen` attribute.
+ *
+ * Modelled on `booleanStringConverter` (composables/hybird-prop.ts), including its
+ * non-string guard: nuxt-ssr-lit forwards the raw PROPERTY value into
+ * `fromAttribute`, so a real boolean can arrive here instead of a string.
+ */
+export declare const autoFullscreenConverter: {
+    fromAttribute(value: unknown): MonoAutoFullscreen;
+    toAttribute(value: MonoAutoFullscreen): string | null;
+};
+/**
+ * Is the viewport currently at or below `bp`?
+ *
+ * Guard order copied from `sidebar-utils.ts`: `typeof window === 'undefined'` alone
+ * is NOT a safe server check, because a DOM shim can define `window` without
+ * `matchMedia`. Check lit's `isServer` first, then feature-detect.
+ *
+ * Deliberately point-in-time with no listener — the only callers are pointer
+ * handlers (the modal's header drag, the drawer's resize start), so there is
+ * nothing to re-render from and nothing to leak. Every VISUAL decision is made by
+ * the `@media` blocks in modal.css / drawer.css, which have no SSR surface at all.
+ */
+export declare function isBelowBreakpoint(bp: MonoBreakpoint): boolean;

package/dist/src/composables/chip-limits.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Selection limits and display caps shared by `<mono-tag-input>` and
+ * `<mono-dropdown-table>`.
+ *
+ * Two independent pairs:
+ *
+ * - `max` / `min` — how many chips the USER can have selected. A pick past `max`
+ *   is rejected (nothing is disabled — the row stays clickable, the pick simply
+ *   does not land); a removal under `min` is rejected the same way, chips at the
+ *   floor lose their ✕ and the field's clear button hides.
+ * - `maxVisible` / `minVisible` — how many chips are DRAWN. Past `maxVisible` the
+ *   rest collapse into a "+N more" chip whose panel lists them, in `flex` and
+ *   `inline` alike. `minVisible` is the collapse floor: while the total is at or
+ *   under it every chip is drawn, however small `maxVisible` is — so a field is
+ *   never collapsed for the sake of one or two chips.
+ *
+ * Each key can be set on the element (`max`, `max-visible`, …) or on the `chip`
+ * object, camel or kebab (`chip.maxVisible`, `chip['max-visible']`). The chip key
+ * PINS, the element prop is the fallback — the rule `chip.color` / `chip.variant`
+ * already follow.
+ */
+export type ChipLimitKey = 'max' | 'min' | 'maxVisible' | 'minVisible';
+/** The limit keys the `chip` object accepts, in both spellings. */
+export interface ChipLimitProps {
+    /** Most chips the user can select (unset = unlimited). Pins the element's `max`. */
+    max?: number;
+    /** Fewest chips the user can leave (unset = 0). Pins the element's `min`. */
+    min?: number;
+    /** Chips drawn before "+N more" (unset = all). Pins the element's `max-visible`. */
+    maxVisible?: number;
+    'max-visible'?: number;
+    /** Never collapse while the total is at or under this. Pins `min-visible`. */
+    minVisible?: number;
+    'min-visible'?: number;
+}
+/** A non-negative integer, or undefined for anything that is not one (`''`, null, NaN, -1). */
+export declare function limitNumber(value: unknown): number | undefined;
+/**
+ * Resolve one limit: the `chip` object's key (camel, then kebab) pins, the
+ * element's own prop is the fallback. Sanitised through {@link limitNumber}.
+ */
+export declare function resolveChipLimit(chip: ChipLimitProps | null | undefined, key: ChipLimitKey, elementValue: unknown): number | undefined;
+/**
+ * How many chips to draw before the rest collapse into "+N more" — `Infinity`
+ * when there is no cap, when the cap is `0` (uncapped, like before), or while
+ * the total sits at or under the collapse floor.
+ */
+export declare function visibleChipCap(total: number, maxVisible: number | undefined, minVisible: number | undefined): number;

package/dist/src/composables/chip-strip.d.ts

@@ -0,0 +1,93 @@
+import { ReactiveController, ReactiveControllerHost } from 'lit';
+export interface ChipStripOptions {
+    /** The scrolling strip, or `null` when the host is not rendering one. */
+    strip: () => HTMLElement | null;
+    /**
+     * Whether inline behaviour is active. False means the host renders no strip,
+     * so the controller stays completely inert — no observer, no queries, no
+     * layout reads. This is what keeps `flex` mode free.
+     */
+    enabled: () => boolean;
+}
+export declare class ChipStripController implements ReactiveController {
+    private readonly host;
+    private readonly opts;
+    private _canScrollStart;
+    private _canScrollEnd;
+    private _observer;
+    /** The element the observer is attached to, so a re-render can re-target it. */
+    private _observed;
+    constructor(host: ReactiveControllerHost, opts: ChipStripOptions);
+    /** True once the strip is scrolled away from its start — render `‹`. */
+    get canScrollStart(): boolean;
+    /** True while content remains past the right edge — render `›`. */
+    get canScrollEnd(): boolean;
+    /** True when either button should show — i.e. the chips overflow the strip. */
+    get overflowing(): boolean;
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * Only re-target the observer — deliberately does NOT measure. Measuring here
+     * would force a layout on every render of every host, and its `requestUpdate`
+     * would schedule an update from inside `updated()`. `invalidate()` and the
+     * ResizeObserver cover the cases that can actually change the answer.
+     */
+    hostUpdated(): void;
+    /**
+     * Re-measure because the CONTENT changed — a chip added, removed or relabelled.
+     * The host calls this from `updated()` when such state actually changed, which
+     * is far rarer than "every update".
+     */
+    invalidate(): void;
+    /**
+     * Recompute both flags from the live geometry and re-render only when one
+     * actually flipped.
+     */
+    sync(): void;
+    /**
+     * Scroll one "page" toward `dir`, aligned to a chip boundary so a chip is
+     * never left half-cut at the leading edge.
+     *
+     * Forward: the first chip whose right edge passes the visible right edge
+     * becomes the new leftmost chip. Backward: the chip that would end at the
+     * current left edge becomes the new leftmost chip. If no chip qualifies
+     * (one chip wider than the strip), fall back to a plain viewport-width step
+     * so the button is never a no-op.
+     */
+    page(dir: -1 | 1): void;
+    /** Pin the strip to its end — used after a chip is added, to reveal it. */
+    scrollToEnd(): void;
+    /**
+     * Move the strip and republish from the CLAMPED TARGET rather than by reading
+     * `scrollLeft` back.
+     *
+     * Scrolling is instant (no `scroll-behavior: smooth`), so the read would agree
+     * — but not reading avoids a second forced layout, and more importantly the
+     * strip's scroll events are expensive well beyond this controller: the shared
+     * popup controller listens for `scroll` on `window` in the CAPTURE phase, so
+     * every scroll event the strip emits repositions any open dropdown, forcing a
+     * layout and a `getComputedStyle` ancestor walk. One event per click is the
+     * budget; a smooth animation's ~30 was what made the page crawl.
+     */
+    private _scrollTo;
+    /**
+     * Store the flags and re-render only on a real change.
+     *
+     * The request is deferred a microtask: `invalidate()` / `scrollToEnd()` are
+     * called from the host's `updated()` (a chip landed, a preset value arrived),
+     * and a synchronous `requestUpdate()` there is Lit's change-in-update warning
+     * on every such edge. The flags are already stored, so the deferred render
+     * reads the same answer — it just doesn't get scheduled from inside the
+     * render that asked for it.
+     */
+    private _publish;
+    /**
+     * Observe the strip so the buttons re-evaluate when the FIELD is resized —
+     * a window resize changes `clientWidth` without any render or scroll event.
+     *
+     * Only the strip is observed, not the chips: a chip add/remove always comes
+     * with a host render, and the host calls `invalidate()` for those.
+     */
+    private _attach;
+    private _teardown;
+}

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

@@ -0,0 +1,103 @@
+/**
+ * Colour parsing and contrast, for props that accept a raw CSS colour.
+ *
+ * `mono-sidebar`, `mono-nav` and `mono-menu` take a `color` that is either a theme token
+ * name or a literal colour (`#7c3aed`, `rgb(124 58 237)`). A token resolves entirely in
+ * CSS — the component sets a `-preset` var and the stylesheet reads `--theme-<name>` and
+ * the matching `--theme-<name>-contrast`. A literal has no such tokens, so two values
+ * have to be derived here instead: the `r, g, b` triple the `--*-rgb` half of the API
+ * expects, and the ink that stays readable on it.
+ *
+ * Everything is a pure function over the prop's own string — no `getComputedStyle`, no
+ * DOM — so it runs unchanged during SSR, where the component renders before any
+ * stylesheet has been applied.
+ *
+ * Scope note: `src/components/chart/mono-data-chart.ts` has its own private `toRgb`.
+ * It is deliberately left alone — it feeds Chart.js canvas paint, which cannot resolve
+ * `var()` and has different needs.
+ */
+export interface Rgba {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** The two inks the theme uses on a filled surface (`index.css` `--theme-*-contrast`). */
+export declare const INK_LIGHT = "#ffffff";
+export declare const INK_DARK = "rgba(0, 0, 0, 0.87)";
+/**
+ * Parse a literal CSS colour to sRGB, or null when it isn't one we can read.
+ *
+ * Handles `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()/rgba()` and `hsl()/hsla()` in
+ * both the legacy comma syntax and the modern space syntax. Returns null for anything
+ * else — `var(…)`, `color-mix(…)`, a named keyword — which callers treat as "paint it,
+ * but fall back for the derived values", since the browser can still render it.
+ */
+export declare function parseCssColor(value: string | undefined | null): Rgba | null;
+/** WCAG relative luminance. */
+export declare function relativeLuminance({ r, g, b }: Rgba): number;
+/** WCAG contrast ratio, 1–21. Order of the arguments does not matter. */
+export declare function contrastRatio(a: Rgba, b: Rgba): number;
+/**
+ * The better of the theme's two inks for text sitting ON `value`, or null when the
+ * colour can't be parsed (the caller then leaves the ink alone and the CSS default —
+ * white, matching every `--theme-*-contrast` but warning's — applies).
+ *
+ * Compares actual contrast rather than thresholding luminance, so it stays correct for
+ * mid-tone colours where a fixed cutoff picks the worse of the two.
+ */
+export declare function readableInk(value: string | undefined | null): string | null;
+/**
+ * `"r, g, b"` for the `--*-rgb` half of the colour API, which the stylesheets wrap in
+ * `rgba(var(--…-rgb), α)`. Null when unparseable.
+ */
+export declare function toRgbTriple(value: string | undefined | null): string | null;
+/**
+ * Does this look like a literal colour rather than a token name?
+ *
+ * Only used AFTER the component's own token list has been checked, so `teal` and
+ * `purple` — which are both theme slots and CSS keywords — always mean the theme slot.
+ * Bare CSS keywords are deliberately not recognised here: a typo like `primry` should
+ * fall through to the validator's warning instead of being silently painted as nothing.
+ */
+export declare function isRawColorValue(value: string | undefined | null): boolean;
+/**
+ * The brand slots `src/data/theme/index.css` defines, in the order they appear there.
+ * Every one has a `--theme-<name>`, a `--theme-<name>-rgb` and a `--theme-<name>-contrast`,
+ * so a component only has to name the slot for the whole treatment to follow the active
+ * colour preset. `surface` is not here — it is each component's "not painted" state, not
+ * a palette entry.
+ */
+export declare const THEME_COLOR_TOKENS: readonly ["primary", "secondary", "success", "danger", "warning", "info", "teal", "purple", "neutral", "dark"];
+export type ThemeColorToken = (typeof THEME_COLOR_TOKENS)[number];
+/** The class token emitted for a `color` that is a literal rather than a slot name. */
+export declare const CUSTOM_COLOR_CLASS = "custom";
+export declare function isThemeColorToken(value: string | undefined | null): boolean;
+/**
+ * The class token for a `color` value.
+ *
+ * A literal MUST NOT reach the class list: the class string is built with `join(' ')`,
+ * so `rgb(255, 0, 0)` would split into three garbage tokens (`rgb(255,`, `0,`, `0)`),
+ * and `var(--brand)` likewise. Named slots — including `surface` — pass through; every
+ * literal collapses to one marker class that the stylesheet keys the painted treatment
+ * off, with the actual colour arriving inline (see `customColorStyle`).
+ */
+export declare function colorClassToken(value: string | undefined | null): string;
+/**
+ * The inline declarations that carry a literal colour, e.g.
+ * `customColorStyle('#7c3aed', 'sidebar')`.
+ *
+ * Written on the component's ROOT element (the one whose stylesheet block declares the
+ * resolvers) — an inline declaration beats the class-based `.mono-<c>.<token>` presets,
+ * whereas the same property set on the host would only *inherit* and would lose to them.
+ *
+ * The rgb triple and the ink are emitted only when the value parses. An unparseable but
+ * renderable value (`var(--brand)`, `color-mix(…)`) still paints: it just keeps the CSS
+ * default ink, and `--mono-<c>-on-accent` stays available to set it by hand.
+ */
+export declare function customColorStyle(value: string | undefined | null, component: string): string;
+/**
+ * Shared validator arm for a `color` prop: a named slot, `surface`, or something that
+ * reads as a CSS colour. Returns an error string, or null when the value is fine.
+ */
+export declare function validateColorProp(value: unknown): string | null;

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

@@ -0,0 +1,27 @@
+/**
+ * Append a per-part class override (if present) to a base class string.
+ *
+ *   cssPart({ inner: 'px-4' }, 'mono-nav-inner', 'inner') // 'mono-nav-inner px-4'
+ *   cssPart(undefined,        'mono-nav-inner', 'inner') // 'mono-nav-inner'
+ */
+export declare function cssPart<T extends object>(cssClass: T | undefined, base: string, key: keyof T): string;
+/**
+ * Apply a `css-class` value to an element's `cssClass`/`cssClassName`.
+ *
+ *  - `null`/`undefined`/empty string → reset both
+ *  - object                          → `cssClass`
+ *  - `'{ … }'` JSON string           → parsed into `cssClass`
+ *  - plain string                    → `cssClassName` (root class fallback)
+ *
+ * Mutates the element's reactive properties directly (so Lit picks up the
+ * change). Used by each component's `_setCssClass`.
+ */
+export declare function applyCssClass<T extends object>(target: {
+    cssClass: T;
+    cssClassName: string;
+}, value: unknown): void;
+/**
+ * Define `css-class` and `cssclass` instance aliases (Vue interop) that route to
+ * `set`. Lets consumers write `<el :css-class="…">` / `:cssclass` / `:cssClass`.
+ */
+export declare function defineCssClassAliases(target: object, set: (value: unknown) => void): void;

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

@@ -0,0 +1,40 @@
+import { StyleInfo } from 'lit/directives/style-map.js';
+/** A sizing prop value: a CSS length string, or a number (interpreted as px). */
+export type CssSizeValue = string | number | undefined;
+/**
+ * Normalize a sizing prop to a CSS length string.
+ * - `number` (or numeric string) → `${n}px`
+ * - any other non-empty string → passed through verbatim (`"12rem"`, `"80%"`, …)
+ * - `null` / `undefined` / `''` → `undefined` (treated as "not set")
+ */
+export declare function toCssSize(value: CssSizeValue): string | undefined;
+/** The six sizing props shared by sizing-driven components. */
+export interface SizeProps {
+    width?: CssSizeValue;
+    height?: CssSizeValue;
+    minWidth?: CssSizeValue;
+    maxWidth?: CssSizeValue;
+    minHeight?: CssSizeValue;
+    maxHeight?: CssSizeValue;
+}
+/**
+ * The popup-PANEL sizing object shared by `mono-select`, `mono-tag-input` and
+ * `mono-dropdown-table`, bound as `:dropdown.prop="{ … }"`.
+ *
+ * The same six keys as {@link SizeProps}, applied to the panel rather than the field:
+ * `height` is an exact height and `maxHeight` the cap, on all three.
+ *
+ * Aliased rather than re-declared per component so the key set cannot drift between them —
+ * each still exports its own name (`SelectDropdownOptions`, `TagInputDropdownOptions`,
+ * `DropdownPanelOptions`) for the consumers who already import one.
+ *
+ * There is deliberately no shared style BUILDER to go with it: the three write these keys onto
+ * different elements with different fallbacks, and a helper parameterised over all of that would
+ * bury the one part that is genuinely subtle — which cap goes to a custom property, and why.
+ */
+export type PanelSizeProps = SizeProps;
+/**
+ * Build a Lit `styleMap` object from the six sizing props, normalizing each via
+ * `toCssSize` and omitting the ones that aren't set.
+ */
+export declare function buildSizeStyle(src: SizeProps): StyleInfo;