* core: enhance HElement class with detailed documentation for lifecycle methods and props handling

Author: catouse

lib/core/src/react/components/h-element.ts

@@ -39,6 +39,9 @@ export class HElement<P extends HElementProps, S = object> extends Component<P,
      */
     declare ['constructor']: typeof HElement<P, S>;
 
+    /**
+     * The unique global ID of the component instance, used to locate the rendered DOM element.
+     */
     protected _gid = nextGid();
 
     constructor(props: P) {
@@ -47,10 +50,20 @@ export class HElement<P extends HElementProps, S = object> extends Component<P,
         this.state = this.getDefaultState(props);
     }
 
+    /**
+     * Get the unique global ID of the component instance.
+     *
+     * @returns The unique global ID.
+     */
     get gid() {
         return this._gid;
     }
 
+    /**
+     * Get the DOM element.
+     *
+     * @returns The DOM element.
+     */
     get element() {
         return document.querySelector(`[z-gid-${this._gid}]`);
     }
@@ -69,10 +82,22 @@ export class HElement<P extends HElementProps, S = object> extends Component<P,
         return this.constructor.NAME;
     }
 
+    /**
+     * Get the default state.
+     *
+     * @param props The props.
+     * @returns The default state.
+     */
     getDefaultState(_props?: RenderableProps<P>): S {
         return {} as S;
     }
 
+    /**
+     * Reset the state.
+     *
+     * @param props The props.
+     * @param init Whether to initialize the state.
+     */
     resetState(props?: RenderableProps<P>, init?: boolean) {
         const defaultState = this.getDefaultState(props);
         if (init) {
@@ -124,6 +149,13 @@ export class HElement<P extends HElementProps, S = object> extends Component<P,
             ?? `{i18n:${key}}`;
     }
 
+    /**
+     * Change the component state.
+     *
+     * @param state The new state.
+     * @param callback The callback to call after the state is changed.
+     * @returns The promise of the state.
+     */
     changeState(state: Partial<S> | ((prevState: Readonly<S>) => Partial<S>), callback?: () => void): Promise<S> {
         return new Promise<S>((resolve) => {
             this.setState(state, () => {
@@ -133,6 +165,13 @@ export class HElement<P extends HElementProps, S = object> extends Component<P,
         });
     }
 
+    /**
+     * Execute a command.
+     *
+     * @param context The command context.
+     * @param params The command parameters.
+     * @returns The result of the command.
+     */
     executeCommand(context: CommandContext | string, params: unknown[] = []) {
         const {onCommand, commands} = this.props;
         let result;
@@ -153,10 +192,25 @@ export class HElement<P extends HElementProps, S = object> extends Component<P,
         return result;
     }
 
+    /**
+     * Get the class name(s) applied to the root element.
+     * Subclasses can override this to inject component-specific classes.
+     *
+     * @param props The current renderable props.
+     * @returns     The class name(s) to merge onto the root element.
+     */
     protected _getClassName(props: RenderableProps<P>): ClassNameLike {
         return props.className;
     }
 
+    /**
+     * Resolve the final attributes/props passed to the underlying DOM element or component.
+     * Filters out framework-only props, allows whitelisted custom props, forwards `data-*`,
+     * `z-*`, `zui-*` and event handler attributes, and stamps the unique `z-gid-*` marker.
+     *
+     * @param props The current renderable props.
+     * @returns     The merged props object to spread onto the rendered element.
+     */
     protected _getProps(props: RenderableProps<P>): Record<string, unknown> {
         const {className, attrs, props: componentProps, data, forwardRef, children, component, style, class: classNameAlt, commands, onCommand, ...others} = props;
         const customProps = new Set((this.constructor as typeof HElement).customProps);
@@ -171,19 +225,53 @@ export class HElement<P extends HElementProps, S = object> extends Component<P,
         return {ref: forwardRef, className: classes(this._getClassName(props), classNameAlt), style, [`z-gid-${this._gid}`]: '', ...other, ...attrs, ...componentProps};
     }
 
+    /**
+     * Resolve the actual component/tag to render.
+     * Accepts a tag name, a registered component name, or a component reference;
+     * defaults to a `div` when not specified.
+     *
+     * @param props The current renderable props.
+     * @returns     The resolved component type or intrinsic HTML tag name.
+     */
     protected _getComponent(props: RenderableProps<P>): ComponentType | keyof JSX.IntrinsicElements {
         const {component = 'div'} = props;
         return (typeof component === 'string' ? getReactComponent(component as string) : component) || component;
     }
 
+    /**
+     * Resolve the children rendered inside the root element.
+     * Subclasses can override this to compose additional content around `props.children`.
+     *
+     * @param props The current renderable props.
+     * @returns     The children to render.
+     */
     protected _getChildren(props: RenderableProps<P>): ComponentChildren {
         return props.children;
     }
 
+    /**
+     * Hook invoked before the render pipeline starts.
+     * Subclasses can override this to transform or replace the incoming props;
+     * returning `void` keeps the original props unchanged.
+     *
+     * @param props The current renderable props.
+     * @returns     The (optionally) transformed props, or `void` to keep them as-is.
+     */
     protected _beforeRender(props: RenderableProps<P>): RenderableProps<P> | void {
         return props;
     }
 
+    /**
+     * Final hook invoked right before `h()` is called.
+     * Subclasses can override this to swap the component, mutate the resolved props,
+     * or wrap the children. Returning `undefined` keeps the inputs unchanged.
+     *
+     * @param component      The resolved component type or tag name.
+     * @param componentProps The resolved props to pass to the component.
+     * @param children       The resolved children.
+     * @param _props         The original renderable props (unused by default).
+     * @returns              A `[component, props, children]` tuple, or `undefined` to keep inputs.
+     */
     protected _onRender(component: ComponentType | keyof JSX.IntrinsicElements, componentProps: Record<string, unknown>, children: ComponentChildren, _props: RenderableProps<P>): [component: ComponentType | keyof JSX.IntrinsicElements, componentProps: Record<string, unknown>, children: ComponentChildren] | undefined {
         return [component, componentProps, children];
     }