Implement sections for gallery sidebar

build-scripts/gulp/gallery.js

@@ -103,12 +103,29 @@ gulp.task("gather-gallery-pages", async function gatherPages() {
 
     if (!toProcess) {
       console.error("Unknown category", group.category);
-      if (!group.pages) {
+      if (!group.subsections && !group.pages) {
         group.pages = [];
       }
       continue;
     }
 
+    if (group.subsections) {
+      // Listed pages keep their per-subsection order.
+      for (const subsection of group.subsections) {
+        for (const page of subsection.pages) {
+          if (!toProcess.delete(page)) {
+            console.error("Found unreferenced demo", page);
+          }
+        }
+      }
+      // Any remaining pages land in a trailing "Other" subsection.
+      const leftover = Array.from(toProcess).sort();
+      if (leftover.length) {
+        group.subsections.push({ header: "Other", pages: leftover });
+      }
+      continue;
+    }
+
     // Any pre-defined groups will not be sorted.
     if (group.pages) {
       for (const page of group.pages) {

gallery/AGENTS.md

@@ -62,6 +62,17 @@ Use `sidebar.js` when a page needs a visible section, section header, or determi
 - New categories without a sidebar entry are appended by the generator with their category name as the header.
 - If a listed page does not exist, the generator logs an error during `gather-gallery-pages`.
 
+### Subsections
+
+A section can group its pages under named subsections instead of one flat list. Use this for large categories where related pages should sit together.
+
+- `subsections` is an array of `{ header, pages }`. It is mutually exclusive with a flat `pages` array on the same group.
+- Each subsection `header` is a non-collapsible label rendered inside the section's expansion panel; the section stays the only collapsible level.
+- Listed pages keep their per-subsection order.
+- Any pages found in the category but not listed in a subsection are collected into a generated `Other` subsection, appended alphabetically. The `Other` subsection is omitted when there are no leftovers.
+- A listed page that does not exist still logs an error during `gather-gallery-pages`.
+- Use sentence case for subsection headers and follow the content standards below.
+
 ## Markdown Pages
 
 Use markdown pages for explanations, design guidance, API notes, and copy standards.

gallery/sidebar.js

@@ -10,6 +10,10 @@ import {
   mdiViewDashboard,
 } from "@mdi/js";
 
+// A group may list its pages flat in `pages`, or group them under named
+// `subsections`. The two are mutually exclusive. Listed pages keep their order;
+// any pages found in the category but not listed are appended alphabetically
+// (to a generated "Other" subsection when the group uses subsections).
 export default [
   {
     // This section has no header and so all page links are shown directly in the sidebar
@@ -27,31 +31,162 @@ export default [
     category: "components",
     icon: mdiPuzzle,
     header: "Components",
+    subsections: [
+      {
+        header: "Form and selectors",
+        pages: [
+          "ha-form",
+          "ha-selector",
+          "ha-select-box",
+          "ha-input",
+          "ha-textarea",
+        ],
+      },
+      {
+        header: "Controls and sliders",
+        pages: [
+          "ha-button",
+          "ha-control-button",
+          "ha-progress-button",
+          "ha-switch",
+          "ha-control-switch",
+          "ha-slider",
+          "ha-control-slider",
+          "ha-control-circular-slider",
+          "ha-control-number-buttons",
+          "ha-control-select",
+          "ha-control-select-menu",
+          "ha-hs-color-picker",
+        ],
+      },
+      {
+        header: "Overlays",
+        pages: [
+          "ha-dialog",
+          "ha-dialogs",
+          "ha-adaptive-dialog",
+          "ha-adaptive-popover",
+          "ha-dropdown",
+          "ha-tooltip",
+        ],
+      },
+      {
+        header: "Lists and disclosure",
+        pages: ["ha-list", "ha-expansion-panel", "ha-faded"],
+      },
+      {
+        header: "Feedback and status",
+        pages: ["ha-alert", "ha-spinner", "ha-tip", "ha-bar", "ha-gauge"],
+      },
+      {
+        header: "Labels and text",
+        pages: ["ha-badge", "ha-label-badge", "ha-chips", "ha-marquee-text"],
+      },
+    ],
   },
   {
     category: "lovelace",
     icon: mdiViewDashboard,
     // Label for in the sidebar
     header: "Dashboards",
-    // Specify order of pages. Any pages in the category folder but not listed here will
-    // automatically be added after the pages listed here.
-    pages: ["introduction"],
+    subsections: [
+      {
+        header: "Introduction",
+        pages: ["introduction"],
+      },
+      {
+        header: "Entity cards",
+        pages: [
+          "entities-card",
+          "entity-button-card",
+          "entity-filter-card",
+          "glance-card",
+          "tile-card",
+          "area-card",
+        ],
+      },
+      {
+        header: "Picture cards",
+        pages: [
+          "picture-card",
+          "picture-elements-card",
+          "picture-entity-card",
+          "picture-glance-card",
+        ],
+      },
+      {
+        header: "Domain cards",
+        pages: [
+          "light-card",
+          "thermostat-card",
+          "alarm-panel-card",
+          "gauge-card",
+          "plant-card",
+          "map-card",
+          "media-control-card",
+          "media-player-row",
+        ],
+      },
+      {
+        header: "Layout and utility",
+        pages: [
+          "grid-and-stack-card",
+          "conditional-card",
+          "iframe-card",
+          "markdown-card",
+          "todo-list-card",
+        ],
+      },
+    ],
   },
   {
     category: "more-info",
     icon: mdiInformationOutline,
     header: "More Info dialogs",
+    subsections: [
+      {
+        header: "Climate and water",
+        pages: ["climate", "humidifier", "water-heater", "fan"],
+      },
+      {
+        header: "Covers and access",
+        pages: ["cover", "lock", "lawn-mower", "vacuum"],
+      },
+      {
+        header: "Lighting",
+        pages: ["light", "scene"],
+      },
+      {
+        header: "Media",
+        pages: ["media-player"],
+      },
+      {
+        header: "Inputs and values",
+        pages: ["input-number", "input-text", "number", "timer"],
+      },
+      {
+        header: "System",
+        pages: ["update"],
+      },
+    ],
   },
   {
     category: "automation",
     icon: mdiRobot,
     header: "Automation",
-    pages: [
-      "editor-trigger",
-      "editor-condition",
-      "editor-action",
-      "trace",
-      "trace-timeline",
+    subsections: [
+      {
+        header: "Editors",
+        pages: ["editor-trigger", "editor-condition", "editor-action"],
+      },
+      {
+        header: "Descriptions",
+        pages: ["describe-trigger", "describe-condition", "describe-action"],
+      },
+      {
+        header: "Traces",
+        pages: ["trace", "trace-timeline"],
+      },
     ],
   },
   {
@@ -64,6 +199,26 @@ export default [
     category: "date-time",
     icon: mdiCalendarClock,
     header: "Date and Time",
+    subsections: [
+      {
+        header: "Date",
+        pages: ["date"],
+      },
+      {
+        header: "Time",
+        pages: ["time", "time-seconds", "time-weekday"],
+      },
+      {
+        header: "Combined",
+        pages: [
+          "date-time",
+          "date-time-numeric",
+          "date-time-seconds",
+          "date-time-short",
+          "date-time-short-year",
+        ],
+      },
+    ],
   },
   {
     category: "misc",

gallery/src/ha-gallery.ts

@@ -40,15 +40,26 @@ interface GalleryPage {
   demo?: unknown;
 }
 
+interface GallerySidebarSubsection {
+  header: string;
+  pages: string[];
+}
+
 interface GallerySidebarGroup {
   category: string;
   header?: string;
   icon?: string;
-  pages: string[];
+  pages?: string[];
+  subsections?: GallerySidebarSubsection[];
 }
 
+const groupPages = (group: GallerySidebarGroup): string[] =>
+  group.subsections
+    ? group.subsections.flatMap((subsection) => subsection.pages)
+    : (group.pages ?? []);
+
 const GALLERY_SIDEBAR = SIDEBAR as GallerySidebarGroup[];
-const DEFAULT_PAGE = `${GALLERY_SIDEBAR[0].category}/${GALLERY_SIDEBAR[0].pages[0]}`;
+const DEFAULT_PAGE = `${GALLERY_SIDEBAR[0].category}/${groupPages(GALLERY_SIDEBAR[0])[0]}`;
 
 const mql = matchMedia("(prefers-color-scheme: dark)");
 
@@ -284,26 +295,15 @@ class HaGallery extends LitElement {
     const sidebar: unknown[] = [];
 
     for (const group of GALLERY_SIDEBAR) {
-      const links: unknown[] = [];
-      const expanded = group.pages.some(
+      const expanded = groupPages(group).some(
         (page) => this._page === `${group.category}/${page}`
       );
 
-      for (const page of group.pages) {
-        const key = `${group.category}/${page}`;
-        if (!(key in PAGES)) {
-          console.error("Undefined page referenced in sidebar.js:", key);
-          continue;
-        }
-        links.push(
-          this._renderPageLink(
-            key,
-            PAGES[key].metadata.title || page,
-            group.header ? undefined : "main-navigation",
-            group.header ? undefined : group.icon
+      const content = group.subsections
+        ? group.subsections.map((subsection) =>
+            this._renderSidebarSubsection(group, subsection)
           )
-        );
-      }
+        : this._renderPageLinks(group, group.pages ?? []);
 
       sidebar.push(
         group.header
@@ -321,16 +321,46 @@ class HaGallery extends LitElement {
                       .path=${group.icon}
                     ></ha-svg-icon>`
                   : nothing}
-                ${links}
+                ${content}
               </ha-expansion-panel>
             `
-          : links
+          : content
       );
     }
 
     return sidebar;
   }
 
+  private _renderSidebarSubsection(
+    group: GallerySidebarGroup,
+    subsection: GallerySidebarSubsection
+  ) {
+    return html`
+      <div class="gallery-sidebar-subheader">${subsection.header}</div>
+      ${this._renderPageLinks(group, subsection.pages)}
+    `;
+  }
+
+  private _renderPageLinks(group: GallerySidebarGroup, pages: string[]) {
+    const links: unknown[] = [];
+    for (const page of pages) {
+      const key = `${group.category}/${page}`;
+      if (!(key in PAGES)) {
+        console.error("Undefined page referenced in sidebar.js:", key);
+        continue;
+      }
+      links.push(
+        this._renderPageLink(
+          key,
+          PAGES[key].metadata.title || page,
+          group.header ? undefined : "main-navigation",
+          group.header ? undefined : group.icon
+        )
+      );
+    }
+    return links;
+  }
+
   private _renderPageLink(
     page: string,
     title: string,
@@ -585,6 +615,16 @@ class HaGallery extends LitElement {
         width: var(--ha-sidebar-expanded-section-item-width, 248px);
       }
 
+      .gallery-sidebar-subheader {
+        margin: var(--ha-space-2) var(--ha-space-4) var(--ha-space-1);
+        color: var(--secondary-text-color);
+        font-size: var(--ha-font-size-s);
+        font-weight: var(--ha-font-weight-medium);
+        line-height: var(--ha-line-height-condensed);
+        text-transform: uppercase;
+        letter-spacing: 0.04em;
+      }
+
       .gallery-sidebar-icon,
       .gallery-nav-item ha-svg-icon[slot="start"] {
         color: var(--sidebar-icon-color);