@mono-lit/helper 0.0.0-stage → 0.0.2

package/dist/src/components/rich-text-editor/rich-text-editor-core.d.ts

@@ -0,0 +1,100 @@
+import { LitElement, TemplateResult } from 'lit';
+import { RichTextEditorColor, RichTextEditorCssClass, RichTextEditorInstance, RichTextEditorMode, RichTextEditorOptions, RichTextEditorPlugins, RichTextEditorSize, RichTextEditorToolbar, RichTextEditorValidationState, RichTextEditorVariant } from './rich-text-editor-types.js';
+import { Constructor } from '../../composables/hybird-prop';
+import { CssSizeValue } from '../../composables/css-size';
+/** Named slots projected by `mono-rich-text-editor` (light: captured; shadow: native). */
+export type RichTextEditorSlotName = 'label' | 'helper';
+/**
+ * `MonoRichTextEditorCore` — render-mode-agnostic logic for `mono-rich-text-editor`,
+ * a form field whose input is a [SunEditor](https://suneditor.com) v3 instance.
+ *
+ * **The peer is optional.** `suneditor` is externalized from mono's build and
+ * loaded the first time an element renders (`rich-text-editor-loader.ts`). An
+ * app that has not installed it gets an inline message naming the package and
+ * the command, plus an `mno-error` event — never a crash.
+ *
+ * **The editor's DOM lives in LIGHT DOM, in both builds.** SunEditor is styled by
+ * one global stylesheet and parks its modals in a `.sun-editor-carrier-wrapper`
+ * on `<body>`, so neither could ever be adopted into a shadow root. The core
+ * therefore creates ONE mount node (`.mono-rich-text-editor-mount`) and each
+ * build decides where it shows: the light build re-homes it into the rendered
+ * field frame, the shadow build keeps it as a light child projected through
+ * `<slot name="editor">`. Either way it inherits the `--se-*` theme remap the
+ * frame declares, and the page sheet reaches it. SSR renders the chrome only —
+ * an editor is client state, exactly like `mono-chart` and `mono-date`.
+ *
+ * **Lifecycle mirrors `date-core`.** `_ensureEditor()` is idempotent and runs
+ * from `firstUpdated`, `connectedCallback` and every `updated()` that finds no
+ * instance, so a `v-if` / `<KeepAlive>` round trip rebuilds the editor instead
+ * of leaving a dead field. A build token plus an `isConnected` re-check after
+ * every `await` keeps a superseded build from constructing an editor on a
+ * detached node that nothing would ever destroy. `disconnectedCallback`
+ * destroys BEFORE `super` so the DOM is still in the tree.
+ *
+ * **Value model.** `modelValue` is the HTML. SunEditor → element: `onChange`
+ * emits `mno-change`, `onInput` emits `mno-input` (the textarea detail shape),
+ * an empty editor is published as `''` so `required` means what it says.
+ * Element → editor: an outside `modelValue` write reaches `$.html.set()` only
+ * when it differs from the last value the editor itself produced — no caret
+ * jumps, no echo. `monoForm` binds through {@link MonoFormControlCore} exactly
+ * as `mono-textarea` does.
+ */
+export declare const MonoRichTextEditorCore: <T extends Constructor<LitElement>>(superClass: T) => Constructor<MonoRichTextEditorCoreInterface> & T;
+/** Public + shared-protected surface added by the core mixin. */
+export declare class MonoRichTextEditorCoreInterface {
+    size: RichTextEditorSize;
+    color: RichTextEditorColor;
+    variant: RichTextEditorVariant;
+    modelValue: string;
+    value: string;
+    name: string;
+    placeholder: string;
+    label: string;
+    helperText: string;
+    validationState: RichTextEditorValidationState;
+    validationMessage: string;
+    errorMessage: string;
+    successMessage: string;
+    ariaLabelText?: string;
+    disabled: boolean;
+    readonly: boolean;
+    required: boolean;
+    cssClass: RichTextEditorCssClass;
+    cssClassName: string;
+    mode: RichTextEditorMode;
+    toolbar?: RichTextEditorToolbar;
+    plugins?: RichTextEditorPlugins;
+    language?: string | Record<string, unknown>;
+    textDirection?: 'ltr' | 'rtl';
+    charCounter: boolean;
+    maxLength?: number;
+    statusbar: boolean;
+    sticky?: number;
+    loadCss: boolean;
+    options?: RichTextEditorOptions;
+    width?: CssSizeValue;
+    height?: CssSizeValue;
+    minWidth?: CssSizeValue;
+    maxWidth?: CssSizeValue;
+    minHeight?: CssSizeValue;
+    maxHeight?: CssSizeValue;
+    readonly editor: RichTextEditorInstance | null;
+    getHtml(): string;
+    setHtml(html: string): void;
+    insertHtml(html: string): void;
+    getText(): string;
+    isEmpty(): boolean;
+    focus(): void;
+    blur(): void;
+    codeView(value?: boolean): void;
+    fullScreen(value?: boolean): void;
+    protected _hasLabelSlotState: boolean;
+    protected _hasHelperSlotState: boolean;
+    protected _mount?: HTMLDivElement;
+    protected get _slotsAlwaysRender(): boolean;
+    protected get _useNativeSlots(): boolean;
+    protected _setSlotState(name: RichTextEditorSlotName, has: boolean): void;
+    protected _slotOutlet(name: RichTextEditorSlotName, fallback?: unknown): TemplateResult;
+    protected _renderEditorOutlet(fieldClass: string): TemplateResult;
+    protected _placeMount(): void;
+}

package/dist/src/components/rich-text-editor/rich-text-editor-loader.d.ts

@@ -0,0 +1,17 @@
+/** The `suneditor` default export (`{ create, init }`), cached; a failure resets so a later attempt retries. */
+export declare function loadSunEditor(): Promise<any>;
+/**
+ * SunEditor's UI stylesheet (`suneditor/css/editor`), injected ONCE per page by
+ * the consumer's bundler as a side-effect import. Failure is not fatal — the
+ * editor still works, unstyled — so it is reported once and swallowed.
+ */
+export declare function loadSunEditorCss(): Promise<void>;
+/** Every built-in plugin, keyed by name (`suneditor/plugins`' default export). */
+export declare function loadSunEditorPlugins(): Promise<Record<string, any>>;
+/** Codes `lang` accepts. */
+export declare const SUNEDITOR_LANG_CODES: string[];
+/**
+ * A language pack by code (`ko`, `pt-BR` → `pt_br`, `zh-CN` → `zh_cn`, …), or
+ * `undefined` for English / an unknown code (SunEditor then uses its default).
+ */
+export declare function loadSunEditorLang(code: string): Promise<any | undefined>;

package/dist/src/components/rich-text-editor/rich-text-editor-toolbar.d.ts

@@ -0,0 +1,65 @@
+import { RichTextEditorButtonList, RichTextEditorPlugins, RichTextEditorToolbar, RichTextEditorToolbarPreset } from './rich-text-editor-types.js';
+/**
+ * Buttons SunEditor's core provides WITHOUT a plugin (v3 `_defaultButtons`).
+ * Anything else in a `buttonList` is the `key` of a plugin that has to be in
+ * `plugins`, so a preset is filtered against the plugins actually loaded.
+ */
+export declare const SUNEDITOR_CORE_BUTTONS: ReadonlySet<string>;
+/**
+ * Built-ins `plugins="auto"` leaves OUT: each needs configuration SunEditor
+ * warns about when it is missing (a server `url` / `uploadUrl`, a `templates` or
+ * `layouts` list, an external KaTeX / MathJax / PDF service). Ask for them by
+ * name — `plugins="auto, image­Gallery"` is not a thing, but
+ * `:plugins.prop="[...]"` with the class or `plugins="font, link, template"`
+ * is — and supply their options through `options`.
+ */
+export declare const AUTO_EXCLUDED_PLUGINS: ReadonlySet<string>;
+/**
+ * SunEditor's own default (`DEFAULTS.BUTTON_LIST`) — no plugin buttons at all.
+ * Mirrored here rather than imported so the presets stay pure.
+ */
+export declare const TOOLBAR_DEFAULT: RichTextEditorButtonList;
+/** The essentials: a comment box, a note field. */
+export declare const TOOLBAR_BASIC: RichTextEditorButtonList;
+/** The default: what a document / description / email body needs. */
+export declare const TOOLBAR_STANDARD: RichTextEditorButtonList;
+/**
+ * Every built-in that works with no extra configuration. Left out on purpose:
+ * the galleries / file browser (need a server `url`), `template` (needs a
+ * `templates` list), `math` and `exportPDF` (need external libraries) — pass
+ * those through `toolbar` + `options` when the app provides what they need.
+ */
+export declare const TOOLBAR_FULL: RichTextEditorButtonList;
+export declare const TOOLBAR_PRESETS: Record<RichTextEditorToolbarPreset, RichTextEditorButtonList>;
+export declare function isToolbarPreset(value: unknown): value is RichTextEditorToolbarPreset;
+/**
+ * The `buttonList` for a `toolbar` prop value: a preset name, an array, its
+ * JSON, or a string of names — `bold, italic | link` (`|` and `/` are honoured
+ * as separators, `,`/whitespace split the rest). Unknown → the `standard` preset.
+ */
+export declare function resolveToolbar(toolbar: RichTextEditorToolbar | undefined | null): RichTextEditorButtonList;
+/**
+ * Drop the plugin buttons a `buttonList` names that are NOT among `available`
+ * plugin keys, so `plugins="none"` (or a trimmed list) with the default toolbar
+ * degrades to the core buttons instead of SunEditor rejecting the list.
+ * Separators left with nothing on either side are dropped too.
+ */
+export declare function pruneToolbar(list: RichTextEditorButtonList, available: ReadonlySet<string>): RichTextEditorButtonList;
+/**
+ * The plugin set to hand SunEditor, from the `plugins` prop and (when needed)
+ * the full built-in map. Returns `{ plugins, keys }` — `keys` is what
+ * `pruneToolbar` filters against.
+ *
+ * - `'auto'` / unset → every built-in that needs no configuration (`all` must
+ *   be supplied; see {@link AUTO_EXCLUDED_PLUGINS}).
+ * - `'none'` → nothing.
+ * - an array → plugin classes kept as they are, NAMES looked up in `all`.
+ * - an object → SunEditor's own `{ name: class }` form.
+ * - a string → comma/space-separated names.
+ */
+export declare function resolvePlugins(plugins: RichTextEditorPlugins | undefined | null, all: Record<string, unknown> | null): {
+    plugins: unknown[];
+    keys: Set<string>;
+};
+/** Whether `plugins` needs the full built-in map to be resolved. */
+export declare function pluginsNeedCatalog(plugins: RichTextEditorPlugins | undefined | null): boolean;

package/dist/src/components/rich-text-editor/rich-text-editor-types.d.ts

@@ -0,0 +1,231 @@
+import { VisibilityProps } from '../../composables/visibility';
+import { CssSizeValue } from '../../composables/css-size';
+export type RichTextEditorSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+export type RichTextEditorColor = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'teal' | 'purple' | 'neutral' | 'dark';
+export type RichTextEditorVariant = 'outlined' | 'filled' | 'underlined';
+export type RichTextEditorValidationState = 'default' | 'valid' | 'invalid' | 'warning';
+/** SunEditor's toolbar placement modes (`options.mode`). */
+export type RichTextEditorMode = 'classic' | 'inline' | 'balloon' | 'balloon-always' | 'classic:bottom' | 'inline:bottom';
+/**
+ * A toolbar preset — `basic` (formatting essentials), `standard` (the default:
+ * fonts, colours, tables, media, code view), `full` (every built-in button) or
+ * `default` (SunEditor's own list, no plugin buttons).
+ */
+export type RichTextEditorToolbarPreset = 'basic' | 'standard' | 'full' | 'default';
+/**
+ * SunEditor's `buttonList`: groups of button names, `'|'` separators, `'/'` line
+ * breaks and `-left` / `-right` / `-center` alignment markers.
+ */
+export type RichTextEditorButtonList = Array<string | string[]>;
+/** What the `toolbar` prop accepts: a preset name, a `buttonList`, or its JSON. */
+export type RichTextEditorToolbar = RichTextEditorToolbarPreset | RichTextEditorButtonList | string;
+/**
+ * What the `plugins` prop accepts: `'auto'` (every built-in, the default), an
+ * array of plugin classes (`import { font, image } from 'suneditor/plugins'`),
+ * an array of built-in plugin NAMES picked from the full set, or a `name → class`
+ * object the way SunEditor itself takes them.
+ */
+export type RichTextEditorPlugins = 'auto' | 'none' | Array<string | RichTextEditorPluginClass> | Record<string, RichTextEditorPluginClass> | string;
+/** A SunEditor plugin class — opaque to mono. */
+export type RichTextEditorPluginClass = any;
+/**
+ * The parts of a SunEditor v3 instance mono relies on, typed structurally so a
+ * consumer without the peer installed still gets a usable `editor` type. The
+ * real instance carries far more — see SunEditor's own `types/`.
+ */
+export interface RichTextEditorInstance {
+    $: {
+        html: {
+            get(options?: {
+                withFrame?: boolean;
+                includeFullPage?: boolean;
+            }): string;
+            set(html: string): void;
+            add(html: string): void;
+            insert(html: string, options?: Record<string, unknown>): void;
+        };
+        ui: {
+            readOnly(value: boolean): void;
+            disable(): void;
+            enable(): void;
+            setDir(dir: 'ltr' | 'rtl'): void;
+        };
+        focusManager: {
+            focus(): void;
+            blur(): void;
+        };
+        viewer: {
+            codeView(value?: boolean): void;
+            fullScreen(value?: boolean): void;
+        };
+        frameContext: {
+            get(key: string): unknown;
+        };
+        [key: string]: unknown;
+    };
+    isEmpty(): boolean;
+    resetOptions(options: Record<string, unknown>): void;
+    destroy(): void;
+    events: Record<string, unknown> | null;
+    [key: string]: unknown;
+}
+/** SunEditor's `InitOptions` — passed through untouched, so it is left open. */
+export type RichTextEditorOptions = Record<string, unknown>;
+export interface RichTextEditorCssClass {
+    root?: string;
+    label?: string;
+    required?: string;
+    field?: string;
+    footer?: string;
+    messageWrap?: string;
+    message?: string;
+    counter?: string;
+}
+export type RichTextEditorModelEventDetail = {
+    /** The editor's HTML, `''` when it holds no content. */
+    modelValue: string;
+    currentValue: string;
+    oldValue: string;
+    value: string;
+    name?: string;
+    /** SunEditor's own event payload (`{ $, frameContext, data, … }`). */
+    sourceEvent?: unknown;
+};
+export type RichTextEditorModelEvent = CustomEvent<RichTextEditorModelEventDetail>;
+export type RichTextEditorReadyEventDetail = {
+    /** The live SunEditor instance — `el.editor` from here on. */
+    editor: RichTextEditorInstance;
+};
+export type RichTextEditorErrorEventDetail = {
+    /** Why the editor could not be built — typically the missing peer. */
+    message: string;
+    error: unknown;
+};
+export type RichTextEditorFocusEventDetail = {
+    name?: string;
+    sourceEvent?: unknown;
+};
+export interface RichTextEditorProps extends VisibilityProps {
+    /** Two-way bound HTML. `''` for an empty editor. */
+    modelValue?: string;
+    'model-value'?: string;
+    modelvalue?: string;
+    /** HTML (kept in sync with modelValue). */
+    value?: string;
+    /** Form field name, carried on the events. */
+    name?: string;
+    /** Placeholder shown while the editor is empty. */
+    placeholder?: string;
+    /** Text label shown above the editor. */
+    label?: string;
+    /** Helper text shown below the editor. */
+    helperText?: string;
+    'helper-text'?: string;
+    helpertext?: string;
+    /** Validation state controlling the frame styling. */
+    validationState?: RichTextEditorValidationState;
+    'validation-state'?: RichTextEditorValidationState;
+    validationstate?: RichTextEditorValidationState;
+    /** Message shown for the current validation state. */
+    validationMessage?: string;
+    'validation-message'?: string;
+    validationmessage?: string;
+    /** Error message that forces the invalid state. */
+    errorMessage?: string;
+    'error-message'?: string;
+    errormessage?: string;
+    /** Success message that forces the valid state. */
+    successMessage?: string;
+    'success-message'?: string;
+    successmessage?: string;
+    /** Disables editing and the toolbar. */
+    disabled?: boolean | string;
+    /** Read-only: content shows, cannot be edited. */
+    readonly?: boolean | string;
+    /** Marks the label and lets `monoForm`'s `required` rule apply. */
+    required?: boolean | string;
+    /** Field size — scales the toolbar, icons and editing font. */
+    size?: RichTextEditorSize;
+    /** Accent colour for focus and active toolbar state. */
+    color?: RichTextEditorColor;
+    /** Frame variant. */
+    variant?: RichTextEditorVariant;
+    /** Toolbar placement: `classic` (default), `inline`, `balloon`, `balloon-always`, `classic:bottom`, `inline:bottom`. */
+    mode?: RichTextEditorMode;
+    /** Toolbar preset (`basic` | `standard` | `full` | `default`) or a SunEditor `buttonList` (bind with `.prop`, or JSON). */
+    toolbar?: RichTextEditorToolbar;
+    /** Plugins: `auto` (all built-ins, default), `none`, an array of plugin classes / names, or a name → class object. */
+    plugins?: RichTextEditorPlugins;
+    /** Language: a SunEditor language code (`ko`, `de`, `zh-CN`, …) loaded on demand, or a language object (`.prop`). */
+    language?: string | Record<string, unknown>;
+    /** Text direction of the CONTENT (the host's own `dir` is left to the page). */
+    textDirection?: 'ltr' | 'rtl';
+    'text-direction'?: 'ltr' | 'rtl';
+    textdirection?: 'ltr' | 'rtl';
+    /** Show SunEditor's character counter in the status bar. */
+    charCounter?: boolean | string;
+    'char-counter'?: boolean | string;
+    charcounter?: boolean | string;
+    /** Maximum number of characters (`charCounter_max`). */
+    maxLength?: number | string;
+    'max-length'?: number | string;
+    maxlength?: number | string;
+    /** Show the status bar (resize handle, path). Default `true`. */
+    statusbar?: boolean | string;
+    /** Sticky toolbar offset in px while the page scrolls (`toolbar_sticky`); unset = not sticky. */
+    sticky?: number | string;
+    /**
+     * Whether the element loads SunEditor's own stylesheet (`suneditor/css/editor`)
+     * the first time it renders. Default `true`. Set `false` when the app ships it.
+     */
+    loadCss?: boolean | string;
+    'load-css'?: boolean | string;
+    loadcss?: boolean | string;
+    /** Raw SunEditor `InitOptions`, merged LAST over everything the props produce. Bind with `.prop`. */
+    options?: RichTextEditorOptions;
+    /** Class hooks per part. */
+    cssClass?: RichTextEditorCssClass | string;
+    'css-class'?: RichTextEditorCssClass | string;
+    cssclass?: RichTextEditorCssClass | string;
+    /** Explicit sizing of the whole field. */
+    width?: CssSizeValue;
+    /** Editing area height (SunEditor `height`, default `auto`). */
+    height?: CssSizeValue;
+    minWidth?: CssSizeValue;
+    'min-width'?: CssSizeValue;
+    minwidth?: CssSizeValue;
+    maxWidth?: CssSizeValue;
+    'max-width'?: CssSizeValue;
+    maxwidth?: CssSizeValue;
+    /** Editing area minimum height (SunEditor `minHeight`, default `10rem`). */
+    minHeight?: CssSizeValue;
+    'min-height'?: CssSizeValue;
+    minheight?: CssSizeValue;
+    maxHeight?: CssSizeValue;
+    'max-height'?: CssSizeValue;
+    maxheight?: CssSizeValue;
+    /** `aria-label` for the editing area (defaults to `label` / `placeholder`). */
+    ariaLabel?: string;
+    'aria-label'?: string;
+    arialabel?: string;
+}
+export interface RichTextEditorEvents {
+    input: RichTextEditorModelEvent;
+    change: RichTextEditorModelEvent;
+    focus: CustomEvent<RichTextEditorFocusEventDetail>;
+    blur: CustomEvent<RichTextEditorFocusEventDetail>;
+    ready: CustomEvent<RichTextEditorReadyEventDetail>;
+    error: CustomEvent<RichTextEditorErrorEventDetail>;
+    'mno-input': RichTextEditorModelEvent;
+    mnoInput: RichTextEditorModelEvent;
+    'mno-change': RichTextEditorModelEvent;
+    mnoChange: RichTextEditorModelEvent;
+    'mno-focus': CustomEvent<RichTextEditorFocusEventDetail>;
+    mnoFocus: CustomEvent<RichTextEditorFocusEventDetail>;
+    'mno-blur': CustomEvent<RichTextEditorFocusEventDetail>;
+    mnoBlur: CustomEvent<RichTextEditorFocusEventDetail>;
+    'mno-ready': CustomEvent<RichTextEditorReadyEventDetail>;
+    mnoReady: CustomEvent<RichTextEditorReadyEventDetail>;
+    'mno-error': CustomEvent<RichTextEditorErrorEventDetail>;
+    mnoError: CustomEvent<RichTextEditorErrorEventDetail>;
+}

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

@@ -0,0 +1,4 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoSelect } from './mono-select.js';
+export type { SelectSize, SelectColor, SelectVariant, SelectValidationState, SelectValue, SelectItem, SelectDisplayValue, SelectDisplayGroup, SelectDataSource, SelectDataSourceLoadMore, SelectCssClass, SelectDropdownOptions, SelectModelEventDetail, SelectModelEvent, SelectProps, SelectEvents, } from './select-types.js';
+export { validateSelectProps, } from './select-utils.js';

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

@@ -0,0 +1,5 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoSelectShadow } from './mono-select.shadow.js';
+export { MonoSelectCore, type SelectSlotName } from './select-core.js';
+export type { SelectSize, SelectColor, SelectVariant, SelectValidationState, SelectValue, SelectItem, SelectDisplayValue, SelectDisplayGroup, SelectDataSource, SelectDataSourceLoadMore, SelectCssClass, SelectModelEventDetail, SelectModelEvent, SelectProps, SelectEvents, } from './select-types.js';
+export { validateSelectProps } from './select-utils.js';

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

@@ -0,0 +1,69 @@
+import { LitElement, TemplateResult } from 'lit';
+declare const MonoSelect_base: import('../../composables/hybird-prop').Constructor<import('./select-core.js').MonoSelectCoreInterface> & typeof LitElement;
+/**
+ * Light-DOM `mono-select` (default build, `@mono-lit/helper/ui/select`).
+ *
+ * `createRenderRoot()` returns `this`, so the component renders into light DOM
+ * and inherits the page's global stylesheet (UnoCSS icons, theme variables).
+ * Named slots (label/helper/prefix/suffix) are captured from the light-DOM
+ * children in `connectedCallback` and re-parented into the rendered
+ * `data-mono-slot` placeholders in `updated()`. All behavior is shared with the
+ * shadow build (`@mono-lit/helper/ui/shadow/select`) via `MonoSelectCore`; both
+ * register `mono-select`, so a document loads only one build.
+ */
+export declare class MonoSelect extends MonoSelect_base {
+    static styles: import('lit').CSSResult[];
+    protected createRenderRoot(): HTMLElement;
+    private _slotsCaptured;
+    private _slotLabel;
+    private _slotHelper;
+    private _slotPrefix;
+    private _slotSuffix;
+    /**
+     * The consumer's `slot="list"` wrapper — ONE element holding their own `v-for`.
+     *
+     * Held as a single node and never opened: mono places the wrapper and leaves its children alone.
+     * Relocating them would break the consumer's next insert, since Vue positions a new row with
+     * `insertBefore(node, anchor)` against the sibling that mono had moved away.
+     */
+    private _slotList;
+    connectedCallback(): void;
+    protected updated(changed: Map<string, unknown>): void;
+    /**
+     * The captured wrapper, which is the truth for this build at every moment: parked out of the
+     * host before the panel exists, and inside the panel after. The core's default (a light child of
+     * the host) is the SHADOW build's answer and would find nothing here.
+     */
+    protected get _listSlotWrapper(): HTMLElement | null;
+    /** Light-DOM target for the list wrapper; the shadow build projects instead. */
+    protected renderListSlot(): TemplateResult;
+    /**
+     * Move the wrapper into the panel, once it exists.
+     *
+     * The panel is relocated into a body portal while open, so the target is queried through the
+     * core's portal-aware root rather than the host. Idempotent: once the wrapper is inside the
+     * target it is left alone, which matters because re-appending it on every render would blow away
+     * the consumer's scroll position and focus.
+     */
+    private _placeListSlot;
+    /**
+     * Adopt a wrapper that appeared after `connectedCallback` — see `LateSlotWatcher`.
+     *
+     * Two things have to happen and the order matters. It is PARKED first, out of the host, because
+     * until it is placed it would otherwise paint in the host's own flow, under the field rather
+     * than inside the panel — that is the bug this exists for. Only then is the flag flipped, which
+     * schedules the render that creates the target `_placeListSlot` needs.
+     *
+     * Parking detached is safe for the subtree inside it: the consumer's `v-for` inserts against
+     * anchors that are its OWN children, and those move with it.
+     */
+    protected _onLateListSlot(): void;
+    private _captureSlots;
+    private _placeSlot;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'mono-select': MonoSelect;
+    }
+}
+export {};

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

@@ -0,0 +1,48 @@
+import { LitElement, TemplateResult } from 'lit';
+import { SelectSlotName } from './select-core.js';
+declare const MonoSelectShadow_base: import('../../composables/hybird-prop').Constructor<import('./select-core.js').MonoSelectCoreInterface> & typeof LitElement;
+/**
+ * Shadow-DOM `mono-select` (the opt-in SSR build, `@mono-lit/helper/ui/shadow/select`).
+ *
+ * Real shadow root + `static styles`, so `@lit-labs/ssr` serializes it to
+ * Declarative Shadow DOM and styles are scoped (`mono-select`→`:host`). The
+ * collapsed control (label + trigger + placeholder + message) server-renders;
+ * the dropdown panel is closed server-side and the DataSource (async) is
+ * client-only — options populate after hydration. The panel stays in the shadow
+ * root (the shared `PopupPortalController` skips the body portal for a shadow
+ * host and CSS positions it under the `position:relative` `.mono-select`).
+ *
+ * Slotting uses native `<slot>`: `label`/`helper` carry the prop text as native
+ * fallback (shown server-side); presence is detected in `firstUpdated()` via
+ * `assignedNodes()` (DSD assigns at parse time → no `slotchange` after upgrade)
+ * plus `@slotchange` for later changes. Interactivity needs the first client
+ * update to flush — hence the defer-hydration poll. Shares all logic with the
+ * light build via `MonoSelectCore`; both register `mono-select`, so a document
+ * loads only one build.
+ */
+export declare class MonoSelectShadow extends MonoSelectShadow_base {
+    static styles: import('lit').CSSResult[];
+    protected get _slotsAlwaysRender(): boolean;
+    connectedCallback(): void;
+    firstUpdated(changed: Map<string, unknown>): void;
+    protected updated(changed: Map<string, unknown>): void;
+    /** A wrapper appeared after connect — the flag is all this build needs, projection does the rest. */
+    protected _onLateListSlot(): void;
+    private _scanSlots;
+    private _slotHasContent;
+    private _onSlotChange;
+    /**
+     * The consumer's list wrapper, PROJECTED rather than moved.
+     *
+     * Projection is what makes this work in a shadow root at all: slotted content stays in the light
+     * DOM, so the app's own stylesheet still reaches it. Moving those nodes inside the shadow root
+     * would cut them off from it — the same reason this build inlines SVGs instead of icon classes.
+     */
+    protected renderListSlot(): TemplateResult;
+    /** Native `<slot>` carrying the prop fallback as native slot content. */
+    protected _slotOutlet(name: SelectSlotName, fallback?: unknown): TemplateResult;
+    /** Inline SVG — the global `.mono-icon`/`i-mdi-*` UnoCSS icons can't reach a
+     *  shadow root. */
+    protected renderIcon(name: 'close' | 'chevron'): TemplateResult;
+}
+export {};

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

@@ -0,0 +1,98 @@
+import { LitElement, TemplateResult } from 'lit';
+import { SelectSize, SelectColor, SelectVariant, SelectValidationState, SelectValue, SelectItem, SelectDataSource, SelectLoadMore, SelectDisplayValue, SelectDisplayGroup, SelectCssClass, SelectDropdownOptions } from './select-types.js';
+import { Constructor } from '../../composables/hybird-prop';
+import { CssSizeValue } from '../../composables/css-size';
+import { LateSlotWatcher } from '../../composables/light-slots';
+import { MonoSearchValue } from '../../search/data-search.js';
+/** Named slots projected by `mono-select` (light: captured; shadow: native). */
+export type SelectSlotName = 'label' | 'helper' | 'prefix' | 'suffix' | 'list';
+/**
+ * `MonoSelectCore` — render-mode-agnostic logic for `mono-select` (props, hybrid
+ * aliases, value/model sync, DataSource paging, search, grouping, keyboard nav,
+ * the popup controller, and the full `render()`). SSR-safe: every `document` /
+ * `window` / focus access is `isServer`-guarded.
+ *
+ * Each build supplies `createRenderRoot()` + `static styles`, the slot strategy
+ * (light captures children into `data-mono-slot` placeholders; shadow uses native
+ * `<slot>` + a `firstUpdated` scan), and the `_slotOutlet` / `renderIcon` hooks.
+ * The shared `_has*SlotState` `@state` fields back both strategies.
+ */
+export declare const MonoSelectCore: <T extends Constructor<LitElement>>(superClass: T) => Constructor<MonoSelectCoreInterface> & T;
+/** Public + shared-protected surface added by the core mixin (types the wrappers
+ *  + the `HTMLElementTagNameMap` augmentation in the light build). */
+export declare class MonoSelectCoreInterface {
+    size: SelectSize;
+    color: SelectColor;
+    variant: SelectVariant;
+    modelValue: SelectValue;
+    value: SelectValue;
+    name: string;
+    label: string;
+    placeholder: string;
+    helperText: string;
+    validationState: SelectValidationState;
+    validationMessage: string;
+    errorMessage: string;
+    successMessage: string;
+    ariaLabelText?: string;
+    disabled: boolean;
+    readonly: boolean;
+    required: boolean;
+    clearable: boolean;
+    items: SelectItem[];
+    dataSource: SelectDataSource | null;
+    immediate: boolean;
+    loadMore?: SelectLoadMore | '' | boolean;
+    pageSize: number;
+    dropdown?: SelectDropdownOptions;
+    dropdownHeight: string | number;
+    dropdownMaxHeight: string | number;
+    flip: boolean;
+    shift: boolean;
+    keyValue: string;
+    displayValue: SelectDisplayValue;
+    displayGroup: SelectDisplayGroup;
+    groupKey: string;
+    groupItems: string;
+    group: boolean;
+    groupSticky: boolean;
+    searchable: boolean;
+    stayOpen: boolean;
+    searchValue: MonoSearchValue;
+    searchOperation: string;
+    searchDebounce: number;
+    searchPlaceholder: string;
+    cssClass: SelectCssClass;
+    cssClassName: string;
+    width?: CssSizeValue;
+    height?: CssSizeValue;
+    minWidth?: CssSizeValue;
+    maxWidth?: CssSizeValue;
+    minHeight?: CssSizeValue;
+    maxHeight?: CssSizeValue;
+    focus(): void;
+    blur(): void;
+    readonly isOpen: boolean;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    protected _hasLabelSlotState: boolean;
+    protected _hasHelperSlotState: boolean;
+    protected _hasPrefixSlotState: boolean;
+    protected _hasSuffixSlotState: boolean;
+    protected _hasListSlotState: boolean;
+    protected _lateListSlot: LateSlotWatcher;
+    protected _onLateListSlot(): void;
+    protected get _listSlotWrapper(): HTMLElement | null;
+    protected _watchListChrome(): void;
+    protected _stopWatchingListChrome(): void;
+    protected _syncListChrome(): void;
+    protected renderListSlot(): TemplateResult;
+    protected _onListSlotClick: (event: Event) => void;
+    protected readonly _listSlotTarget: HTMLElement | null;
+    protected get _slotsAlwaysRender(): boolean;
+    protected _toBoolean(value: unknown): boolean;
+    protected _setSlotState(name: SelectSlotName, has: boolean): void;
+    protected _slotOutlet(name: SelectSlotName, fallback?: unknown): TemplateResult;
+    protected renderIcon(name: 'close' | 'chevron'): TemplateResult;
+}