@limetech/lime-web-components 6.4.1 → 6.5.0

package/dist/dialog/dialog.d.ts

@@ -1,52 +1,188 @@
 /**
- * Service for creating and displaying dialogs containing a web component
+ * Service for creating and managing dialogs
  *
- * @emits dialog.destroyed - When the dialog is beeing externally destroyed,
- * e.g. by closing a popup window (depending on platform), a
- * {@link DialogDestroyedEvent} will be emitted using
+ * The {@link DialogRenderer} enables displaying web components in dialogs,
+ * which can be modal or non-modal. It is accessed through the
+ * {@link LimeWebComponentPlatform} instance provided to components.
+ *
+ * Dialogs are useful for:
+ * - User input forms
+ * - Confirmation prompts
+ * - Detail views
+ * - Multi-step wizards
+ *
+ * The rendering implementation depends on the platform. Most commonly, dialogs
+ * are rendered directly on the current page. On some platforms, dialogs may be
+ * opened as separate native windows.
+ *
+ * @emits dialog.destroyed - When a dialog is externally destroyed (e.g., popup
+ * window closed by user), a {@link DialogDestroyedEvent} is emitted via
  * {@link EventDispatcher}
+ *
+ * @example
+ * Basic usage
+ * ```typescript
+ * const dialogRenderer = platform.get(PlatformServiceNames.Dialog);
+ *
+ * // Create a dialog
+ * const dialogId = dialogRenderer.create('my-dialog-component', {
+ *     title: 'Confirmation',
+ *     message: 'Are you sure?'
+ * });
+ *
+ * // Update dialog properties
+ * dialogRenderer.update(dialogId, { message: 'Processing...' });
+ *
+ * // Close the dialog
+ * dialogRenderer.destroy(dialogId);
+ * ```
+ *
  * @public
  * @group Dialog
  */
 export interface DialogRenderer {
     /**
-     * Create a new dialog and render its contents. Depending on what kind of
-     * platform the service is used on, the dialog might be rendered in the
-     * current `Document` or opened in a new popup window.
-     *
-     * @param name - the name of the web component representing the dialog
-     * @param properties - any properties to send to the dialog
-     * @param listeners - any event listeners to register on the dialog
-     * @returns id representing the dialog
+     * Create and display a new dialog
+     *
+     * Creates a dialog containing the specified web component. The dialog can be
+     * modal or non-modal depending on the component implementation. The rendering
+     * approach depends on the platform - most commonly as an overlay on the current
+     * page, but on some platforms as a separate native window.
+     *
+     * @param name - Tag name of the web component to render in the dialog (e.g., 'my-dialog-component')
+     * @param properties - Props to pass to the dialog component. These will be set as properties on the component instance.
+     * @param listeners - Event listeners to register on the dialog component. Keys are event names, values are handler functions.
+     * @returns Unique identifier for the created dialog. Use this ID with {@link DialogRenderer.update} and {@link DialogRenderer.destroy}.
+     *
+     * @example
+     * ```typescript
+     * const dialogRenderer = this.platform.get(PlatformServiceNames.Dialog);
+     * const dialogId = dialogRenderer.create(
+     *     'confirmation-dialog',
+     *     { title: 'Delete Item', message: 'This cannot be undone' },
+     *     {
+     *         'confirm': () => this.deleteItem(),
+     *         'cancel': () => dialogRenderer.destroy(dialogId)
+     *     }
+     * );
+     * ```
      */
     create(name: string, properties?: DialogProperties, listeners?: DialogListeners): number;
     /**
-     * Update an existing dialog with new properties
+     * Update an existing dialog's properties
+     *
+     * Updates the properties of a dialog that was previously created. This is
+     * useful for updating dialog content based on user interactions or data changes.
+     *
+     * Event listeners cannot be updated and will remain as originally registered.
+     *
+     * @param id - The dialog identifier returned from {@link DialogRenderer.create}
+     * @param properties - New property values to set on the dialog component
+     *
+     * @example
+     * ```typescript
+     * const dialogRenderer = this.platform.get(PlatformServiceNames.Dialog);
+     * const dialogId = dialogRenderer.create('progress-dialog', {
+     *     progress: 0,
+     *     status: 'Starting...'
+     * });
      *
-     * @param id - the dialog identifier
-     * @param properties - any properties to send to the dialog
+     * // Later, update progress
+     * dialogRenderer.update(dialogId, {
+     *     progress: 50,
+     *     status: 'Processing...'
+     * });
+     * ```
      */
     update(id: number, properties?: DialogProperties): void;
     /**
-     * Destroy a dialog
+     * Close and destroy a dialog
      *
-     * @param id - id representing the dialog
+     * Removes the dialog from the DOM and cleans up all associated resources
+     * and event listeners. If the dialog was rendered as a popup window, the
+     * window will be closed.
+     *
+     * @param id - The dialog identifier returned from {@link DialogRenderer.create}
+     *
+     * @example
+     * ```typescript
+     * const dialogRenderer = this.platform.get(PlatformServiceNames.Dialog);
+     * const dialogId = dialogRenderer.create('my-dialog');
+     *
+     * // Later, close the dialog
+     * dialogRenderer.destroy(dialogId);
+     * ```
      */
     destroy(id: number): void;
 }
 /**
+ * Properties to pass to a dialog component
+ *
+ * An object mapping property names to values. These will be set as properties
+ * on the dialog's web component instance when the dialog is created or updated.
+ *
+ * @example
+ * ```typescript
+ * const properties: DialogProperties = {
+ *     userId: 123,
+ *     mode: 'edit',
+ *     allowDelete: true,
+ *     fields: ['name', 'email', 'phone']
+ * };
+ * dialogRenderer.create('user-form-dialog', properties);
+ * ```
+ *
  * @public
  * @group Dialog
  */
 export type DialogProperties = Record<string, any>;
 /**
+ * Event listeners for a dialog component
+ *
+ * An object mapping event names to handler functions. These listeners will be
+ * registered on the dialog's web component instance when the dialog is created.
+ *
+ * @example
+ * ```typescript
+ * const listeners: DialogListeners = {
+ *     'save': (event?: CustomEvent<User>) => {
+ *         console.log('User saved:', event?.detail);
+ *     },
+ *     'cancel': () => {
+ *         console.log('Cancelled');
+ *     },
+ *     'delete': (event?: CustomEvent<number>) => {
+ *         console.log('Delete user:', event?.detail);
+ *     }
+ * };
+ * dialogRenderer.create('user-form-dialog', properties, listeners);
+ * ```
+ *
  * @public
  * @group Dialog
  */
 export type DialogListeners = Record<string, (event?: CustomEvent<any>) => void>;
 /**
- * @event dialog.destroyed - Emitted when a dialog is externally destroyed, e.g.
- * by closing a popup window
+ * Event emitted when a dialog is externally destroyed
+ *
+ * This event is dispatched via {@link EventDispatcher} when a dialog is closed
+ * by external means, such as the user closing a popup window. The event detail
+ * contains the dialog ID that was destroyed.
+ *
+ * This allows the component that created the dialog to clean up any references
+ * or state associated with the dialog.
+ *
+ * @event dialog.destroyed
+ *
+ * @example
+ * ```typescript
+ * const eventDispatcher = this.platform.get(PlatformServiceName.EventDispatcher);
+ * eventDispatcher.addListener('dialog.destroyed', (event: DialogDestroyedEvent) => {
+ *     const destroyedDialogId = event.detail;
+ *     console.log(`Dialog ${destroyedDialogId} was closed`);
+ * });
+ * ```
+ *
  * @public
  * @group Dialog
  */

package/dist/dialog/dialog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dialog.d.ts","sourceRoot":"","sources":["../../src/dialog/dialog.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC3B;;;;;;;;;OASG;IACH,MAAM,CACF,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,gBAAgB,EAC7B,SAAS,CAAC,EAAE,eAAe,GAC5B,MAAM,CAAC;IAEV;;;;;OAKG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAExD;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;GAGG;AAEH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEnD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAChC,MAAM,EAEN,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,KAAK,IAAI,CACrC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"dialog.d.ts","sourceRoot":"","sources":["../../src/dialog/dialog.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,WAAW,cAAc;IAC3B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CACF,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,gBAAgB,EAC7B,SAAS,CAAC,EAAE,eAAe,GAC5B,MAAM,CAAC;IAEV;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAExD;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAChC,MAAM,EAEN,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,KAAK,IAAI,CACrC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC"}