@operato/shell 1.12.9 → 1.14.1

package/src/app/pages/page-view.ts

@@ -22,12 +22,26 @@ function diff(after: any, before: any): any {
   return changed && changes
 }
 
+/**
+ * PageView is a base class for creating page elements with lifecycle management.
+ * Subclasses can extend PageView to define custom behavior and handle page lifecycle events.
+ */
 export class PageView extends LitElement {
+  /**
+   * Determines whether the page can be deactivated. Subclasses can override this method
+   * to implement custom deactivation logic.
+   * @returns A Promise that resolves to true if the page can be deactivated, or false otherwise.
+   */
   async canDeactivate(): Promise<boolean> {
     return Promise.resolve(true)
   }
 
-  // Only render this page if it's actually visible.
+  /**
+   * Determines whether the page should update. This method is called whenever there are
+   * changes to the page's properties.
+   * @param changes - A map of changed property values.
+   * @returns True if the page should update, or false otherwise.
+   */
   shouldUpdate(changes: PropertyValues<this>) {
     var active = String(this.active) == 'true'
     var { active: oldActive = false } = this._oldLifecycleInfo$ || {}
@@ -50,13 +64,31 @@ export class PageView extends LitElement {
     return active
   }
 
+  /**
+   * Indicates whether the page is currently active.
+   */
   @property({ type: Boolean }) active: boolean = false
+
+  /**
+   * Stores information about the page's lifecycle.
+   */
   @property({ type: Object }) lifecycle: any
+
+  /**
+   * The context path for the page.
+   */
   @property({ type: String, attribute: 'context-path' }) contextPath?: string
 
   _oldLifecycleInfo$: any
 
   /* lifecycle */
+
+  /**
+   * Handles page updates and lifecycle events. Subclasses can override this method
+   * to implement custom logic for initializing, updating, and disposing of the page.
+   * @param changes - A map of changed properties.
+   * @param force - If true, forces an update of the page.
+   */
   async pageUpdate(changes: any = {}, force: boolean = false) {
     var before = this._oldLifecycleInfo$ || {}
 
@@ -113,6 +145,9 @@ export class PageView extends LitElement {
     }
   }
 
+  /**
+   * Resets the page. Subclasses can override this method to perform custom reset logic.
+   */
   async pageReset() {
     var { initialized } = this._oldLifecycleInfo$ || {}
 
@@ -122,14 +157,35 @@ export class PageView extends LitElement {
     }
   }
 
+  /**
+   * Disposes of the page. Subclasses can override this method to perform custom disposal logic.
+   */
   async pageDispose() {
     await this.pageUpdate({
       initialized: false
     })
   }
 
+  /**
+   * Initializes the page. Subclasses can override this method to perform custom initialization logic.
+   * @param pageInfo - Information about the page's state.
+   */
   pageInitialized(pageInfo: any) {}
+
+  /**
+   * Handles page updates and changes in properties.
+   * Subclasses can override this method to implement custom update logic.
+   * @param changes - A map of changed properties.
+   * @param after - The current state of the page.
+   * @param before - The previous state of the page.
+   */
   pageUpdated(changes: any, after: any, before: any) {}
+
+  /**
+   * Handles the disposal of the page. Subclasses can override this method
+   * to implement custom disposal logic.
+   * @param pageInfo - Information about the page's state.
+   */
   pageDisposed(pageInfo: any) {}
 
   /* context */
@@ -140,6 +196,12 @@ export class PageView extends LitElement {
     })
   }
 
+  /**
+   * Updates the context of the page. Subclasses can override the `context` getter
+   * to provide specific context information for the page. The context will be updated
+   * using the `updateContext` method inherited from PageView.
+   * @param override - An optional object with context properties to override.
+   */
   get context() {
     return {}
   }