@ixfx/components 0.17.1 → 0.18.1

package/bundle/index.d.ts

@@ -303,7 +303,11 @@ type CommandOptions = Readonly<{
 }>;
 type Command<TState = unknown> = Readonly<{
   id: CommandId;
-  label: string;
+  /**
+   * User-facing label. A plain string, or a function of the state for labels that
+   * vary by context. Resolve with `CommandRegistry.getLabel`.
+   */
+  label: string | ((state: TState) => string);
   icon?: string;
   description: string;
   enabledWhen?: (state: TState) => boolean;
@@ -345,6 +349,8 @@ type KeyEventHandler = (commandId: CommandId, modifiers: Modifiers, context: Inp
 declare class CommandRegistry<TState = unknown> {
   private commands;
   private invokeListeners;
+  private labelOverrides;
+  private labelListeners;
   private options;
   /**
    * Creates, with options.
@@ -363,6 +369,28 @@ declare class CommandRegistry<TState = unknown> {
    * @returns _true_ if a command was removed
    */
   unregister(id: CommandId): boolean;
+  /**
+   * Overrides a command's label until cleared, without re-registering it.
+   * Listeners added with `addOnLabelChangeHandler` are notified if the override changed.
+   * @param id - Command ID
+   * @param text - New label, or _undefined_ to clear the override and use the command's own label
+   * @returns _false_ if the command is not registered
+   */
+  setLabel(id: CommandId, text: string | undefined): boolean;
+  /**
+   * Resolves a command's current label: a `setLabel` override if present,
+   * otherwise the command's label (calling it with `state` if it is a function).
+   * @param id - Command ID
+   * @param state - Current application state, passed to a function label
+   * @returns The label, or _undefined_ if the command is not registered
+   */
+  getLabel(id: CommandId, state: TState): string | undefined;
+  /**
+   * Adds a function to call when a label is changed via `setLabel`.
+   * @param handler - Receives the command id and new override (_undefined_ if cleared)
+   * @returns Function to unsubscribe the handler
+   */
+  addOnLabelChangeHandler(handler: (id: CommandId, label: string | undefined) => void): () => void;
   /**
    * Runs a command by its id.
    *
@@ -822,7 +850,10 @@ declare global {
   }
 }
 export type SplitButtonMode = `default` | `switcher`;
+/** Fills the popover (panel or target) just before it is shown. */
+export type PopoverProvider = (popover: HTMLElement) => void | Promise<void>;
 export declare class SplitButton extends ButtonElement {
+  #private;
   registry?: CommandRegistry<unknown>;
   keyboardManager?: KeyboardManager;
   mode: SplitButtonMode;
@@ -831,7 +862,24 @@ export declare class SplitButton extends ButtonElement {
   itemsProvider?: ItemsProvider;
   /** Directly set popup items. Ignored when itemsProvider is also set. */
   items?: PopupItem[];
-  private _menuTrigger;
+  /**
+   * Id of a `popover` element elsewhere in the same tree (or shadow root) that the
+   * caret toggles instead of opening the menu, like the native `popovertarget`.
+   * The caret is passed as the popover's `source`, so it anchors implicitly.
+   */
+  popoverTarget: string;
+  /**
+   * Builds popover content just in time. Called each time the popover is about to be
+   * shown (awaited if it returns a promise) with the popover element — the built-in
+   * panel, or the `popover-target` element — so it can fill it in before it appears.
+   * Setting this (without `popover-target`) makes the caret open the built-in panel.
+   */
+  popoverProvider?: PopoverProvider;
+  private _menuTrigger?;
+  private _popoverPanel?;
+  private _caretEl?;
+  private _hasPopoverSlot;
+  private _popoverOpen;
   private _selectedCommand;
   private _selectedLabel;
   private _selectedIcon;
@@ -839,8 +887,6 @@ export declare class SplitButton extends ButtonElement {
   private _dynamicItems;
   private _loadingItems;
   private _menuHasItems;
-  disconnectedCallback(): void;
-  firstUpdated(): void;
   updated(changedProperties: Map<string, unknown>): void;
   private _applyItems;
   /** In switcher mode, programmatically select the active command. Returns false if not found. */
@@ -849,16 +895,27 @@ export declare class SplitButton extends ButtonElement {
   invoke(): boolean;
   /** True when there is (or will be) popup content. Used to dim the caret visually. */
   private get _caretHasContent();
+  /** The caret toggles a popover (slotted content, `popover-target` or `popoverProvider`) rather than the menu. */
+  private get _popoverMode();
+  private _resolvePopover;
+  private _onPopoverSlotChange;
+  private _onPopoverToggle;
+  /** Show the popover (building its content first). `toggle`: hide it instead when already open. */
+  private _showPopover;
   private _onDefaultMenuSlotChange;
   private _onSwitcherSlotChange;
   private _applySwitcherItems;
   private _handleSwitcherMenuCommand;
   private _handleSwitcherPrimaryClick;
   private _handleCaretClick;
+  private _openOverlay;
   private _handlePrimaryKeyDown;
   private _handleCaretKeyDown;
+  private _handleCaretPointerDown;
   protected render(): import("lit").TemplateResult<1>;
   private _renderCaret;
+  /** The caret with its overlay: the popover panel in popover mode, otherwise the menu trigger + menu. */
+  private _renderCaretArea;
   private _renderLoadingOrItems;
   private _renderDefault;
   private _renderSwitcher;
@@ -3489,6 +3546,12 @@ interface ListDragPreview {
   readonly canvas?: HTMLCanvasElement;
   readonly dispose?: () => void;
 }
+/**
+ * Writes an application payload onto the drag's `DataTransfer` at `dragstart`.
+ * Every list component exposes this as a public `writeDataTransfer` property;
+ * `ListNativeDragController` invokes it after any built-in payload writer.
+ */
+type ListDragDataTransferWriter<T> = (dataTransfer: DataTransfer, detail: ListNativeDragStartDetail<T>) => void;
 type ListDragPreviewRenderer<T> = (context: ListDragPreviewContext<T>) => ListDragPreview;
 type ListDragPreviewSourceResolver<T> = (entry: ListDragEntry<T>) => CanvasImageSource | undefined;
 interface ListNativeDragStartDetail<T = unknown> {
@@ -4472,8 +4535,20 @@ export interface CrumbNavigationElementEventMap extends TreeComponentEventMap {
 export interface CrumbNavigationElement {
   addEventListener: (<K extends keyof CrumbNavigationElementEventMap>(type: K, listener: (this: CrumbNavigationElement, event: CrumbNavigationElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions) => void) & ((type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions) => void);
 }
+/**
+ * A structured path segment. `label` is the displayed text and may contain any
+ * character, including the display separator. `value` is an optional opaque
+ * identity the host can round-trip (e.g. an id) — reported back via the
+ * `segments` field on `navigate` / `change` events.
+ */
+export type CrumbPathSegment = {
+  label: string;
+  value?: string;
+};
 export type CrumbSegment = {
   label: string;
+  /** Carried onto the matching `CrumbPathSegment` when this sibling is chosen. */
+  value?: string;
   icon?: string;
   isLeaf?: boolean;
 };
@@ -4484,12 +4559,16 @@ export type CrumbNavNavigateDetail = {
   label: string;
   parentPath: string;
   fullPath: string;
+  /** The new structured path (excluding `pathRoot`). Present when the `segments` property is in use. */
+  segments?: CrumbPathSegment[];
 };
 export type CrumbNavNavigateEvent = CustomEvent<CrumbNavNavigateDetail>;
 export type CrumbNavChangeDetail = {
   label: string;
   parentPath: string;
   fullPath: string;
+  /** The new structured path (excluding `pathRoot`). Present when the `segments` property is in use. */
+  segments?: CrumbPathSegment[];
 };
 export type CrumbNavChangeEvent = CustomEvent<CrumbNavChangeDetail>;
 export type CrumbNavExpandDetail = {
@@ -4547,7 +4626,18 @@ export type CrumbDropDetail = {
 export type CrumbDropEvent = CustomEvent<CrumbDropDetail>;
 export declare class CrumbPathElement extends LitElement {
   #private;
+  /**
+   * Text path, split on `separator`. Use `segments` instead when a label may
+   * contain the separator. When `segments` is set it takes precedence and this
+   * property holds the derived display text (labels joined by `separator`).
+   */
   path: string;
+  /**
+   * Structured path (excluding `pathRoot`). Labels may contain any character,
+   * including `separator`. Takes precedence over `path`, which is derived from
+   * it. Set to `undefined` to go back to the text `path`.
+   */
+  segments: CrumbPathSegment[] | undefined;
   separator: string;
   pathRoot: string;
   siblingLookup: CrumbSiblingLookupFn | undefined;
@@ -4579,6 +4669,9 @@ export declare class CrumbPathElement extends LitElement {
   /** Deepest relative-segment path visited, kept so it can be restored via virtual segments. */
   private _hintSegments;
   protected updated(changedProperties: PropertyValues): void;
+  protected willUpdate(changed: PropertyValues): void;
+  /** Structured segments, or the text path parsed into value-less segments. */
+  getSegments(): CrumbPathSegment[];
   setPath(newPath: string): void;
   /** Drop cached dropdown siblings (and leaf detection) so they are looked up again. */
   invalidateSiblings(): void;
@@ -4650,6 +4743,70 @@ declare global {
     'ixfx-data-display': DataDisplayComponent;
   }
 }
+/**
+ * Caller-assigned item tags, shared by every list-like component
+ * (`ixfx-grid-list`, `ixfx-detail-list`, `ixfx-data-grid`, `ixfx-multicol-list`).
+ *
+ * What a tag *means* belongs to the caller. The component only
+ *
+ * 1. exposes it for styling: a `tag-<name>` token in the item's `part`, and
+ *    `data-tags` (space-separated, so `[data-tags~="foo"]` matches);
+ * 2. applies the generic interaction flags declared for it in `tagBehaviour`.
+ *
+ * Tokens are prefixed so a caller tag called `selected` cannot collide with
+ * the built-in state token.
+ */
+/** Generic interaction flags a tag can switch off. Omitted flags keep the default (`true`). */
+type ItemTagBehaviourFlags = {
+  /** `false`: no selection or tickle, no `list-select-intent`; range and select-all skip the item. */
+  selectable?: boolean;
+  /** `false`: keyboard cursor movement skips the item. */
+  focusable?: boolean;
+  /** `false`: no drag starts from the item. */
+  draggable?: boolean;
+  /** `false`: the item is left out of incremental search. */
+  searchable?: boolean;
+};
+/** Behaviour declarations keyed by tag name. */
+type ItemTagBehaviour = Readonly<Record<string, ItemTagBehaviourFlags>>;
+/** Tag assignment by key set: tag name → keys that carry it. Like `partialKeys`, for tags kept apart from the data. */
+type ItemTagKeys = ReadonlyMap<string, ReadonlySet<string>>;
+/** The effective flags for an item: every flag is explicit. */
+type ResolvedItemTagFlags = Required<ItemTagBehaviourFlags>;
+export declare const DEFAULT_ITEM_TAG_FLAGS: ResolvedItemTagFlags;
+/** Prefix of a tag's `part` token. */
+export declare const TAG_PART_PREFIX = "tag-";
+/**
+ * Merge the tags from the per-item hook and from `tagKeys`, de-duplicated,
+ * in first-seen order. Empty and whitespace-containing names are dropped
+ * (they could not be a single `part` token).
+ */
+export declare function collectTags(key: string | undefined, fromHook: readonly string[] | undefined, tagKeys: ItemTagKeys | undefined): readonly string[];
+/** Most restrictive wins: any `false` among the item's tags beats the default and any `true`. */
+export declare function resolveTagFlags(tags: readonly string[], behaviour: ItemTagBehaviour | undefined): ResolvedItemTagFlags;
+/** ` tag-foo tag-bar` — append to a `part` value. Empty string when there are no tags. */
+export declare function tagPartTokens(tags: readonly string[]): string;
+/** Value for `data-tags` (`"foo bar"`), or `undefined` when there are no tags. */
+export declare function tagsAttribute(tags: readonly string[]): string | undefined;
+/** Reflect tags onto an element (element mode / light DOM): `data-tags`, and `tag-*` tokens in `part` it didn't set. */
+export declare function applyTagAttributes(el: Element, tags: readonly string[], basePart?: string): void;
+/** Whether two tag lists are identical (order matters; lists are tiny). */
+export declare function sameTags(a: readonly string[], b: readonly string[]): boolean;
+/** Whether two `tagKeys` maps hold the same tags with the same keys. */
+export declare function sameTagKeys(a: ItemTagKeys | undefined, b: ItemTagKeys | undefined): boolean;
+/**
+ * Per-component holder for the two assignment forms and `tagBehaviour`.
+ * Resolves an item's tags and flags; caches nothing (callers re-render on change).
+ */
+export declare class ItemTagResolver {
+  tagKeys: ItemTagKeys | undefined;
+  behaviour: ItemTagBehaviour | undefined;
+  /** Tags for an item, merging the hook's result with `tagKeys`. */
+  tagsFor(key: string | undefined, fromHook?: readonly string[]): readonly string[];
+  flagsFor(tags: readonly string[]): ResolvedItemTagFlags;
+  /** Convenience: flags for an item straight from its key and hook result. */
+  flagsForItem(key: string | undefined, fromHook?: readonly string[]): ResolvedItemTagFlags;
+}
 /**
  * Shared list viewport-change types.
  *
@@ -5325,6 +5482,8 @@ interface DataListSearchAdapterOptions {
   rawKeyAt: (index: number) => string;
   /** Raw (unfiltered) index → text matched against the query. */
   rawSearchTextAt: (index: number) => string;
+  /** Raw index → whether the item takes part in search. Default: all do. */
+  isSearchable?: (index: number) => boolean;
   /** `filter` mode: the host hides items whose key is not in `matchedKeys` (`undefined` clears). */
   onFilterChange?: (matchedKeys: ReadonlySet<string> | undefined) => void;
   /** `navigate` + Enter: activate the item with this key. Falls back to `focusKey`. */
@@ -5361,6 +5520,8 @@ interface ElementListSearchAdapterOptions {
   highlightKey?: string;
   /** Full ordered item set, including rows not currently in the DOM (virtualised hosts). Defaults to querying `itemSelector`. */
   getAllItems?: () => Element[];
+  /** Items for which this returns `false` take no part in search. Default: all do. */
+  isSearchable?: (el: Element) => boolean;
   /** Observe host child-list mutations to refresh the item set. Default true. */
   observeContainer?: boolean;
 }
@@ -5818,6 +5979,12 @@ export declare class DataGridElement extends LitElement {
    * built-in HTML+canvas preview.
    */
   dragPreviewRenderer: ListDragPreviewRenderer<unknown> | undefined;
+  /**
+   * Write an application payload onto the drag's `DataTransfer` (e.g. a custom
+   * MIME type). Called once per drag, synchronously inside `dragstart`, after a
+   * non-cancelled `list-native-drag-start`.
+   */
+  writeDataTransfer: ListDragDataTransferWriter<unknown> | undefined;
   dragPreviewSource: ListDragPreviewSourceResolver<unknown> | undefined;
   /**
    * Default icon name for column header buttons. Defaults to `ellipsis`.
@@ -5901,6 +6068,28 @@ export declare class DataGridElement extends LitElement {
    */
   get partialKeys(): ReadonlySet<string>;
   set partialKeys(keys: Iterable<string>);
+  /**
+   * Caller-assigned tags for a row (`undefined` ⇒ none). Each tag is exposed on
+   * the row as a `tag-<name>` `part` token (`::part(item tag-foo)`) and in
+   * `data-tags` (`[data-tags~="foo"]`); `tagBehaviour` can switch off selection,
+   * focus, drag or search per tag. `index` is the row's position in the sorted
+   * order. Re-read on every render; call {@link refreshTags} after mutating
+   * data the hook reads.
+   */
+  tags: ((row: unknown, index: number) => readonly string[] | undefined) | undefined;
+  /** Tags by row key, apart from the row data (like {@link partialKeys}): tag name → keys. Merged with the `tags` hook. */
+  get tagKeys(): ItemTagKeys | undefined;
+  set tagKeys(value: ItemTagKeys | undefined);
+  /**
+   * Interaction flags per tag name: `selectable`, `focusable`, `draggable`,
+   * `searchable` (`false` switches one off; omitted keeps the default). With
+   * several tags the most restrictive wins. Rows stay rendered and keep their
+   * place in layout and scroll.
+   */
+  get tagBehaviour(): ItemTagBehaviour | undefined;
+  set tagBehaviour(value: ItemTagBehaviour | undefined);
+  /** Re-evaluate tags and re-render (the `tags` hook is read live; this drops cached cursor state). */
+  refreshTags(): void;
   /** Replace the selection with these row keys (clamped to known rows). */
   set selectedKeys(keys: Iterable<string>);
   /**
@@ -6371,6 +6560,12 @@ export declare class VerticalListElement extends LitElement {
    * built-in HTML+canvas preview.
    */
   dragPreviewRenderer: ListDragPreviewRenderer<Element> | undefined;
+  /**
+   * Write an application payload onto the drag's `DataTransfer` (e.g. a custom
+   * MIME type). Called once per drag, synchronously inside `dragstart`, after a
+   * non-cancelled `list-native-drag-start`.
+   */
+  writeDataTransfer: ListDragDataTransferWriter<Element> | undefined;
   dragPreviewSource: ListDragPreviewSourceResolver<Element> | undefined;
   /**
    * Object/adapter item mode (mirrors `ixfx-detail-list`). When set, the list
@@ -6515,6 +6710,23 @@ export declare class VerticalListElement extends LitElement {
   selectAll(): void;
   /** The selection as stable `data-key` / `data-value` strings. */
   get selectedKeys(): ReadonlySet<string>;
+  /**
+   * Tags assigned by key, apart from the item data (like {@link partialKeys}):
+   * tag name → keys carrying it. Each tag is mirrored on the row as `data-tags`
+   * (`li[data-tags~="foo"]`); `tagBehaviour` can switch off selection, focus,
+   * drag or search per tag.
+   */
+  get tagKeys(): ItemTagKeys | undefined;
+  set tagKeys(value: ItemTagKeys | undefined);
+  /**
+   * Interaction flags per tag name: `selectable`, `focusable`, `draggable`,
+   * `searchable` (`false` switches one off; omitted keeps the default). With
+   * several tags the most restrictive wins. Rows stay rendered.
+   */
+  get tagBehaviour(): ItemTagBehaviour | undefined;
+  set tagBehaviour(value: ItemTagBehaviour | undefined);
+  /** Re-apply `data-tags` to the rows and refresh drag state. Called automatically on change and after each update. */
+  refreshTags(): void;
   /**
    * Rows shown as *partially* selected (a part of the resource is selected):
    * `data-partial`, an indeterminate checkbox in `checked` mode, and an
@@ -6738,6 +6950,31 @@ export declare class DetailListElement extends LitElement {
    */
   badgeProperty: string;
   keyProperty: string;
+  /**
+   * Caller-assigned tags for an object item (`undefined` ⇒ none). Each tag is
+   * mirrored on the row as `data-tags` (style with `li[data-tags~="foo"]`), and
+   * `tagBehaviour` can switch off selection, focus, drag or search per tag.
+   * Re-evaluated when `items`, `tags`, `tagKeys` or `tagBehaviour` change, or on
+   * {@link refreshTags}.
+   */
+  tags: ((item: unknown, index: number) => readonly string[] | undefined) | undefined;
+  /**
+   * Tags assigned by key, apart from the item data (like `partialKeys`):
+   * tag name → keys carrying it. Merged with the `tags` hook; works for
+   * declarative rows too.
+   */
+  get tagKeys(): ItemTagKeys | undefined;
+  set tagKeys(value: ItemTagKeys | undefined);
+  /**
+   * Interaction flags per tag name: `selectable`, `focusable`, `draggable`,
+   * `searchable` (`false` switches one off; omitted keeps the default). With
+   * several tags the most restrictive wins. Rows stay rendered and keep their
+   * place in layout.
+   */
+  get tagBehaviour(): ItemTagBehaviour | undefined;
+  set tagBehaviour(value: ItemTagBehaviour | undefined);
+  /** Re-evaluate every row's tags (call after mutating data the `tags` hook reads). */
+  refreshTags(): void;
   filterPredicate: ((el: Element) => boolean) | undefined;
   /**
    * Whether keyboard navigation wraps from last to first and vice versa.
@@ -6764,6 +7001,12 @@ export declare class DetailListElement extends LitElement {
    * built-in HTML+canvas preview.
    */
   dragPreviewRenderer: ListDragPreviewRenderer<Element> | undefined;
+  /**
+   * Write an application payload onto the drag's `DataTransfer` (e.g. a custom
+   * MIME type). Called once per drag, synchronously inside `dragstart`, after a
+   * non-cancelled `list-native-drag-start`.
+   */
+  writeDataTransfer: ListDragDataTransferWriter<Element> | undefined;
   dragPreviewSource: ListDragPreviewSourceResolver<Element> | undefined;
   /**
    * Group rows under collapsible headers that flow inline in the columns. A
@@ -8400,6 +8643,8 @@ export declare class FlatListElement extends LitElement {
   itemWrap: `stop` | `wrap`;
   searchModes: string | undefined;
   itemsDraggable: boolean;
+  /** Write an application payload onto the drag's `DataTransfer`. Forwarded to the inner list. */
+  writeDataTransfer: ListDragDataTransferWriter<Element> | undefined;
   /** Rows (and empty space) accept native drops. See `flat-list-drop`. */
   itemsDroppable: boolean;
   /**
@@ -9159,6 +9404,11 @@ type TickledItem<T = unknown> = {
    * Whether the item is currently enabled/interactive
    */
   readonly enabled?: boolean;
+  /**
+   * `false`: hover may still tickle the item, but keyboard cursor movement
+   * skips it. Independent of `enabled` (which blocks both).
+   */
+  readonly focusable?: boolean;
 };
 /**
  * Input mode determines which mechanism controls the tickled state
@@ -9448,6 +9698,13 @@ type GridListDataAdapter<T> = {
   label?: (item: T, index: number) => string;
   render: (item: T, index: number) => unknown;
   disabled?: (item: T, index: number) => boolean;
+  /**
+   * Caller-assigned tags for the item (`undefined` ⇒ none). Each tag is exposed as a
+   * `tag-<name>` token in the cell's `part` and in `data-tags`; `tagBehaviour` can
+   * switch off selection, focus, drag or search per tag. Re-read on every render, so
+   * `updateItem` / `updateItems` pick up changes.
+   */
+  tags?: (item: T, index: number) => readonly string[] | undefined;
   searchableText?: (item: T, index: number) => string;
   /**
    * Per-item icon, rendered above `render`'s output inside the cell's content
@@ -9686,6 +9943,12 @@ export declare class GridListElement<T = unknown> extends LitElement {
    * as selection changes. Defaults to the shared built-in preview.
    */
   dragPreviewRenderer: ListDragPreviewRenderer<T> | undefined;
+  /**
+   * Write an application payload onto the drag's `DataTransfer` (e.g. a custom
+   * MIME type). Called once per drag, synchronously inside `dragstart`, after a
+   * non-cancelled `list-native-drag-start`.
+   */
+  writeDataTransfer: ListDragDataTransferWriter<T> | undefined;
   /**
    * Optional synchronous resolver that supplies an already-loaded
    * `CanvasImageSource` for each drag entry's preview thumbnail.
@@ -9911,6 +10174,22 @@ export declare class GridListElement<T = unknown> extends LitElement {
    * Auto-assigned keyless-item keys are omitted.
    */
   visibleKeys(): string[];
+  /**
+   * Tags assigned by key, for callers who keep them apart from the item data
+   * (like {@link partialKeys}): tag name → keys carrying it. Merged with the
+   * adapter's `tags` hook. Each tag shows as a `tag-<name>` `part` token and in
+   * `data-tags`. Works in element mode too.
+   */
+  get tagKeys(): ItemTagKeys | undefined;
+  set tagKeys(value: ItemTagKeys | undefined);
+  /**
+   * Interaction flags per tag name: `selectable`, `focusable`, `draggable`,
+   * `searchable` (each `false` to switch off; omitted keeps the default). With
+   * several tags the most restrictive wins. Items stay rendered and keep their
+   * place in layout and scroll.
+   */
+  get tagBehaviour(): ItemTagBehaviour | undefined;
+  set tagBehaviour(value: ItemTagBehaviour | undefined);
   /**
    * Cells shown as *partially* selected (a part of the resource is selected):
    * `data-partial` / `part="item partial"` and an accessible description.
@@ -12497,6 +12776,22 @@ export declare class MulticolListElement extends LitElement {
   private _getCategoryLabel;
   /** Category description if present, else the default 'Change category' hint. */
   private _getCategoryTooltip;
+  /**
+   * Caller-assigned tags for an item (`undefined` ⇒ none), given the column it
+   * is shown in. Each tag is mirrored on the item as `data-tags`
+   * (`li[data-tags~="foo"]`); `tagBehaviour` can switch off selection, focus,
+   * drag or search per tag. Merged with {@link tagKeys}. Call {@link refreshTags}
+   * after changing what the hook reads.
+   */
+  tags: ((item: MulticolItem, columnId: string) => readonly string[] | undefined) | undefined;
+  /** Tags by item key, in every column with an item of that key: tag name → keys. */
+  get tagKeys(): ItemTagKeys | undefined;
+  set tagKeys(value: ItemTagKeys | undefined);
+  /** Interaction flags per tag name (`selectable`, `focusable`, `draggable`, `searchable`); the most restrictive flag wins. */
+  get tagBehaviour(): ItemTagBehaviour | undefined;
+  set tagBehaviour(value: ItemTagBehaviour | undefined);
+  /** Re-evaluate every column's tags. */
+  refreshTags(): void;
   /**
    * Item keys shown as *partially* selected in every column that has an item
    * with that key (see `ixfx-vertical-list`'s `partialKeys`). Independent of
@@ -14185,12 +14480,57 @@ export type NotifierOptions = {
   tapBehaviour?: `none` | `dismiss`;
   tapHandlerDefault?: (notification: Notification) => void;
 };
-export declare const NotificationManager: {
-  configure(opts: NotifierOptions): void;
-  notify(content: NotificationContent): string;
-  update(id: string, content: Partial<NotificationContent>): void;
-  dismiss(id: string): void;
-  dismissAll(): void;
+/** A notification as remembered by a manager's history. */
+export type NotificationHistoryEntry = Notification & {
+  /** `true` once read: via `markRead`/`markAllRead`, or when the user taps the toast. */
+  readonly read: boolean;
+  /** Set once the toast is no longer visible (timed out, evicted, tapped away or dismissed). */
+  readonly dismissedAt?: number;
+};
+export type NotificationHistoryListener = (history: readonly NotificationHistoryEntry[]) => void;
+/** Options for `createNotificationManager` / `NotificationManager.scope`. */
+export type NotificationManagerOptions = NotifierOptions & {
+  /** Max history entries kept per manager (oldest dropped first). Default 100. */
+  historyLimit?: number;
+};
+/**
+ * An independent notification manager: its own queue, timers, renderer,
+ * options and history. `NotificationManager` is the default, app-wide
+ * instance; create more with `createNotificationManager()` (or
+ * `NotificationManager.scope(name)`) to show toasts next to the component
+ * they concern.
+ */
+export type NotificationManagerInstance = {
+  configure: (opts: NotificationManagerOptions) => void;
+  notify: (content: NotificationContent) => string;
+  update: (id: string, content: Partial<NotificationContent>) => void;
+  dismiss: (id: string) => void;
+  dismissAll: () => void;
+  /** Remembered notifications, oldest first. Includes ones no longer visible. */
+  getHistory: () => readonly NotificationHistoryEntry[];
+  /** Number of history entries not yet read. Drives a bell indicator. */
+  readonly unreadCount: number;
+  markRead: (id: string) => void;
+  markAllRead: () => void;
+  clearHistory: () => void;
+  /** Called with the full history whenever it changes (new, updated, read, dismissed, cleared). Returns an unsubscribe function. */
+  subscribe: (listener: NotificationHistoryListener) => () => void;
+  /** Dismiss everything, drop history and listeners, detach the renderer. The instance is unusable afterwards. */
+  destroy: () => void;
+};
+export declare function createNotificationManager(initial?: NotificationManagerOptions): NotificationManagerInstance;
+/**
+ * The default, app-wide manager. Also a registry of named, independent
+ * scopes: `NotificationManager.scope('lister-1', { renderer })`.
+ */
+export declare const NotificationManager: NotificationManagerInstance & {
+  /**
+   * Get (creating on first use, with `opts`) the independent manager for `name`.
+   * `opts` are ignored if the scope already exists; call `.configure()` on it instead.
+   */
+  scope: (name: string, opts?: NotificationManagerOptions) => NotificationManagerInstance;
+  /** Destroy and forget a named scope (e.g. when its component unmounts). */
+  releaseScope: (name: string) => void;
 };
 export type PillTapDetail = {
   readonly id: string;
@@ -17064,4 +17404,4 @@ export interface XyPad {
   addEventListener: (<K extends keyof XyPadEventMap>(type: K, listener: (this: XyPad, event: XyPadEventMap[K]) => void, options?: boolean | AddEventListenerOptions) => void) & ((type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions) => void);
 }
 export declare function init(): void;
-export { type AcTokenAddDetail, type AcTokenAddEvent, type AcTokenElementEventMap, type AcTokenItem, type AcTokenRemoveDetail, type AcTokenRemoveEvent, type AcTokenStyle, type AcTokenStyleFn, type AcTokenizerFn, type AcTokensChangeDetail, type AcTokensChangeEvent, type AddedNode, type BridgeDeps, type BridgeResult, type BuiltInFormatterName, type BuiltInFormatterOptions, type CheckState, type CheckedSelectItem, type ColourPickerChangeEvent, type ColourPickerEventDetail, type ColourPickerInputEvent, type ComputeHyperbolicLayoutOptions, type ComputeTreemapLayoutOptions, type ContextKind, type ContextTarget, type CrumbNavigationViewState, type CssVars, type DataGridColumn, type DataGridColumnMenu, type DataGridColumnViewState, type DataGridDataType, type DataGridEditability, type DataGridEditorContext, type DataGridEditorFactory, type DataGridEditorType, type DataGridGetRowKey, type DataGridGroupBy, type DataGridGroupLabel, type DataGridInteractionMode, type DataGridRowLook, type DataGridSelectionMode, type DataGridSortDirection, type DataGridSortState, type DataGridViewState, type DataListSearchAdapterOptions, type DataListSearchItem, type DetailFormatter, type DetailGroupBy, type DetailListViewState, type DetailSortComparator, type DetailSortItem, type DetailSortMode, type DockDropZone, type DragSelectRect, type DraggableNode, type ElementIncrSearch, type ElementIncrSearchOptions, type ElementListSearchAdapterOptions, type ElementListSearchHost, type FlatListActivateDetail, type FlatListActivateEvent, type FlatListBranchOrder, type FlatListContextMenuDetail, type FlatListContextMenuEvent, type FlatListDropDetail, type FlatListDropEvent, type FlatListEditCancelDetail, type FlatListEditCancelEvent, type FlatListEditCommitDetail, type FlatListEditCommitEvent, type FlatListElementEventMap, type FlatListNavigateDetail, type FlatListNavigateEvent, type FlatListSelectDetail, type FlatListSelectEvent, type FlatListViewState, type FuzzySearch, type FuzzySearchOptions, type GlobalFormatter, type GridListActivateDetail, type GridListActivateEvent, type GridListCaptionAlign, type GridListCaptionBackdrop, type GridListCaptionPosition, type GridListCaptionStyle, type GridListDataAdapter, type GridListElementEventMap, type GridListFullElementEventMap, type GridListItemClickDetail, type GridListItemClickEvent, type GridListItemEventDetail, type GridListItemUpdate, type GridListOrientation, type GridListSelectDetail, type GridListSelectEvent, type GridListTickleDetail, type GridListTickleEvent, type GridListViewState, type GridListViewportChangeDetail, type GridListViewportChangeEvent, type GroupedItemListerElementEventMap, type GroupedSelectDetail, type GroupedSelectEvent, type HighlightOptions, type HighlightTarget, type HyperbolicEdgeRenderContext, type HyperbolicEdgeRenderer, type HyperbolicFocusDetail, type HyperbolicFocusEvent, type HyperbolicInteractionMode, type HyperbolicLayoutEdge, type HyperbolicLayoutNode, type HyperbolicNodeShape, type Point as HyperbolicPoint, type HyperbolicTreeListViewState, type IGroupedSubComponent, type IGroupedSubComponentEventMap, type IcicleViewState, type IconChangedDetail, type IconChangedEvent, type IconEntry, type IncrSearch, type IncrSearchChangeCallback, IncrSearchTreeController as IncrSearchMillerController, type IncrSearchTreeOptions as IncrSearchMillerOptions, type IncrSearchTreeOptions, type IncrSearchOptions, type IncrSearchResult, type IncrSearchState, type InputMode, type ItemDisplay, type ItemOrientation, type ListActivateDetail, type ListActivateEvent, type ListContextMenuDetail, type ListContextMenuEvent, type ListDragEntry, type ListDragLeaveDetail, type ListDragLeaveEvent, type ListDragOverEvent, type ListDragPreview, type ListDragPreviewContext, type ListDragPreviewRenderer, type ListDragPreviewSourceResolver, type ListDragSelectControllerConfig, type ListDragSource, type ListDropDetail, type ListDropEvent, type ListEditCancelDetail, type ListEditCancelEvent, type ListEditCommitDetail, type ListEditCommitEvent, type ListElementEventMap, type ListGroupBy, type ListGroupChangeDetail, type ListGroupChangeEvent, type ListGroupEventMap, type ListGroupInfo, type ListGroupLabel, type ListGroupPartition, type ListGroupToggleDetail, type ListGroupToggleEvent, type ListInteractionMode, type ListItemClickDetail, type ListItemClickEvent, type ListItemMotionOptions, type ListItemOutResult, type ListMarqueeMode, type ListNativeDragControllerConfig, type ListNativeDragStartDetail, type ListNativeDragStartEvent, type ListSearchAdapter, type ListSearchControllerOptions, type ListSearchHost, type ListSearchMode, type ListSelectDetail, type ListSelectEvent, type ListSelectIntentDetail, type ListSelectIntentEvent, type ListSelectIntentKind, type ListSelectIntentSource, type ListSelectKeysDetail, type ListSelectionControllerConfig, type ListSelectionGesture, type ListSelectionMode, type ListSelectionModes, type ListTickleDetail, type ListTickleEvent, type ListViewportChangeDetail, type ListViewportChangeEvent, type MarqueeConfig, index_d_exports as Menu, type TreeActivateDetail as MillerActivateDetail, type TreeActivateEvent as MillerActivateEvent, type TreeCollapseDetail as MillerCollapseDetail, type TreeCollapseEvent as MillerCollapseEvent, type TreeExpandDetail as MillerExpandDetail, type TreeExpandEvent as MillerExpandEvent, type TreeItem as MillerItem, type TreeItemClickDetail as MillerItemClickDetail, type TreeItemClickEvent as MillerItemClickEvent, type MillerListViewState, type TreeNode as MillerNode, type TreeSelectDetail as MillerSelectDetail, type TreeSelectEvent as MillerSelectEvent, type TreeTickleDetail as MillerTickleDetail, type TreeTickleEvent as MillerTickleEvent, type MulticolCategory, type MulticolColumnState, type MulticolColumnsChangeReason, type MulticolItem, type MulticolListViewState, type MulticolQuery, type MulticolSelectDetail, type NodeDragConfig, type NodeFactory, type NodeFactoryContext, type OklchValue, type OpenableMenu, type PanZoomConfig, Point$1 as Point, type ProximityPair, type ProximityQuery, type Rect, type RegisterListSearchCommandsOptions, type ScrollHoverGuard, type ScrollHoverGuardConfig, type SortDirection, type SubComponentActivateDetail, type SubComponentActivateEvent, type SubComponentFactory, type SubComponentItemClickDetail, type SubComponentItemClickEvent, type SubComponentSelectDetail, type SubComponentSelectEvent, type SubComponentTickleDetail, type SubComponentTickleEvent, type SunburstViewState, type TickledControllerConfig, type TickledItem, type TreeCheckboxState, type TreeKeyboardNavCallbacks, type TreeKeyboardNavControllerConfig, type TreeKeyboardNavItemId, type TreeListSearchAdapterOptions, type TreeListViewState, type TreemapInteractionMode, type TreemapListViewState, type TreemapRect, type TreemapTilingMethod, type TreemapValueAccessor, type VerticalListViewState, type WheelMode, type WireDragConfig, type WireDragMode, type WireDragPort, type WirePath };
+export { type AcTokenAddDetail, type AcTokenAddEvent, type AcTokenElementEventMap, type AcTokenItem, type AcTokenRemoveDetail, type AcTokenRemoveEvent, type AcTokenStyle, type AcTokenStyleFn, type AcTokenizerFn, type AcTokensChangeDetail, type AcTokensChangeEvent, type AddedNode, type BridgeDeps, type BridgeResult, type BuiltInFormatterName, type BuiltInFormatterOptions, type CheckState, type CheckedSelectItem, type ColourPickerChangeEvent, type ColourPickerEventDetail, type ColourPickerInputEvent, type ComputeHyperbolicLayoutOptions, type ComputeTreemapLayoutOptions, type ContextKind, type ContextTarget, type CrumbNavigationViewState, type CssVars, type DataGridColumn, type DataGridColumnMenu, type DataGridColumnViewState, type DataGridDataType, type DataGridEditability, type DataGridEditorContext, type DataGridEditorFactory, type DataGridEditorType, type DataGridGetRowKey, type DataGridGroupBy, type DataGridGroupLabel, type DataGridInteractionMode, type DataGridRowLook, type DataGridSelectionMode, type DataGridSortDirection, type DataGridSortState, type DataGridViewState, type DataListSearchAdapterOptions, type DataListSearchItem, type DetailFormatter, type DetailGroupBy, type DetailListViewState, type DetailSortComparator, type DetailSortItem, type DetailSortMode, type DockDropZone, type DragSelectRect, type DraggableNode, type ElementIncrSearch, type ElementIncrSearchOptions, type ElementListSearchAdapterOptions, type ElementListSearchHost, type FlatListActivateDetail, type FlatListActivateEvent, type FlatListBranchOrder, type FlatListContextMenuDetail, type FlatListContextMenuEvent, type FlatListDropDetail, type FlatListDropEvent, type FlatListEditCancelDetail, type FlatListEditCancelEvent, type FlatListEditCommitDetail, type FlatListEditCommitEvent, type FlatListElementEventMap, type FlatListNavigateDetail, type FlatListNavigateEvent, type FlatListSelectDetail, type FlatListSelectEvent, type FlatListViewState, type FuzzySearch, type FuzzySearchOptions, type GlobalFormatter, type GridListActivateDetail, type GridListActivateEvent, type GridListCaptionAlign, type GridListCaptionBackdrop, type GridListCaptionPosition, type GridListCaptionStyle, type GridListDataAdapter, type GridListElementEventMap, type GridListFullElementEventMap, type GridListItemClickDetail, type GridListItemClickEvent, type GridListItemEventDetail, type GridListItemUpdate, type GridListOrientation, type GridListSelectDetail, type GridListSelectEvent, type GridListTickleDetail, type GridListTickleEvent, type GridListViewState, type GridListViewportChangeDetail, type GridListViewportChangeEvent, type GroupedItemListerElementEventMap, type GroupedSelectDetail, type GroupedSelectEvent, type HighlightOptions, type HighlightTarget, type HyperbolicEdgeRenderContext, type HyperbolicEdgeRenderer, type HyperbolicFocusDetail, type HyperbolicFocusEvent, type HyperbolicInteractionMode, type HyperbolicLayoutEdge, type HyperbolicLayoutNode, type HyperbolicNodeShape, type Point as HyperbolicPoint, type HyperbolicTreeListViewState, type IGroupedSubComponent, type IGroupedSubComponentEventMap, type IcicleViewState, type IconChangedDetail, type IconChangedEvent, type IconEntry, type IncrSearch, type IncrSearchChangeCallback, IncrSearchTreeController as IncrSearchMillerController, type IncrSearchTreeOptions as IncrSearchMillerOptions, type IncrSearchTreeOptions, type IncrSearchOptions, type IncrSearchResult, type IncrSearchState, type InputMode, type ItemDisplay, type ItemOrientation, type ItemTagBehaviour, type ItemTagBehaviourFlags, type ItemTagKeys, type ListActivateDetail, type ListActivateEvent, type ListContextMenuDetail, type ListContextMenuEvent, type ListDragDataTransferWriter, type ListDragEntry, type ListDragLeaveDetail, type ListDragLeaveEvent, type ListDragOverEvent, type ListDragPreview, type ListDragPreviewContext, type ListDragPreviewRenderer, type ListDragPreviewSourceResolver, type ListDragSelectControllerConfig, type ListDragSource, type ListDropDetail, type ListDropEvent, type ListEditCancelDetail, type ListEditCancelEvent, type ListEditCommitDetail, type ListEditCommitEvent, type ListElementEventMap, type ListGroupBy, type ListGroupChangeDetail, type ListGroupChangeEvent, type ListGroupEventMap, type ListGroupInfo, type ListGroupLabel, type ListGroupPartition, type ListGroupToggleDetail, type ListGroupToggleEvent, type ListInteractionMode, type ListItemClickDetail, type ListItemClickEvent, type ListItemMotionOptions, type ListItemOutResult, type ListMarqueeMode, type ListNativeDragControllerConfig, type ListNativeDragStartDetail, type ListNativeDragStartEvent, type ListSearchAdapter, type ListSearchControllerOptions, type ListSearchHost, type ListSearchMode, type ListSelectDetail, type ListSelectEvent, type ListSelectIntentDetail, type ListSelectIntentEvent, type ListSelectIntentKind, type ListSelectIntentSource, type ListSelectKeysDetail, type ListSelectionControllerConfig, type ListSelectionGesture, type ListSelectionMode, type ListSelectionModes, type ListTickleDetail, type ListTickleEvent, type ListViewportChangeDetail, type ListViewportChangeEvent, type MarqueeConfig, index_d_exports as Menu, type TreeActivateDetail as MillerActivateDetail, type TreeActivateEvent as MillerActivateEvent, type TreeCollapseDetail as MillerCollapseDetail, type TreeCollapseEvent as MillerCollapseEvent, type TreeExpandDetail as MillerExpandDetail, type TreeExpandEvent as MillerExpandEvent, type TreeItem as MillerItem, type TreeItemClickDetail as MillerItemClickDetail, type TreeItemClickEvent as MillerItemClickEvent, type MillerListViewState, type TreeNode as MillerNode, type TreeSelectDetail as MillerSelectDetail, type TreeSelectEvent as MillerSelectEvent, type TreeTickleDetail as MillerTickleDetail, type TreeTickleEvent as MillerTickleEvent, type MulticolCategory, type MulticolColumnState, type MulticolColumnsChangeReason, type MulticolItem, type MulticolListViewState, type MulticolQuery, type MulticolSelectDetail, type NodeDragConfig, type NodeFactory, type NodeFactoryContext, type OklchValue, type OpenableMenu, type PanZoomConfig, Point$1 as Point, type ProximityPair, type ProximityQuery, type Rect, type RegisterListSearchCommandsOptions, type ResolvedItemTagFlags, type ScrollHoverGuard, type ScrollHoverGuardConfig, type SortDirection, type SubComponentActivateDetail, type SubComponentActivateEvent, type SubComponentFactory, type SubComponentItemClickDetail, type SubComponentItemClickEvent, type SubComponentSelectDetail, type SubComponentSelectEvent, type SubComponentTickleDetail, type SubComponentTickleEvent, type SunburstViewState, type TickledControllerConfig, type TickledItem, type TreeCheckboxState, type TreeKeyboardNavCallbacks, type TreeKeyboardNavControllerConfig, type TreeKeyboardNavItemId, type TreeListSearchAdapterOptions, type TreeListViewState, type TreemapInteractionMode, type TreemapListViewState, type TreemapRect, type TreemapTilingMethod, type TreemapValueAccessor, type VerticalListViewState, type WheelMode, type WireDragConfig, type WireDragMode, type WireDragPort, type WirePath };