selective-ui 1.2.4 → 1.2.6

package/src/ts/views/group-view.ts

@@ -1,41 +1,106 @@
-
 import { View } from "../core/base/view";
 import { Libs } from "../utils/libs";
 import type { GroupViewTags, GroupViewResult } from "../types/views/view.group.type";
 
 /**
- * View implementation responsible for rendering and managing
- * a grouped collection of selectable items.
+ * GroupView
+ *
+ * View implementation for rendering grouped collections of selectable items.
+ *
+ * ### Responsibility
+ * - Renders a semantic group structure: header (label) + items container.
+ * - Manages group-level visibility based on child item state.
+ * - Supports collapse/expand interactions with accessibility annotations.
+ * - Provides typed access to DOM structure via {@link view}.
+ *
+ * ### Structure
+ * ```
+ * GroupView (root)
+ *   ├─ GroupHeader (label, role="presentation")
+ *   └─ GroupItems (container, role="group")
+ * ```
+ *
+ * ### Lifecycle (View-based FSM)
+ * - **Construction**: Accepts parent container, transitions `NEW → INITIALIZED`.
+ * - **{@link mount}**: Creates DOM structure, appends to parent, transitions `INITIALIZED → MOUNTED`.
+ * - **{@link update}**: Refreshes group header label, transitions `MOUNTED → UPDATED → MOUNTED`.
+ * - **{@link destroy}**: Removes DOM nodes, transitions to `DESTROYED`.
+ *
+ * ### Visibility semantics
+ * - {@link updateVisibility} hides the entire group when all child items are hidden.
+ * - Checks for `"hide"` class on children (does not inspect `display` or `visibility` styles).
  *
- * The group consists of:
- * - A header element (label)
- * - A container holding child item views
+ * ### Accessibility
+ * - Root container: `role="group"`, `aria-labelledby` points to header.
+ * - Header: `role="presentation"`, unique ID for labeling.
+ * - Items container: `role="group"` (nested group).
+ * - Collapse state: `aria-expanded` attribute on header (managed by {@link setCollapsed}).
+ *
+ * ### DOM side effects
+ * - {@link mount} creates and appends DOM structure.
+ * - {@link updateLabel} mutates header `textContent`.
+ * - {@link setCollapsed} toggles CSS classes and ARIA attributes.
+ * - {@link updateVisibility} toggles `"hide"` class on root.
+ *
+ * ### No-op / Idempotency
+ * - {@link updateLabel}, {@link updateVisibility}, {@link setCollapsed} are no-ops if not mounted (early return guards).
+ * - Safe to call multiple times without side effects beyond DOM state updates.
  *
  * @extends View<GroupViewTags>
+ * @template GroupViewTags - Type descriptor for the group's DOM structure.
+ * @see {@link GroupViewResult}
+ * @see {@link View}
  */
 export class GroupView extends View<GroupViewTags> {
 
     /**
      * Strongly-typed reference to the mounted group view structure.
-     * Will be null until the view has been mounted.
+     *
+     * Structure:
+     * - **view**: Root container element.
+     * - **tags**: Named references to header and items container.
+     *
+     * Lifecycle:
+     * - `null` until {@link mount} completes.
+     * - Cleared during {@link destroy}.
+     *
+     * @public
      */
     public view: GroupViewResult | null = null;
 
     /**
      * Mounts the group view into the DOM.
      *
-     * Creates the group container, header, and items wrapper,
-     * applies required ARIA attributes, and appends the root
-     * element to the parent container.
+     * Creation flow:
+     * 1. Generates unique group ID (7-character random string).
+     * 2. Creates DOM structure via {@link Libs.mountNode}:
+     *    - Root: `<div role="group" aria-labelledby="seui-{id}-header">`
+     *    - Header: `<div role="presentation" id="seui-{id}-header">`
+     *    - Items: `<div role="group">` (nested group for child items)
+     * 3. Appends root to {@link parent} container.
+     * 4. Transitions `INITIALIZED → MOUNTED` via `super.mount()`.
+     *
+     * Accessibility setup:
+     * - Root `aria-labelledby` associates group with header text.
+     * - Header `role="presentation"` hides it from navigation (purely visual label).
+     * - Items container `role="group"` creates semantic boundary for children.
+     *
+     * Postcondition:
+     * - {@link view} is populated with typed DOM references.
+     *
+     * @public
+     * @returns {void}
+     * @override
+     * @throws {Error} If {@link parent} is null (should never occur due to base `View` constructor).
      */
     public override mount(): void {
         const group_id = Libs.randomString(7);
 
-        this.view = Libs.mountView<GroupViewTags>({
+        this.view = Libs.mountNode<GroupViewResult>({
             GroupView: {
                 tag: {
                     node: "div",
-                    classList: ["selective-ui-group"],
+                    classList: ["seui-group"],
                     role: "group",
                     ariaLabelledby: `seui-${group_id}-header`,
                     id: `seui-${group_id}-group`,
@@ -44,7 +109,7 @@ export class GroupView extends View<GroupViewTags> {
                     GroupHeader: {
                         tag: {
                             node: "div",
-                            classList: ["selective-ui-group-header"],
+                            classList: ["seui-group-header"],
                             role: "presentation",
                             id: `seui-${group_id}-header`,
                         },
@@ -52,13 +117,13 @@ export class GroupView extends View<GroupViewTags> {
                     GroupItems: {
                         tag: {
                             node: "div",
-                            classList: ["selective-ui-group-items"],
+                            classList: ["seui-group-items"],
                             role: "group",
                         },
                     },
                 },
             },
-        }) as GroupViewResult;
+        });
 
         // Parent is guaranteed to exist by the base View constructor.
         this.parent!.appendChild(this.view.view);
@@ -67,10 +132,19 @@ export class GroupView extends View<GroupViewTags> {
     }
 
     /**
-     * Called when the view needs to be updated.
+     * Updates the group view in response to state changes.
+     *
+     * Behavior:
+     * - Refreshes the group header label via {@link updateLabel}.
+     * - Transitions `MOUNTED → UPDATED → MOUNTED` via `super.update()`.
      *
-     * Currently performs a lightweight refresh by updating
-     * the group header label.
+     * Notes:
+     * - Currently performs only label refresh; extend for additional update logic.
+     * - Does **not** update visibility or collapse state automatically.
+     *
+     * @public
+     * @returns {void}
+     * @override
      */
     public override update(): void {
         this.updateLabel();
@@ -80,8 +154,18 @@ export class GroupView extends View<GroupViewTags> {
     /**
      * Updates the text content of the group header.
      *
-     * @param label - The new label to display.
-     *                If null, the existing label is preserved.
+     * Behavior:
+     * - No-op if not mounted ({@link view} is `null`).
+     * - If `label` is `null`, preserves existing header text.
+     * - Otherwise, replaces header `textContent` with new label.
+     *
+     * Notes:
+     * - Does **not** escape HTML (uses `textContent`, not `innerHTML`).
+     * - Safe to call multiple times with same value (idempotent).
+     *
+     * @public
+     * @param {string | null} [label=null] - New label to display; `null` preserves current label.
+     * @returns {void}
      */
     public updateLabel(label: string | null = null): void {
         if (!this.view) return;
@@ -93,11 +177,15 @@ export class GroupView extends View<GroupViewTags> {
     }
 
     /**
-     * Returns the container element that holds all item/option views
-     * belonging to this group.
+     * Returns the container element for child item views.
      *
-     * @returns The HTMLDivElement used as the items container.
-     * @throws {Error} If the view has not been mounted yet.
+     * Usage:
+     * - Caller appends `OptionView` or other child views to this container.
+     * - Container provides semantic grouping (`role="group"`).
+     *
+     * @public
+     * @returns {HTMLDivElement} The items container element.
+     * @throws {Error} If the view has not been mounted yet ({@link view} is `null`).
      */
     public getItemsContainer(): HTMLDivElement {
         if (!this.view) {
@@ -107,10 +195,22 @@ export class GroupView extends View<GroupViewTags> {
     }
 
     /**
-     * Updates the visibility of the group based on its children.
+     * Updates the group's visibility based on child item state.
+     *
+     * Visibility rules:
+     * - Iterates through direct children of the items container.
+     * - Counts children **without** the `"hide"` CSS class.
+     * - Toggles `"hide"` class on root container:
+     *   - **Added** if all children are hidden (zero visible).
+     *   - **Removed** if any child is visible.
+     *
+     * Notes:
+     * - No-op if not mounted ({@link view} is `null`).
+     * - Only checks for `"hide"` class; does **not** inspect `display` or `visibility` styles.
+     * - Safe to call repeatedly (idempotent based on current child state).
      *
-     * If all child items are hidden, the entire group
-     * will be hidden as well.
+     * @public
+     * @returns {void}
      */
     public updateVisibility(): void {
         if (!this.view) return;
@@ -126,11 +226,22 @@ export class GroupView extends View<GroupViewTags> {
     /**
      * Sets the collapsed/expanded state of the group.
      *
-     * This updates both:
-     * - Visual state (CSS classes)
-     * - Accessibility state (ARIA attributes)
+     * State updates:
+     * - **CSS**: Toggles `"collapsed"` class on root container.
+     * - **ARIA**: Sets `aria-expanded` attribute on header (`"true"` or `"false"`).
+     *
+     * Visual effects:
+     * - CSS class typically controls item container visibility (via stylesheet).
+     * - ARIA attribute communicates state to assistive technologies.
+     *
+     * Notes:
+     * - No-op if not mounted ({@link view} is `null`).
+     * - Does **not** animate or transition; relies on CSS for presentation.
+     * - Safe to call with same value repeatedly (idempotent).
      *
-     * @param collapsed - True to collapse the group, false to expand it.
+     * @public
+     * @param {boolean} collapsed - `true` to collapse the group; `false` to expand.
+     * @returns {void}
      */
     public setCollapsed(collapsed: boolean): void {
         if (!this.view) return;