@cdevhub/ngx-tw 0.4.0 → 0.6.0

package/types/cdevhub-ngx-tw-date-range-picker-testing.d.ts

@@ -0,0 +1,148 @@
+import { ComponentHarness, BaseHarnessFilters, HarnessPredicate } from '@angular/cdk/testing';
+import { CalendarHarness } from '@cdevhub/ngx-tw/calendar/testing';
+
+/** Filters accepted by `DateRangePickerHarness.with`. */
+interface DateRangePickerHarnessFilters extends BaseHarnessFilters {
+    /** Match by the trigger's accessible name. */
+    label?: string | RegExp;
+    /** Match by the whole text currently rendered in the trigger. */
+    triggerText?: string | RegExp;
+    /** Match disabled / enabled pickers. */
+    disabled?: boolean;
+}
+/**
+ * Harness for `tw-date-range-picker`.
+ *
+ * Unlike `tw-date-picker`, this component has **no text input**: its trigger is
+ * a `button[role="combobox"]` that renders the start label, a separator and the
+ * end label as three sibling spans (or a single placeholder span when empty).
+ * A range is therefore read, never typed — {@link getStartText} /
+ * {@link getEndText} read it, and {@link selectRange} sets it through the
+ * calendar.
+ *
+ * The calendar renders into the CDK overlay, outside the
+ * `tw-date-range-picker` host, so it is resolved through
+ * `documentRootLocatorFactory()`. A consumer loads this harness from the
+ * ordinary fixture loader — no `documentRootLoader` ceremony required.
+ *
+ * Day-grid navigation is not reimplemented here: {@link getCalendar} returns
+ * the `CalendarHarness` from `@cdevhub/ngx-tw/calendar/testing`, which already
+ * owns cells, view switching and header paging.
+ */
+declare class DateRangePickerHarness extends ComponentHarness {
+    static hostSelector: string;
+    private readonly trigger;
+    /**
+     * The start / separator / end spans, or a single placeholder span when the
+     * range is empty. They carry no distinguishing attribute, so position inside
+     * the trigger is the only handle — see {@link getStartText}.
+     */
+    private readonly triggerSpans;
+    /**
+     * The inline clear control — the only button in the host that is not the
+     * trigger.
+     */
+    private readonly clearButton;
+    /** Resolves the overlay's calendar, which lives outside this harness's host. */
+    private readonly calendar;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: DateRangePickerHarnessFilters): HarnessPredicate<DateRangePickerHarness>;
+    /**
+     * The trigger's accessible name.
+     *
+     * Note this is *composed*, not the bare `aria-label`: once a complete range
+     * is set the component appends the range to it
+     * (`"Report period. Current range: Apr 10 to Apr 15."`). Match with a RegExp
+     * in {@link with} if you need it to survive a selection.
+     */
+    getLabel(): Promise<string | null>;
+    /**
+     * The whole text rendered in the trigger, trimmed — start, separator and end
+     * run together, or the placeholder when no range is set.
+     */
+    getTriggerText(): Promise<string>;
+    /**
+     * The formatted start date, or `null` when no range is set (the trigger then
+     * renders a single placeholder span instead of the start/separator/end
+     * triple).
+     */
+    getStartText(): Promise<string | null>;
+    /** The formatted end date, or `null` when no range is set. */
+    getEndText(): Promise<string | null>;
+    /** Whether the calendar overlay is open, read from the trigger's `aria-expanded`. */
+    isOpen(): Promise<boolean>;
+    /** Whether the trigger reports `aria-disabled="true"`. */
+    isDisabled(): Promise<boolean>;
+    /** Whether the trigger reports `aria-invalid="true"`. */
+    isInvalid(): Promise<boolean>;
+    /**
+     * Whether the trigger reports `aria-required="true"`. Reflects the `required`
+     * input *and* a `Validators.required` on a bound control.
+     */
+    isRequired(): Promise<boolean>;
+    /**
+     * Opens the calendar overlay by clicking the trigger. No-op when already
+     * open; a disabled picker ignores it, as it does in the browser.
+     */
+    open(): Promise<void>;
+    /**
+     * Closes the calendar overlay by clicking the trigger again. No-op when
+     * already closed.
+     *
+     * Deliberately not Escape: `tw-date-range-picker` treats Escape as *cancel*
+     * and restores the range the overlay opened with, which would make `close()`
+     * silently undo a selection. The trigger toggles without that side effect.
+     *
+     * The overlay runs a leave animation before it detaches, so `isOpen()` flips
+     * to `false` immediately while the panel element lingers for a few more
+     * frames. Two consequences worth knowing:
+     *
+     * - Do not assert `getCalendar()` is `null` on the tick after a close; the
+     *   old panel is still mounted.
+     * - An `open()` inside that window does **not** attach a fresh panel — the
+     *   component sees an overlay ref it has not disposed yet and silently
+     *   keeps the outgoing one. Let the animation finish before reopening.
+     */
+    close(): Promise<void>;
+    /**
+     * The `CalendarHarness` for the open overlay, or `null` when no overlay is
+     * attached. One `tw-calendar` renders all `numberOfMonths` months under a
+     * single header, so this is a single harness whatever that input is set to.
+     */
+    getCalendar(): Promise<CalendarHarness | null>;
+    /**
+     * Opens the overlay if needed and clicks the two cells whose text matches
+     * `start` then `end` exactly (`'10'`, not `'April 10'`). Throws when either
+     * cell is not visible in the current view.
+     *
+     * With more than one month rendered a day number appears once per month grid;
+     * the first match wins, which is the earliest visible month. Page the
+     * calendar via {@link getCalendar} first if you need a later one.
+     *
+     * With `showActions` off this commits and closes on the second click; with it
+     * on the range stays pending until {@link clickAction} confirms it.
+     */
+    selectRange(start: string, end: string): Promise<void>;
+    /**
+     * Clicks a button in the overlay's action bar (`Today`, `Clear`, `Cancel`,
+     * `Apply`) by its visible text. Matching on text rather than position is what
+     * keeps this usable when a consumer relabels the actions via `todayLabel` and
+     * friends — pass whatever label you configured.
+     *
+     * Preset entries are excluded: they are `role="option"`, not action buttons.
+     * Throws when the overlay is closed or nothing matches.
+     */
+    clickAction(label: string | RegExp): Promise<void>;
+    /**
+     * Whether the inline clear control is rendered. It appears only while
+     * `showClear` is on, the picker is enabled, and a range is set.
+     */
+    hasClearButton(): Promise<boolean>;
+    /** Clicks the inline clear control. Throws when none is rendered. */
+    clear(): Promise<void>;
+    /** @internal Text of one of the start/separator/end spans, or `null` when the trigger is empty. */
+    private rangeSpanText;
+}
+
+export { DateRangePickerHarness };
+export type { DateRangePickerHarnessFilters };

package/types/cdevhub-ngx-tw-date-range-picker.d.ts

@@ -55,21 +55,21 @@ declare class DateRangePickerComponent<D = Date> extends FormFieldControl<TwDate
     readonly minDate: _angular_core.InputSignal<D | null>;
     /** Latest selectable date for either endpoint. Presets and calendar cells later than this are rejected or disabled. Defaults to `null`. */
     readonly maxDate: _angular_core.InputSignal<D | null>;
-    /** Per-date predicate — return `false` to disable. Applied in both calendars. Presets that fall on a filtered date are skipped. */
+    /** Per-date predicate — return `false` to disable. Applied in both calendars. Presets that fall on a filtered date are skipped. Defaults to `null`. */
     readonly dateFilter: _angular_core.InputSignal<DateFilterFn<D> | null>;
     /** Which calendar view opens first — `'day'`, `'month'`, or `'year'`. Defaults to `'day'`. */
     readonly startView: _angular_core.InputSignal<CalendarViewState>;
-    /** Date the left calendar focuses on when opened with no value. Falls back to today. Ignored when a value is already set. */
+    /** Date the left calendar focuses on when opened with no value. Falls back to today. Ignored when a value is already set. Defaults to `null`. */
     readonly startAt: _angular_core.InputSignal<D | null>;
     /** Display format for each endpoint, passed to `DateAdapter.format()`. When `showTime` is true and this is left at the default, hour/minute (and optional seconds) are folded in automatically. */
     readonly format: _angular_core.InputSignal<unknown>;
     /** Separator rendered between the two formatted endpoints in the trigger. Defaults to `" – "`. */
     readonly rangeSeparator: _angular_core.InputSignal<string>;
-    /** Placeholder text shown in the trigger for an empty `start` endpoint. */
+    /** Placeholder text shown in the trigger for an empty `start` endpoint. Defaults to `'Start date'`. */
     readonly emptyStartLabel: _angular_core.InputSignal<string>;
-    /** Placeholder text shown in the trigger for an empty `end` endpoint. */
+    /** Placeholder text shown in the trigger for an empty `end` endpoint. Defaults to `'End date'`. */
     readonly emptyEndLabel: _angular_core.InputSignal<string>;
-    /** When set, overrides the composed `${emptyStartLabel}${rangeSeparator}${emptyEndLabel}` placeholder with a single string. */
+    /** When set, overrides the composed `${emptyStartLabel}${rangeSeparator}${emptyEndLabel}` placeholder with a single string. Defaults to `undefined`. */
     readonly placeholder: _angular_core.InputSignal<string | undefined>;
     /** When true, the trigger cannot open the overlay and `aria-disabled="true"` is set. Defaults to `false`. */
     readonly disabledInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
@@ -83,9 +83,9 @@ declare class DateRangePickerComponent<D = Date> extends FormFieldControl<TwDate
     readonly variant: _angular_core.InputSignal<DateRangePickerVariant | undefined>;
     /** How many months the overlay shows side-by-side. `2` is the standard range-picker layout; use `1` for compact contexts. Defaults to `2`. */
     readonly numberOfMonths: _angular_core.InputSignal<DateRangePickerMonths>;
-    /** Optional quick-select presets rendered as a vertical list before the calendars. Each preset provides a label and a factory returning a `TwDateRange<D>`. An empty array hides the preset panel. */
+    /** Optional quick-select presets rendered as a vertical list before the calendars. Each preset provides a label and a factory returning a `TwDateRange<D>`. An empty array hides the preset panel. Defaults to an empty array. */
     readonly presets: _angular_core.InputSignal<readonly DateRangePreset<D>[]>;
-    /** Whether to show a clear-button affordance inside the trigger when a value is set. Defaults to `true`. */
+    /** Whether to show a clear-button affordance inside the trigger when a value is set. Defaults to `true` — most form pickers expect the inline clear, matching `<tw-input>`'s clear button; without it consumers must wire one themselves. */
     readonly showClear: _angular_core.InputSignal<boolean>;
     /** Minimum range length in days, inclusive. Commits shorter than this are rejected and surface `calendarRangeTooShort` on the bound `NgControl`. `null` = no minimum. Defaults to `null`. */
     readonly minRangeLength: _angular_core.InputSignal<number | null>;
@@ -101,11 +101,11 @@ declare class DateRangePickerComponent<D = Date> extends FormFieldControl<TwDate
     readonly rangeClickBehavior: _angular_core.InputSignal<RangeClickBehavior>;
     /** Override first day of week (0=Sun, 1=Mon) on the embedded calendar. Falls back to the adapter's default. */
     readonly firstDayOfWeek: _angular_core.InputSignal<number | null>;
-    /** Per-instance locale override. Forwarded to the embedded calendar and the underlying `DateAdapter` so the trigger display tracks the picker's locale. Falls back to Angular `LOCALE_ID` when `null`. */
+    /** Per-instance locale override. Forwarded to the embedded calendar and the underlying `DateAdapter` so the trigger display tracks the picker's locale. Falls back to Angular `LOCALE_ID` when `null`. Defaults to `null`. */
     readonly locale: _angular_core.InputSignal<string | null>;
-    /** Function producing per-cell CSS classes on the embedded calendar. */
+    /** Function producing per-cell CSS classes on the embedded calendar. Defaults to `null`. */
     readonly dateClass: _angular_core.InputSignal<DateClassFn<D> | null>;
-    /** Optional cell-content template, forwarded to the embedded calendar. Use to customize cell visuals beyond `dateClass`. */
+    /** Optional cell-content template, forwarded to the embedded calendar. Use to customize cell visuals beyond `dateClass`. Defaults to `null`. */
     readonly cellTemplate: _angular_core.InputSignal<TemplateRef<{
         $implicit: CalendarCell<D>;
     }> | null>;
@@ -123,15 +123,15 @@ declare class DateRangePickerComponent<D = Date> extends FormFieldControl<TwDate
     readonly minuteStep: _angular_core.InputSignal<number>;
     /** Step for the embedded time-pickers' second fields. Defaults to `1`. */
     readonly secondStep: _angular_core.InputSignal<number>;
-    /** Label for the `Today` action in the overlay's action bar. */
+    /** Label for the `Today` action in the overlay's action bar. Defaults to `'Today'`. */
     readonly todayLabel: _angular_core.InputSignal<string>;
-    /** Label for the `Clear` action in the overlay's action bar. */
+    /** Label for the `Clear` action in the overlay's action bar. Defaults to `'Clear'`. */
     readonly clearLabel: _angular_core.InputSignal<string>;
-    /** Label for the `Cancel` action in the overlay's action bar. */
+    /** Label for the `Cancel` action in the overlay's action bar. Defaults to `'Cancel'`. */
     readonly cancelLabel: _angular_core.InputSignal<string>;
-    /** Label for the `Apply` action in the overlay's action bar. */
+    /** Label for the `Apply` action in the overlay's action bar. Defaults to `'Apply'`. */
     readonly applyLabel: _angular_core.InputSignal<string>;
-    /** Extra class(es) applied to the overlay panel element. `twMerge` resolves conflicts with internal classes. */
+    /** Extra class(es) applied to the overlay panel element. `twMerge` resolves conflicts with internal classes. Defaults to an empty string. */
     readonly panelClass: _angular_core.InputSignal<string | readonly string[]>;
     /** CDK scroll strategy for the overlay. Defaults to `'reposition'`. */
     readonly scrollStrategy: _angular_core.InputSignal<"reposition" | "close" | "block">;
@@ -139,17 +139,17 @@ declare class DateRangePickerComponent<D = Date> extends FormFieldControl<TwDate
     readonly offset: _angular_core.InputSignal<number>;
     /** Accessible label for the clear button. Defaults to `'Clear date range'`. */
     readonly clearAriaLabel: _angular_core.InputSignal<string>;
-    /** Per-instance override of the `ErrorStateMatcher`. When omitted, uses the injected `TW_ERROR_STATE_MATCHER`. */
+    /** Per-instance override of the `ErrorStateMatcher`. When omitted, uses the injected `TW_ERROR_STATE_MATCHER`. Defaults to `undefined`. */
     readonly errorStateMatcher: _angular_core.InputSignal<ErrorStateMatcher | undefined>;
-    /** Accessible name for the trigger. Required when no visible label is supplied via `tw-form-field` or an external `aria-labelledby`. Alias: `aria-label`. */
+    /** Accessible name for the trigger. Required when no visible label is supplied via `tw-form-field` or an external `aria-labelledby`. Alias: `aria-label`. Defaults to `undefined`. */
     readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external element that labels the trigger. Alias: `aria-labelledby`. */
+    /** ID of an external element that labels the trigger. Alias: `aria-labelledby`. Defaults to `undefined`. */
     readonly ariaLabelledby: _angular_core.InputSignal<string | undefined>;
-    /** Consumer-supplied `aria-describedby` ids. The form-field preserves these when merging hint/error ids. Alias: `aria-describedby`. */
+    /** Consumer-supplied `aria-describedby` ids. The form-field preserves these when merging hint/error ids. Alias: `aria-describedby`. Defaults to `undefined`. */
     readonly userAriaDescribedByInput: _angular_core.InputSignal<string | undefined>;
-    /** Two-way bound selected range. `null` when no selection. Setting programmatically updates the trigger display and the calendar selection; it does NOT trigger `onChange`. */
+    /** Two-way bound selected range. `null` when no selection. Setting programmatically updates the trigger display and the calendar selection; it does NOT trigger `onChange`. Defaults to `null`. */
     readonly value: _angular_core.ModelSignal<TwDateRange<D> | null>;
-    /** Two-way bound open state of the overlay. Setting to `true` opens; setting to `false` closes. */
+    /** Two-way bound open state of the overlay. Setting to `true` opens; setting to `false` closes. Defaults to `false`. */
     readonly open: _angular_core.ModelSignal<boolean>;
     /** Fires after the overlay's enter animation completes. Payload is the trigger element. */
     readonly opened: _angular_core.OutputEmitterRef<DateRangePickerOpenedEvent>;
@@ -170,9 +170,6 @@ declare class DateRangePickerComponent<D = Date> extends FormFieldControl<TwDate
     private readonly destroyRef;
     private readonly formField;
     private ngControl;
-    private readonly parentForm;
-    private readonly parentFormGroup;
-    private readonly defaultMatcher;
     private readonly triggerRef;
     private readonly uid;
     /** @internal */
@@ -189,16 +186,16 @@ declare class DateRangePickerComponent<D = Date> extends FormFieldControl<TwDate
     readonly focusedSignal: _angular_core.WritableSignal<boolean>;
     private readonly cvaDisabled;
     private readonly describedByIdsSignal;
-    private readonly closingSignal;
     private readonly lastValueBeforeOpen;
     private readonly pendingRange;
     private readonly currentView;
-    private readonly _ngControlRev;
-    private readonly _formSubmitRev;
+    /** @internal Shared `errorState` / `required` / `errors` derivation — see `wireErrorState`. */
+    private readonly errorWiring;
     private onChange;
     private onTouched;
-    private readonly overlayInstanceSignal;
-    private get overlayInstance();
+    private overlayInstance;
+    private closing;
+    private readonly isAttached;
     /** @internal */
     readonly isDisabled: Signal<boolean>;
     /** @internal Effective variant — auto-naked when wrapped in tw-form-field. */
@@ -250,6 +247,16 @@ declare class DateRangePickerComponent<D = Date> extends FormFieldControl<TwDate
     readonly required: Signal<boolean>;
     /** @internal */
     readonly errorState: Signal<boolean>;
+    /**
+     * @internal Active validation errors map from the bound `NgControl` (or `null` when the
+     * control reports none / is unbound). This is what `[twError match="…"]` filters on inside a
+     * `<tw-form-field>`; without it every `match`-targeted message — including the
+     * `calendarMinDate` / `calendarMaxDate` / `calendarInvalidRange` / `calendarRangeTooShort` /
+     * `calendarRangeTooLong` codes this component's `NG_VALIDATORS` apparatus exists to produce —
+     * stays permanently hidden. (Authoritative key list: `CalendarValidationErrors` in
+     * `calendar.types.ts`.)
+     */
+    readonly errors: Signal<Record<string, unknown> | null>;
     /** @internal */
     readonly controlType = "date-range-picker";
     /** @internal */

package/types/cdevhub-ngx-tw-dialog-testing.d.ts

@@ -0,0 +1,98 @@
+import { ComponentHarness, BaseHarnessFilters, HarnessPredicate } from '@angular/cdk/testing';
+
+/** Filters accepted by `DialogHarness.with`. */
+interface DialogHarnessFilters extends BaseHarnessFilters {
+    /** Match by the dialog's id — the same value as `TwDialogRef.id`. */
+    id?: string | RegExp;
+    /** Match by the text of the projected `[twDialogTitle]` element. */
+    title?: string | RegExp;
+    /** Match by ARIA role — `'dialog'` or `'alertdialog'`. */
+    role?: string | RegExp;
+}
+/**
+ * Harness for a dialog opened with `TwDialog.open()`.
+ *
+ * ## Loading it
+ *
+ * A dialog is **service-opened**, not template-declared: nothing in the test
+ * fixture's own DOM represents it, and the container renders into the CDK
+ * overlay container on `document.body`. This harness's host *is* that container,
+ * so it must be loaded from
+ * `TestbedHarnessEnvironment.documentRootLoader(fixture)` — the ordinary
+ * `loader(fixture)` searches inside `fixture.nativeElement` and will never find
+ * it. This is not the same situation as an overlay *panel* belonging to a
+ * template-declared component (`tw-select`, `tw-popover-overlay`, `tw-menu`),
+ * where the harness hosts on the in-fixture trigger and reaches its panel
+ * internally; there the plain fixture loader is correct.
+ *
+ * ## Waiting for it
+ *
+ * `TwDialog` loads its render layer through a dynamic `import()`, so the
+ * container does **not** exist synchronously after `open()`. Await the ref's
+ * public {@link TwDialogRef.whenComponentReady} before asking for the harness —
+ * it resolves once the chunk has landed and the overlay is attached, for
+ * template dialogs (with `null`) as well as component dialogs.
+ *
+ * @example
+ * ```ts
+ * const ref = dialog.open(EditorDialog);
+ * await ref.whenComponentReady();
+ * const rootLoader = TestbedHarnessEnvironment.documentRootLoader(fixture);
+ * const harness = await rootLoader.getHarness(DialogHarness);
+ * expect(await harness.getTitleText()).toBe('Edit profile');
+ * ```
+ */
+declare class DialogHarness extends ComponentHarness {
+    static hostSelector: string;
+    private readonly title;
+    private readonly content;
+    /** Any descendant of the container that currently holds DOM focus. */
+    private readonly focusedDescendant;
+    /**
+     * Overlay backdrops, which are siblings of the dialog's overlay pane rather
+     * than descendants of the container — hence the document-root lookup.
+     */
+    private readonly backdrops;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: DialogHarnessFilters): HarnessPredicate<DialogHarness>;
+    /** The dialog's id. Matches the `id` on the `TwDialogRef` returned by `open()`. */
+    getId(): Promise<string | null>;
+    /** The dialog's ARIA role — `'dialog'`, or `'alertdialog'` when so configured. */
+    getRole(): Promise<string | null>;
+    /**
+     * Text of the projected `[twDialogTitle]` element, trimmed, or `null` when
+     * the dialog's content does not use the title directive.
+     */
+    getTitleText(): Promise<string | null>;
+    /**
+     * Text of the projected `[twDialogContent]` region, trimmed, or `null` when
+     * the dialog's content does not use the content directive.
+     */
+    getContentText(): Promise<string | null>;
+    /**
+     * Whether DOM focus currently sits on the dialog container or anywhere inside
+     * it — the observable consequence of the CDK focus trap. CDK moves focus
+     * asynchronously, so let the fixture settle after opening before asserting.
+     */
+    containsFocus(): Promise<boolean>;
+    /** Whether the dialog rendered a backdrop. */
+    hasBackdrop(): Promise<boolean>;
+    /**
+     * Clicks the backdrop — the pointer dismiss gesture. Does nothing observable
+     * when the dialog was opened with `disableClose: true`, which is exactly how
+     * a test asserts that flag.
+     *
+     * Throws when no backdrop is rendered. With several overlays stacked, the
+     * last backdrop in the overlay container is used, i.e. the topmost one.
+     */
+    clickBackdrop(): Promise<void>;
+    /**
+     * Sends Escape to the dialog — the keyboard dismiss gesture. Like
+     * {@link clickBackdrop}, it is deliberately a no-op when the dialog was
+     * opened with `disableClose: true`.
+     */
+    pressEscape(): Promise<void>;
+}
+
+export { DialogHarness };
+export type { DialogHarnessFilters };

package/types/cdevhub-ngx-tw-dialog.d.ts

@@ -104,17 +104,19 @@ declare class DialogContainer extends CdkDialogContainer<TwDialogConfig> {
 /**
  * Reference to a dialog opened via {@link TwDialog.open}. Drives the dialog
  * lifecycle (close, state, observables) and forwards useful overlay streams.
+ *
+ * The ref is returned **synchronously** from `open()`, but the dialog's render
+ * layer (`@angular/cdk/dialog` + the Tailwind container) is loaded through a
+ * dynamic `import()`. The ref therefore starts *detached*: `id`, `state`,
+ * `close()`, the lifecycle observables, and panel/size mutations all work
+ * immediately (mutations are buffered and replayed on attach), but the rendered
+ * component instance does not exist yet — read it via {@link whenComponentReady}
+ * instead of a synchronous `componentInstance` field.
  */
 declare class TwDialogRef<R = unknown, C = unknown> {
-    private readonly cdkRef;
     readonly config: TwDialogConfig<unknown, R>;
-    readonly containerInstance: DialogContainer;
-    /** Unique ID of the dialog. */
+    /** Unique ID of the dialog. Generated eagerly by the service, so it is valid the instant `open()` returns. */
     readonly id: string;
-    /** Instance of the component rendered inside the dialog, or `null` for template dialogs. */
-    componentInstance: C | null;
-    /** `ComponentRef` of the content component, or `null` for template dialogs. */
-    readonly componentRef: ComponentRef<C> | null;
     /** Current lifecycle state. Reactively readable. */
     readonly state: Signal<DialogState>;
     /** When `true`, close-via-escape and close-via-backdrop are disabled. */
@@ -123,9 +125,60 @@ declare class TwDialogRef<R = unknown, C = unknown> {
     private readonly afterOpenedSubject;
     private readonly beforeClosedSubject;
     private readonly afterClosedSubject;
+    private readonly backdropClickSubject;
+    private readonly keydownEventsSubject;
+    private cdkRef;
+    private container;
+    private componentInstanceValue;
+    private componentRefValue;
+    private resolveComponentReady;
+    private readonly componentReadyPromise;
+    private readonly pendingPanelAdds;
+    private readonly pendingPanelRemoves;
+    private pendingSize;
     private pendingResult;
     private closeFocusOrigin;
-    constructor(cdkRef: DialogRef<R, C>, config: TwDialogConfig<unknown, R>, containerInstance: DialogContainer);
+    constructor(id: string, config: TwDialogConfig<unknown, R>);
+    /**
+     * The Tailwind container instance, or `null` until the dialog has attached.
+     * `null` is the normal value for the first tick after `open()` returns,
+     * because the render layer is loaded through a dynamic `import()`.
+     *
+     * Only `state`, `animationStateChanged`, `enterAnimationDuration` and
+     * `exitAnimationDuration` are supported reads; the `_`-prefixed members are
+     * library-internal wiring and may change without a major bump. Prefer
+     * {@link state} and {@link afterOpened} on the ref itself.
+     */
+    get containerInstance(): DialogContainer | null;
+    /**
+     * @internal Wire this facade to its CDK backend. Called from the dialog
+     * renderer **inside** `cdkDialog.open()`'s `providers` callback — the same
+     * point the constructor ran before deferral — so subscriptions to
+     * `animationStateChanged` are in place before the container emits `'open'`.
+     */
+    _attach(cdkRef: DialogRef<R, C>, container: DialogContainer): void;
+    /** @internal Record the rendered component after `cdkDialog.open()` returns. */
+    _setComponent(instance: C | null, ref: ComponentRef<C> | null): void;
+    /**
+     * Resolves with the rendered content-component instance once the dialog's
+     * render chunk has loaded and attached. Resolves `null` for template dialogs,
+     * and for a dialog closed before it ever opened.
+     *
+     * Replaces the former synchronous `componentInstance` field, which cannot be
+     * populated before the deferred render chunk lands.
+     *
+     * @example
+     * ```ts
+     * const ref = dialog.open(EditorDialog);
+     * const editor = await ref.whenComponentReady();
+     * editor?.focusFirstField();
+     * ```
+     */
+    whenComponentReady(): Promise<C | null>;
+    /** The rendered component instance, or `null` if not yet attached / a template dialog. Prefer {@link whenComponentReady}. */
+    get componentInstance(): C | null;
+    /** The rendered `ComponentRef`, or `null` if not yet attached / a template dialog. */
+    get componentRef(): ComponentRef<C> | null;
     /**
      * Closes the dialog. The exit animation runs before the overlay is disposed.
      * @param result Value forwarded to `afterClosed()` subscribers.
@@ -137,15 +190,15 @@ declare class TwDialogRef<R = unknown, C = unknown> {
     beforeClosed(): Observable<R | undefined>;
     /** Observable that emits once after the dialog has fully closed and the overlay is disposed. */
     afterClosed(): Observable<R | undefined>;
-    /** Backdrop click stream (emits even when `disableClose` is set). */
+    /** Backdrop click stream (emits even when `disableClose` is set). Buffered — a subscription made before the dialog attaches receives events once it does. */
     backdropClick(): Observable<MouseEvent>;
-    /** Keydown event stream for the overlay. */
+    /** Keydown event stream for the overlay. Buffered — a subscription made before the dialog attaches receives events once it does. */
     keydownEvents(): Observable<KeyboardEvent>;
-    /** Updates the dialog's width/height. Pass empty string to reset a dimension. */
+    /** Updates the dialog's width/height. Pass empty string to reset a dimension. Buffered until attach. */
     updateSize(width?: string | number, height?: string | number): this;
-    /** Adds CSS classes to the overlay panel. */
+    /** Adds CSS classes to the overlay panel. Buffered until attach. */
     addPanelClass(classes: string | string[]): this;
-    /** Removes CSS classes from the overlay panel. */
+    /** Removes CSS classes from the overlay panel. Buffered until attach. */
     removePanelClass(classes: string | string[]): this;
     private closeWithOrigin;
     private finishClose;
@@ -156,13 +209,21 @@ declare class TwDialogRef<R = unknown, C = unknown> {
  * trapping, portals, overlay plumbing, and adds a Tailwind container, richer
  * ref API, and animation lifecycle.
  *
+ * The rendering layer (`@angular/cdk/dialog` + the Tailwind container) is loaded
+ * through a dynamic `import()` on the first `open()` call, so merely registering
+ * this service costs nothing in the initial bundle. `open()` still returns its
+ * {@link TwDialogRef} synchronously — the dialog is rendered once the chunk
+ * lands. Read the rendered component via {@link TwDialogRef.whenComponentReady}.
+ *
  * Not `providedIn: 'root'` — register it via {@link provideTwDialog}.
  */
 declare class TwDialog implements OnDestroy {
-    private readonly cdkDialog;
     private readonly injector;
     private readonly defaultOptions;
     private readonly parentDialog;
+    /** Cached renderer chunk import — kicked off on the first `open()`. */
+    private rendererPromise;
+    private destroyed;
     private readonly openDialogsAtThisLevel;
     private readonly afterOpenedSubject;
     private readonly afterAllClosedSubject;
@@ -179,7 +240,7 @@ declare class TwDialog implements OnDestroy {
      * Opens a dialog using the given component or template.
      * @param content Component class or `TemplateRef`.
      * @param config Options merged over the application defaults.
-     * @returns Reference controlling the opened dialog.
+     * @returns Reference controlling the opened dialog, returned synchronously.
      */
     open<R = unknown, D = unknown, C = unknown>(content: ComponentType<C> | TemplateRef<C>, config?: TwDialogConfig<D, R>): TwDialogRef<R, C>;
     /** Closes every open dialog managed by this service (and child services). */
@@ -187,11 +248,22 @@ declare class TwDialog implements OnDestroy {
     /** Looks up an open dialog by its id. */
     getDialogById<R = unknown, C = unknown>(id: string): TwDialogRef<R, C> | undefined;
     ngOnDestroy(): void;
+    /**
+     * @internal Resolves once the renderer chunk has loaded. Exposed for tests,
+     * which must await the dynamic import before asserting on rendered DOM.
+     */
+    _whenRendered(): Promise<void>;
+    /**
+     * Render a dialog once the renderer chunk has loaded. The ref was already
+     * returned to the caller, so it may have been closed (or the service
+     * destroyed) while the import was in flight — both skip the actual open.
+     */
+    private renderWhenReady;
+    private loadRenderer;
     private registerOpen;
     private unregister;
     private getAfterAllClosedSource;
     private resolveConfig;
-    private resolveScrollStrategy;
     static ɵfac: i0.ɵɵFactoryDeclaration<TwDialog, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<TwDialog>;
 }
@@ -233,7 +305,6 @@ declare class DialogIconDirective {
 declare class DialogTitleDirective implements OnInit, OnDestroy {
     private readonly generatedId;
     private readonly dialogRef;
-    private readonly container;
     /** Custom id for the title element. Defaults to a generated unique id. */
     readonly id: i0.InputSignal<string>;
     ngOnInit(): void;
@@ -254,7 +325,6 @@ declare class DialogSubtitleDirective {
 declare class DialogDescriptionDirective implements OnInit, OnDestroy {
     private readonly generatedId;
     private readonly dialogRef;
-    private readonly container;
     /** Custom id for the description element. Defaults to a generated unique id. */
     readonly id: i0.InputSignal<string>;
     ngOnInit(): void;
@@ -289,7 +359,7 @@ declare class DialogActionsDirective {
  * `[twDialogClose]` value to pass a result to `afterClosed()` subscribers.
  */
 declare class DialogCloseDirective {
-    /** Value passed to `afterClosed()` when the button is clicked. */
+    /** Value passed to `afterClosed()` when the button is clicked. Defaults to `undefined`. */
     readonly twDialogClose: i0.InputSignal<unknown>;
     /** Native button `type`. Defaults to `'button'` to avoid accidental form submission. */
     readonly type: i0.InputSignal<"button" | "submit" | "reset">;