@cdevhub/ngx-tw 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cdevhub/ngx-tw",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Angular component library for Tailwind CSS v4 — accessible, signal-based, built on Angular CDK.",
   "keywords": [
     "angular",

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,51 @@ 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. */
+    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 +181,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 +200,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 +231,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 +239,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 +296,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 +316,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;
@@ -299,5 +360,5 @@ declare class DialogCloseDirective {
     static ɵdir: i0.ɵɵDirectiveDeclaration<DialogCloseDirective, "[twDialogClose]", never, { "twDialogClose": { "alias": "twDialogClose"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-export { DialogActionsDirective, DialogCloseDirective, DialogContainer, DialogContentDirective, DialogDescriptionDirective, DialogHeaderDirective, DialogIconDirective, DialogSubtitleDirective, DialogTitleDirective, TW_DIALOG_DATA, TW_DIALOG_DEFAULT_OPTIONS, TwDialog, TwDialogConfig, TwDialogRef, provideTwDialog };
+export { DialogActionsDirective, DialogCloseDirective, DialogContentDirective, DialogDescriptionDirective, DialogHeaderDirective, DialogIconDirective, DialogSubtitleDirective, DialogTitleDirective, TW_DIALOG_DATA, TW_DIALOG_DEFAULT_OPTIONS, TwDialog, TwDialogConfig, TwDialogRef, provideTwDialog };
 export type { DialogActionsAlign, DialogAnimationEvent, DialogState, TwDialogAutoFocus, TwDialogRestoreFocus, TwDialogRole, TwDialogScrollStrategy, TwDialogSize };

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

@@ -132,17 +132,19 @@ declare class SheetContainer extends CdkDialogContainer<SheetConfig> {
 /**
  * Reference to a sheet opened via {@link Sheet.open}. Drives the sheet
  * lifecycle (close, state, observables) and forwards useful overlay streams.
+ *
+ * The ref is returned **synchronously** from `open()`, but the sheet'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 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 SheetRef<R = unknown, C = unknown> {
-    private readonly cdkRef;
     readonly config: SheetConfig<unknown, R>;
-    readonly containerInstance: SheetContainer;
-    /** Unique ID of the sheet. */
+    /** Unique ID of the sheet. Generated eagerly by the service, so it is valid the instant `open()` returns. */
     readonly id: string;
-    /** Instance of the component rendered inside the sheet, or `null` for template sheets. */
-    componentInstance: C | null;
-    /** `ComponentRef` of the content component, or `null` for template sheets. */
-    readonly componentRef: ComponentRef<C> | null;
     /** Current lifecycle state. Reactively readable. */
     readonly state: Signal<SheetState>;
     /** When `true`, close-via-escape AND close-via-backdrop are both disabled. */
@@ -155,9 +157,50 @@ declare class SheetRef<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 pendingResult;
     private closeFocusOrigin;
-    constructor(cdkRef: DialogRef<R, C>, config: SheetConfig<unknown, R>, containerInstance: SheetContainer);
+    constructor(id: string, config: SheetConfig<unknown, R>);
+    /** The Tailwind container instance, or `null` until the sheet has attached. */
+    get containerInstance(): SheetContainer | null;
+    /**
+     * @internal Wire this facade to its CDK backend. Called from the sheet
+     * 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: SheetContainer): 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 sheet's
+     * render chunk has loaded and attached. Resolves `null` for template sheets,
+     * and for a sheet 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 = sheet.open(FilterSheet);
+     * const filters = await ref.whenComponentReady();
+     * filters?.reset();
+     * ```
+     */
+    whenComponentReady(): Promise<C | null>;
+    /** The rendered component instance, or `null` if not yet attached / a template sheet. Prefer {@link whenComponentReady}. */
+    get componentInstance(): C | null;
+    /** The rendered `ComponentRef`, or `null` if not yet attached / a template sheet. */
+    get componentRef(): ComponentRef<C> | null;
     /**
      * Closes the sheet. The exit slide animation runs before the overlay is disposed.
      * @param result Value forwarded to `afterClosed()` subscribers.
@@ -169,13 +212,13 @@ declare class SheetRef<R = unknown, C = unknown> {
     beforeClosed(): Observable<R | undefined>;
     /** Observable that emits once after the sheet has fully closed and the overlay is disposed. */
     afterClosed(): Observable<R | undefined>;
-    /** Backdrop click stream (emits even when `closeOnBackdropClick` / `disableClose` is set). */
+    /** Backdrop click stream (emits even when `closeOnBackdropClick` / `disableClose` is set). Buffered — a subscription made before the sheet 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 sheet attaches receives events once it does. */
     keydownEvents(): Observable<KeyboardEvent>;
-    /** 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;
@@ -187,13 +230,21 @@ declare class SheetRef<R = unknown, C = unknown> {
  * pinned to the requested viewport edge, a Tailwind container with axis-aware
  * sizing, slide enter/exit animations, and split close-behavior flags.
  *
+ * 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 SheetRef} synchronously — the sheet is rendered once the chunk lands.
+ * Read the rendered component via {@link SheetRef.whenComponentReady}.
+ *
  * Not `providedIn: 'root'` — register it via {@link provideSheet}.
  */
 declare class Sheet implements OnDestroy {
-    private readonly cdkDialog;
     private readonly injector;
     private readonly defaultOptions;
     private readonly parentSheet;
+    /** Cached renderer chunk import — kicked off on the first `open()`. */
+    private rendererPromise;
+    private destroyed;
     private readonly openSheetsAtThisLevel;
     private readonly afterOpenedSubject;
     private readonly afterAllClosedSubject;
@@ -210,7 +261,7 @@ declare class Sheet implements OnDestroy {
      * Opens a sheet 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 sheet.
+     * @returns Reference controlling the opened sheet, returned synchronously.
      */
     open<R = unknown, D = unknown, C = unknown>(content: ComponentType<C> | TemplateRef<C>, config?: SheetConfig<D, R>): SheetRef<R, C>;
     /** Closes every open sheet managed by this service (and child services). */
@@ -218,12 +269,22 @@ declare class Sheet implements OnDestroy {
     /** Looks up an open sheet by its id. */
     getSheetById<R = unknown, C = unknown>(id: string): SheetRef<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 sheet 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;
-    private resolvePositionStrategy;
     static ɵfac: i0.ɵɵFactoryDeclaration<Sheet, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<Sheet>;
 }
@@ -265,7 +326,6 @@ declare class SheetIconDirective {
 declare class SheetTitleDirective implements OnInit, OnDestroy {
     private readonly generatedId;
     private readonly sheetRef;
-    private readonly container;
     /** Custom id for the title element. Defaults to a generated unique id. */
     readonly id: i0.InputSignal<string>;
     ngOnInit(): void;
@@ -286,7 +346,6 @@ declare class SheetSubtitleDirective {
 declare class SheetDescriptionDirective implements OnInit, OnDestroy {
     private readonly generatedId;
     private readonly sheetRef;
-    private readonly container;
     /** Custom id for the description element. Defaults to a generated unique id. */
     readonly id: i0.InputSignal<string>;
     ngOnInit(): void;
@@ -331,5 +390,5 @@ declare class SheetCloseDirective {
     static ɵdir: i0.ɵɵDirectiveDeclaration<SheetCloseDirective, "[twSheetClose]", never, { "twSheetClose": { "alias": "twSheetClose"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-export { SHEET_DATA, SHEET_DEFAULT_OPTIONS, Sheet, SheetActionsDirective, SheetCloseDirective, SheetConfig, SheetContainer, SheetContentDirective, SheetDescriptionDirective, SheetHeaderDirective, SheetIconDirective, SheetRef, SheetSubtitleDirective, SheetTitleDirective, provideSheet };
+export { SHEET_DATA, SHEET_DEFAULT_OPTIONS, Sheet, SheetActionsDirective, SheetCloseDirective, SheetConfig, SheetContentDirective, SheetDescriptionDirective, SheetHeaderDirective, SheetIconDirective, SheetRef, SheetSubtitleDirective, SheetTitleDirective, provideSheet };
 export type { SheetActionsAlign, SheetAnimationEvent, SheetAutoFocus, SheetRestoreFocus, SheetRole, SheetScrollStrategy, SheetSide, SheetSize, SheetState };

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

@@ -88,6 +88,17 @@ declare class ToastRef<C = unknown, R = unknown> {
     private enterTimer;
     private leaveTimer;
     constructor(id: string, content: ToastContent, config: ToastConfig<unknown, R>, dismissCallback: (ref: ToastRef) => void);
+    /**
+     * @internal Start the enter animation clock. Called by the service once the
+     * toast has actually been attached to its container.
+     *
+     * This deliberately does NOT run from the constructor. The renderer is loaded
+     * through a dynamic `import()`, so a ref can exist for an arbitrary stretch
+     * before anything is on screen — starting the clock at construction would let
+     * a toast burn part (or all) of its auto-dismiss duration while still
+     * invisible on a slow connection. Idempotent and safe to call after dismissal.
+     */
+    _startEnterSequence(): void;
     /**
      * Dismiss the toast programmatically. The leave animation plays before the
      * element is removed and subscribers are notified. Safe to call multiple times.
@@ -225,14 +236,22 @@ interface PromiseMessages<T> {
  * created per `ToastPosition` on first use and reused for the lifetime of the
  * service; toasts stack vertically inside their position container.
  *
+ * The rendering layer (CDK overlay + the toast components) is loaded through a
+ * dynamic `import()` on the first `show()` call, so merely registering this
+ * service costs nothing in the initial bundle. Every open method still returns
+ * its {@link ToastRef} synchronously — the toast is attached once the chunk
+ * lands, and `update()` / `dismiss()` called in the meantime are honoured.
+ *
  * Not `providedIn: 'root'` — register via {@link provideToast}.
  */
 declare class ToastService implements OnDestroy {
-    private readonly overlay;
     private readonly injector;
     private readonly defaultOptions;
     private readonly parent;
-    private readonly positionOverlays;
+    /** Cached renderer chunk. Non-null once the first `show()` has kicked off the import. */
+    private rendererPromise;
+    private renderer;
+    private destroyed;
     private readonly activeRefsAtThisLevel;
     private readonly afterOpenedSubject;
     private readonly afterAllDismissedSubject;
@@ -273,14 +292,30 @@ declare class ToastService implements OnDestroy {
     ngOnDestroy(): void;
     private openWithSeverity;
     private openInternal;
+    /**
+     * Attach a toast once the renderer chunk has loaded. The ref was already
+     * returned to the caller, so it may have been dismissed (or the service
+     * destroyed) while the import was in flight — both are checked before
+     * anything is put on screen.
+     */
+    private attachWhenRendererReady;
+    /**
+     * @internal Resolves once the renderer chunk has loaded and pending toasts
+     * have been attached. Exposed for tests, which must await the dynamic import
+     * before asserting on rendered DOM.
+     */
+    _whenRendered(): Promise<void>;
+    /** Load (once) and instantiate the rendering layer. Resolves to `null` if the service was destroyed mid-import. */
+    private loadRenderer;
     private enforceMaxVisible;
     private registerOpen;
     private handleDismissed;
-    private attachToContainer;
-    private announceOpen;
+    /**
+     * Re-announce an updated toast. If the renderer has not landed yet there is
+     * nothing on screen to announce — the announcement that fires on attach
+     * reads the ref's current (already updated) content, so nothing is lost.
+     */
     private announceUpdate;
-    private getContainerForPosition;
-    private buildPositionStrategy;
     private resolveConfig;
     private getAfterAllDismissedSource;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ToastService, never>;