@fusion.dev/helix-headless 0.22.0 → 0.24.0

package/dist/menu/item/menu-item.js

@@ -16,6 +16,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.checked = false;
         this.disabled = false;
         this.download = false;
+        this.exclusive = false;
         this.href = '';
         this.onPage = true;
         this.rel = '';
@@ -24,6 +25,11 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.value = '';
         this.isMenuItem = true;
         this.submenu = false;
+        this.start = false;
+        this.readStart = () => {
+            const slot = this.renderRoot.querySelector('slot[name="start"]');
+            this.start = (slot?.assignedNodes().length ?? 0) > 0;
+        };
         this.readSubmenu = () => {
             const slot = this.renderRoot.querySelector('slot[name="submenu"]');
             this.submenu = (slot?.assignedElements().length ?? 0) > 0;
@@ -50,9 +56,18 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
     get hasSubmenu() {
         return this.submenu;
     }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (this.children === undefined || this.hydrating) {
+            return;
+        }
+        const named = (name) => [...this.children].some((child) => child.slot === name);
+        this.submenu = named('submenu');
+        this.start = named('start');
+    }
     firstUpdated(changed) {
         super.firstUpdated(changed);
-        this.readSubmenu();
+        this.finishHydration();
     }
     focus() {
         this.renderRoot.querySelector('[part="item"]')?.focus();
@@ -81,9 +96,12 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         }
         const submenu = this.hasSubmenu;
         const linked = this.href !== '' && !this.disabled;
-        const role = this.checkable || this.checked ? 'menuitemcheckbox' : 'menuitem';
-        const checkedState = this.checkable || this.checked ? (this.checked ? 'true' : 'false') : nothing;
-        const inside = html `<span part="start"><slot name="start"></slot></span>
+        const ticks = this.checkable || this.checked;
+        const role = ticks ? (this.exclusive ? 'menuitemradio' : 'menuitemcheckbox') : 'menuitem';
+        const checkedState = ticks ? (this.checked ? 'true' : 'false') : nothing;
+        const inside = html `<span part="start" ?data-empty=${!this.start}
+          ><slot name="start" @slotchange=${this.readStart}></slot
+        ></span>
         <slot></slot>
         ${submenu
             ? html `<svg
@@ -104,7 +122,8 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
                 >
                   ${unsafeSVG(check.content)}
                 </svg>`
-                : html `<span part="mark" aria-hidden="true"></span>`}`;
+                :
+                    nothing}`;
         return html `${linked
             ? html `<a
             part="item"
@@ -129,7 +148,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             @click=${this.handleClick}
             @keydown=${this.handleKeydown}
           >${inside}</div>`}
-      <slot name="submenu" @slotchange=${this.readSubmenu}></slot>`;
+      <div hidden><slot name="submenu" @slotchange=${this.readSubmenu}></slot></div>`;
     }
 };
 __decorate([
@@ -144,6 +163,9 @@ __decorate([
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessMenuItem.prototype, "download", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessMenuItem.prototype, "exclusive", void 0);
 __decorate([
     property()
 ], HelixHeadlessMenuItem.prototype, "href", void 0);
@@ -165,6 +187,9 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessMenuItem.prototype, "submenu", void 0);
+__decorate([
+    state()
+], HelixHeadlessMenuItem.prototype, "start", void 0);
 HelixHeadlessMenuItem = __decorate([
     customElement('helix-headless-menu-item')
 ], HelixHeadlessMenuItem);

package/dist/menu/root/menu-root.d.ts

@@ -126,6 +126,29 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected updated(changed: PropertyValues): void;
+    /**
+     * Says whether the page showing reserves a column either side of its labels.
+     *
+     * **A fact no row can answer for itself**, which is why the columns were
+     * unconditional. A row knows about its own start slot and nothing about its
+     * neighbors, so a page where one row has an icon and the rest do not draws two
+     * different left edges for its text. Reserving on every row instead charged
+     * every menu for a column nothing in it was ever going to fill: measured on a
+     * page of two plain rows, the text started 36 pixels into the row, of which 12
+     * was the row's own padding and 24 a leading column and its seam. The same
+     * page now starts at 12, and a page where one row does have a mark still
+     * starts both of its rows at 36.
+     *
+     * **Per page rather than per menu**, because a submenu is a different set of
+     * rows: a page of checkable filters under a page of plain ones reserves on one
+     * and not on the other, and asking the whole tree would hand the plain page
+     * the filters' column. `Notifications` answers the same question for its media
+     * column the same way, and for the same reason.
+     *
+     * Read off the light DOM rather than off the rows, so it does not depend on
+     * which children have upgraded by the time this runs.
+     */
+    private markColumns;
     /**
      * Walks the tree marking which rows are on the page showing.
      *

package/dist/menu/root/menu-root.js

@@ -45,7 +45,11 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
                 this.enter(chosen);
                 return;
             }
-            this.hide();
+            queueMicrotask(() => {
+                if (!event.defaultPrevented) {
+                    this.hide();
+                }
+            });
         };
         this.handleFocusIn = (event) => {
             const item = this.items.find((row) => row.contains(event.target));
@@ -159,10 +163,17 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             }
             this.mark(item, this.drilldown.atRoot);
         }
+        this.markColumns();
+    }
+    markColumns() {
+        const rows = this.drilldown.rows;
+        this.toggleState('start', rows.some((row) => row.querySelector(':scope > [slot="start"]') !== null));
+        this.toggleState('mark', rows.some((row) => row.checkable || row.checked || this.drilldown.hasPage(row)));
     }
     mark(item, onPage) {
+        const page = this.drilldown.page;
         item.onPage = onPage;
-        item.showingSubmenu = item === this.drilldown.page;
+        item.showingSubmenu = page !== null && item.contains(page);
         for (const child of item.children) {
             const nested = child;
             if (nested.isMenuItem === true && child.slot === 'submenu') {

package/dist/notifications/group/notification-group.d.ts

@@ -0,0 +1,129 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import type { HelixHeadlessNotification } from '../notification/notification.js';
+declare const HelixHeadlessNotificationGroup_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
+/**
+ * @summary A named set of notifications, which can be collapsed to the first of
+ * them.
+ *
+ * @description
+ * **What groups with what is the consumer's, and this never guesses.** A feed
+ * can be cut by day, by the thing being talked about, by the person doing the
+ * talking, or by nothing at all, and which of those is right is a question about
+ * the product. So a group is written by hand around the rows that belong
+ * together and told what to call itself, exactly as `FilterField` is told what
+ * its operators are.
+ *
+ * **Collapsed shows the first row and assigns the rest nowhere.** Not `hidden`,
+ * not `inert`, not a stylesheet: the slot is assigned imperatively, so a
+ * collapsed group's later rows are absent from the layout and from the
+ * accessibility tree with no CSS at all, which is what the headless tier claims
+ * for itself. `Notifications` already assigns its list this way and this borrows
+ * the mechanism.
+ *
+ * The count is separate from how many rows are written, because it usually is: a
+ * group saying five with one row under it and a link to the rest is the common
+ * shape, and computing the number from the children would make that unsayable.
+ * Left off, it is the number of rows.
+ *
+ * @since 0.24.0
+ * @status experimental
+ * @category feedback
+ * @aliases NotificationSection, FeedGroup
+ * @documentation https://helix.fusion.dev/components/notifications
+ *
+ * @slot - The notifications in this group.
+ * @slot action - Beside the count, for a link to the rest of them.
+ * @slot label - Replaces the group's name, for a heading that needs a mark in it.
+ *
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the group folds, and cancelable.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the group unfolds. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart action - The trailing region of the header.
+ * @csspart count - How many are in the group.
+ * @csspart header - The label, the count and the action together.
+ * @csspart items - The region holding the notifications.
+ * @csspart label - What the group is called.
+ * @csspart trigger - The control that collapses and expands, where collapsible.
+ */
+export declare class HelixHeadlessNotificationGroup extends HelixHeadlessNotificationGroup_base {
+    /**
+     * Manual, which is what lets a fold remove rows rather than hide them.
+     *
+     * Under automatic assignment every unnamed child lands in the default slot and
+     * the only ways to fold are `hidden`, `inert` or a stylesheet: the first two
+     * leave the rows in the layout or in the tree, and the third puts the state
+     * somewhere a headless consumer has to re-implement. Assigning by hand, a
+     * folded group's later rows are assigned nowhere and render nothing at all.
+     *
+     * `Notifications` takes the same option for a neighboring reason, and its
+     * note records the other half of it: the rows are ordinary children a consumer
+     * writes with no `slot`, and wrapping them any other way means editing their
+     * markup.
+     */
+    static shadowRootOptions: ShadowRootInit;
+    /**
+     * Whether the group can be collapsed to its first row.
+     *
+     * Off by default, because a group is a heading before it is a control: a feed
+     * cut by day wants its days named and rarely wants them folded, and a control
+     * that does nothing anybody asked for is still a tab stop.
+     */
+    collapsible: boolean;
+    /**
+     * How many notifications this group stands for.
+     *
+     * **Not the number of rows, and that is the point.** A group saying five with
+     * one row under it and a link to the rest is the ordinary shape of a feed that
+     * has been trimmed, and deriving this from the children would make it
+     * unsayable. Left off, it is the number of rows.
+     */
+    count?: number;
+    /**
+     * What the group is called: a day, a subject, a person.
+     *
+     * The slot's fallback rather than its replacement, so a consumer who wants a
+     * mark beside the name slots `label` and this goes unused.
+     */
+    label: string;
+    /**
+     * What this is, for the feed above it to recognize without importing it.
+     *
+     * The same seam `Notification` uses: a root reads a child's markers rather
+     * than its constructor, so the two tiers never have to agree about which class
+     * a consumer happened to instantiate.
+     */
+    readonly isNotificationGroup = true;
+    /** The notifications written into this group, in the order they were given. */
+    get items(): HelixHeadlessNotification[];
+    /** How many the group says it stands for, which is the count or the rows. */
+    get total(): number;
+    protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Puts the rows the group is showing into the slot, and the rest nowhere.
+     *
+     * **Assignment rather than hiding, which is what makes this work with no
+     * stylesheet.** A row that is not assigned to a slot renders nothing at all:
+     * it is out of the layout, out of the tab order and out of the accessibility
+     * tree, in both tiers, without a rule anywhere. `hidden` would do the first
+     * three and `inert` only the last two, and either would put the collapse in a
+     * place a headless consumer has to re-implement.
+     *
+     * Collapsed keeps the first row rather than none, because a group folded to
+     * nothing is a heading with a number after it and no reason to believe there
+     * is anything behind it. The one row is the evidence.
+     */
+    private assign;
+    private readonly handleToggle;
+    /** How many rows the collapse is hiding, for the control to say so. */
+    private get folded();
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-notification-group': HelixHeadlessNotificationGroup;
+    }
+}
+export {};

package/dist/notifications/group/notification-group.js

@@ -0,0 +1,106 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement, hostAria, MixinControllerOpen } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+const TRIGGER_ID = 'trigger';
+const ITEMS_ID = 'items';
+let HelixHeadlessNotificationGroup = class HelixHeadlessNotificationGroup extends MixinControllerOpen(HelixElement) {
+    constructor() {
+        super(...arguments);
+        this.collapsible = false;
+        this.label = '';
+        this.isNotificationGroup = true;
+        this.handleToggle = () => {
+            this.toggleOpen();
+        };
+    }
+    static { this.shadowRootOptions = {
+        ...HelixElement.shadowRootOptions,
+        slotAssignment: 'manual',
+    }; }
+    get items() {
+        return this.knownChildren.filter((child) => child.isNotification === true);
+    }
+    get total() {
+        return this.count ?? this.items.length;
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, this.label === '' ? { role: 'group' } : { label: this.label, role: 'group' });
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.assign();
+    }
+    assign() {
+        const slot = this.renderRoot?.querySelector?.('slot:not([name])');
+        if (!slot?.assign) {
+            return;
+        }
+        const items = this.items;
+        const showing = this.collapsible && !this.open ? items.slice(0, 1) : items;
+        if (this.assignsByName) {
+            for (const item of items) {
+                this.route(item, showing.includes(item) ? undefined : 'folded');
+            }
+            return;
+        }
+        slot.assign(...showing);
+        const action = this.renderRoot?.querySelector?.('slot[name="action"]');
+        action?.assign?.(...[...this.children].filter((child) => child.getAttribute('slot') === 'action'));
+        const label = this.renderRoot?.querySelector?.('slot[name="label"]');
+        label?.assign?.(...[...this.children].filter((child) => child.getAttribute('slot') === 'label'));
+    }
+    get folded() {
+        return Math.max(this.items.length - 1, 0);
+    }
+    render() {
+        const collapsed = this.collapsible && !this.open;
+        return html `<div part="header">
+        ${this.collapsible
+            ? html `<button
+                id=${TRIGGER_ID}
+                aria-controls=${ITEMS_ID}
+                aria-expanded=${this.open ? 'true' : 'false'}
+                part="trigger"
+                type="button"
+                @click=${this.handleToggle}
+              >
+                <span part="label"><slot name="label">${this.label}</slot></span>
+                <span part="count">${this.total}</span>
+              </button>`
+            : html `<span part="label"><slot name="label">${this.label}</slot></span>
+                <span part="count">${this.total}</span>`}
+        <span part="action"><slot name="action"></slot></span>
+      </div>
+      <div
+        id=${ITEMS_ID}
+        part="items"
+        aria-label=${collapsed && this.folded > 0 ? `${this.folded} more` : nothing}
+      >
+        <slot></slot>
+      </div>`;
+    }
+};
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessNotificationGroup.prototype, "collapsible", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessNotificationGroup.prototype, "count", void 0);
+__decorate([
+    property()
+], HelixHeadlessNotificationGroup.prototype, "label", void 0);
+HelixHeadlessNotificationGroup = __decorate([
+    customElement('helix-headless-notification-group')
+], HelixHeadlessNotificationGroup);
+export { HelixHeadlessNotificationGroup };

package/dist/notifications/index.d.ts

@@ -1,2 +1,3 @@
+export { HelixHeadlessNotificationGroup } from './group/notification-group.js';
 export { HelixHeadlessNotification } from './notification/notification.js';
 export { HelixHeadlessNotifications } from './root/notifications-root.js';

package/dist/notifications/index.js

@@ -1,2 +1,3 @@
+export { HelixHeadlessNotificationGroup } from './group/notification-group.js';
 export { HelixHeadlessNotification } from './notification/notification.js';
 export { HelixHeadlessNotifications } from './root/notifications-root.js';

package/dist/notifications/notification/notification.d.ts

@@ -36,10 +36,14 @@ import '../../format-date/index.js';
  * @documentation https://helix.fusion.dev/components/notifications
  *
  * @slot - What happened, in the consumer's own markup.
- * @slot actions - What a reader can do about it.
+ * @slot actions - What a reader can do about it, under the words it is about. Drawn always
+ * rather than on hover, because an action is the point of the row and not chrome around it.
  * @slot caption - A second line qualifying it, quieter than the first. A bare
  * slot rather than a box, so an item without one pays nothing for it; style it
  * through `::slotted()`.
+ * @slot detail - A block belonging to the row rather than a line about it: a quoted
+ * comment, a status moving from one value to another, a preview. Unlike `caption` nothing
+ * here sets a size or an ink, because whatever fills it usually brings its own.
  * @slot media - An avatar or icon identifying who or what it came from.
  *
  * @event {HelixDismissEvent} helix-dismiss - Fired when a reader asks to remove it, and cancelable.
@@ -121,14 +125,30 @@ export declare class HelixHeadlessNotification extends HelixElement {
     /**
      * Says whether there is anything for the time to make way for.
      *
-     * The trailing column holds the time and the controls in one place and shows
+     * The trailing column holds the time and the dismiss in one place and shows
      * one of them, so a row with nothing to do about it would hide its timestamp
-     * on hover and put nothing there. `dismissible` this element knows on the
-     * server; whether a consumer filled the actions slot it can only find out from
-     * a DOM, so this runs after the render and the resting answer, no controls, is
-     * the one the server writes.
+     * on hover and put nothing there.
+     *
+     * **`dismissible` alone, where this once also counted a filled actions slot.**
+     * An action is not chrome. A row offering "Respond" is a row whose whole point
+     * is that button, and one nobody sees until a pointer arrives is one most
+     * readers never find: on a coarse pointer it was drawn and on a desktop it was
+     * not, so the two disagreed about whether the row had a button at all. Actions
+     * now sit in the body under the words they are about, and the swap is left to
+     * the one control that really is chrome.
+     *
+     * This element knows `dismissible` on the server, so unlike the answer it
+     * replaces this one needs no DOM and is right from the first render.
      */
     private markControls;
+    /**
+     * Says whether a consumer put anything in the actions slot.
+     *
+     * Only so the stylesheet can space them from the words above: a row with no
+     * actions pays nothing for the room they would have taken. Answered from a
+     * DOM, so the resting answer is the one the server writes.
+     */
+    private markActions;
     /**
      * The control that removes the item, with the mark a consumer can replace.
      *
@@ -148,13 +168,19 @@ export declare class HelixHeadlessNotification extends HelixElement {
      * on its own viewBox, so it lands where the box says and takes the icon step
      * the row is already set in.
      *
-     * **A trash and not the `x` the Tag draws, because the two do not mean the
-     * same thing.** A tag's cross takes a token off a field the reader is still
-     * filling in, and putting it back is retyping a word. A notification is the
-     * only copy of something that happened, and this removes it from the feed for
-     * good, so the mark is the one every other interface uses for that and the
-     * ink is `danger`. It is only ever on screen while the row is hovered or
-     * focused, so a feed of twenty is not a column of red.
+     * **A cross, and not the trash this used to draw.** The argument for the trash
+     * was that a notification is the only copy of something that happened, so
+     * removing it is destruction and should be marked as such. That reads the row
+     * as the event. It is not: the deploy still deployed and the build still
+     * failed, and the feed this sits in has `See everything` under it, which says
+     * plainly that the row is a view of a longer list. What dismissing ends is the
+     * notice.
+     *
+     * The component cannot know better than that either. `helix-dismiss` is a
+     * request the consumer answers, so whether anything is destroyed is theirs to
+     * decide, and a default that shouts danger asserts a permanence this element
+     * does not control. `--notifications-dismiss-color` is still there for a
+     * consumer whose control really does destroy something.
      */
     protected renderDismiss(): TemplateResult | typeof nothing;
     /**

package/dist/notifications/notification/notification.js

@@ -5,7 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { customElement, HelixDismissEvent, HelixElement, HelixReadEvent, hostAria, requestChange, slotFilled, } from '@fusion.dev/helix-core';
-import { trash } from '@fusion.dev/helix-icons';
+import { x } from '@fusion.dev/helix-icons';
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
@@ -62,10 +62,14 @@ let HelixHeadlessNotification = class HelixHeadlessNotification extends HelixEle
     updated(changed) {
         super.updated(changed);
         this.markControls();
+        this.markActions();
     }
     markControls() {
+        this.toggleState('controls', this.dismissible);
+    }
+    markActions() {
         const slot = this.renderRoot?.querySelector('slot[name="actions"]');
-        this.toggleState('controls', this.dismissible || slotFilled(slot));
+        this.toggleState('actions', slotFilled(slot));
     }
     renderDismiss() {
         if (!this.dismissible) {
@@ -83,9 +87,9 @@ let HelixHeadlessNotification = class HelixHeadlessNotification extends HelixEle
           data-glyph
           fill="currentColor"
           part="dismiss-mark"
-          viewBox=${trash.viewBox}
+          viewBox=${x.viewBox}
         >
-          ${unsafeSVG(trash.content)}
+          ${unsafeSVG(x.content)}
         </svg>
       </slot>
     </button>`;
@@ -105,13 +109,12 @@ let HelixHeadlessNotification = class HelixHeadlessNotification extends HelixEle
       <div part="body">
         <div part="label"><slot></slot></div>
         <slot name="caption"></slot>
+        <slot name="detail"></slot>
+        <span part="actions"><slot name="actions" @slotchange=${this.handleActions}></slot></span>
       </div>
       <div part="trailing">
         ${this.renderTime()}
-        <div part="controls">
-          <span part="actions"><slot name="actions" @slotchange=${this.handleActions}></slot></span>
-          ${this.renderDismiss()}
-        </div>
+        <div part="controls">${this.renderDismiss()}</div>
       </div>
     </div>`;
     }

package/dist/notifications/root/notifications-root.d.ts

@@ -1,5 +1,6 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
+import type { HelixHeadlessNotificationGroup } from '../group/notification-group.js';
 import type { HelixHeadlessNotification } from '../notification/notification.js';
 declare const HelixHeadlessNotifications_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & typeof HelixElement;
 /**
@@ -33,6 +34,7 @@ declare const HelixHeadlessNotifications_base: (new (...args: any[]) => import("
  * @slot footer - Below the list, for a link to everything.
  * @slot header - Above the list, for a title and the mark-all control.
  *
+ * @event {HelixDismissEvent} helix-dismiss - A row asking to be removed, dispatched by the row and heard here because the feed is what a consumer holds. Cancelable: refusing it takes the decision and the row stays.
  * @event {HelixReadEvent} helix-read - Fired by an item, and by this element when everything is marked read. Cancelable.
  *
  * @csspart empty - Shown when there is nothing in the feed.
@@ -79,8 +81,62 @@ export declare class HelixHeadlessNotifications extends HelixHeadlessNotificatio
      * attribute showed a count for an item the reader had just opened.
      */
     get unread(): number;
-    /** The notifications declared as children, in the order they are written. */
+    /**
+     * The notifications in the feed, in the order they are written.
+     *
+     * **Through a group as well as beside one**, because a feed may be cut into
+     * named piles and the rows inside them are still the feed's rows: `unread`
+     * counts them and `markEveryoneRead` moves them. A group that renders only its
+     * first row while folded is still holding the rest, and a badge that dropped
+     * to what was on screen would fall every time somebody folded something.
+     *
+     * One level, not a walk. A group inside a group is not a thing this family
+     * has, and a recursive read here would invent one.
+     *
+     * `?? []` is the server. Lit's element shim carries attributes and not a tree,
+     * so `children` is undefined there, and this getter is reached from `unread`
+     * during the first update.
+     */
     get items(): HelixHeadlessNotification[];
+    /**
+     * What the list slot is given: the rows and the groups, as written.
+     *
+     * Not `items`, which reaches through a group to the rows inside it. Assigning
+     * those would lift them out of the group that is arranging them and hand the
+     * feed a flat list again.
+     */
+    get rows(): Element[];
+    /**
+     * The groups written into the feed, in the order they are written.
+     *
+     * Only the ones that can fold answer to `foldEveryGroup`, but this is every
+     * group: a consumer counting their sections should not have to know which of
+     * them happen to be collapsible.
+     */
+    get groups(): HelixHeadlessNotificationGroup[];
+    /**
+     * Folds every group that can fold, and reports how many actually moved.
+     *
+     * **A command, not a second place the state lives.** A group owns whether it
+     * is folded; this asks all of them at once. The alternative, a property on the
+     * feed that groups read, gives two answers to one question the moment a reader
+     * unfolds one of them, and then neither is wrong and neither is right.
+     *
+     * **Through each group's own request**, so one refusal refuses one group: a
+     * `helix-before-open` or `helix-before-close` prevented on a group leaves that
+     * group where it was and the rest still move. `markEveryoneRead` takes the
+     * same route for the same reason.
+     *
+     * **And unlike that one, this announces nothing of its own.** Marking read is
+     * usually a round trip, so a feed-level `helix-read` lets a consumer refuse the
+     * whole operation before any of it starts. Folding is not: it is where the
+     * reader is looking, it reaches no server, and an event nobody can meaningfully
+     * refuse is a channel that exists to be ignored.
+     *
+     * A group that is not `collapsible` is left alone rather than counted as
+     * refusing, because it was never asked.
+     */
+    foldEveryGroup(folded?: boolean): number;
     /**
      * Marks every unread item read, and reports how many actually moved.
      *