@leavittsoftware/web 11.0.1 → 11.1.0

package/CLAUDE.md

@@ -27,6 +27,7 @@ When bumping `@leavittsoftware/web` in a downstream project, read every entry **
 
 **Search downstream for:**
 
+- Hand-rolled multi selects built from `titanium-chip-multi-select` + a `leavitt-*-select` / `titanium-single-select-base` subclass
 - `AppRoute` / `PageRoute` / `RedirectRoute` imports from `titanium/helpers/route`
 - App-shell `#routes` tables and `before` handlers on page routes
 - `'page' in route` / `'redirect' in route` discriminators used to collect or execute matches
@@ -34,11 +35,13 @@ When bumping `@leavittsoftware/web` in a downstream project, read every entry **
 
 **Adopt when upgrading to this version:**
 
+- **`titanium-multi-select-base`** — new generic multi select combobox: selected items render as chips inside the field and the search input lives in the popover above the selectable items. Replaces the `titanium-chip-multi-select` + separate single-select + add-button pattern for "pick several from a list" inputs. Use it directly with `.items` (local fuse.js search) and optional `.sections` grouping, or extend it and override `onInputChanged` / `showSuggestions` for remote search — same hook names as `titanium-single-select-base`. Fires `selected-changed`; read the new value from `event.target.selected`.
 - **Middleware + halt pipeline** — `AppRoute` now includes `MiddlewareRoute` (`pattern` + required `before`, no `page`/`redirect`). Matching destinations run **all** matching middleware (and page `before` handlers) in declaration order; handlers continue by default and may return `ROUTE_HALT` / `'halt'` (`RouteHandlerResult`) to stop the pipeline without rendering. Rework app routers from “first match wins immediately” to the two-pass collect-then-execute pattern (see skeleton.leavitt.com `develop` / leavittbook `my-app.ts`). Prefer importing `ROUTE_HALT` from `titanium/helpers/route` instead of the string literal.
 - **`titanium-single-select-base` shaped menu tokens** — shaped open menus now set `--md-menu-item-leading-icon-color` / `--md-menu-item-trailing-icon-color` to `inverse-on-surface` (alongside the existing label/supporting-text tokens). Inert section-header `md-menu-item` styling (spacing + shaped inverse colors) lives on the base — remove duplicate `md-menu-item[inert]` / leading-icon color overrides from subclasses once on this build.
 
 **Renamed / API changes:**
 
+- New element: `titanium-multi-select-base` (`titanium/multi-select-base/multi-select-base`); new exported type `TitaniumMultiSelectSection<T>`
 - `AppRoute` = `MiddlewareRoute | PageRoute | RedirectRoute`
 - `PageRoute.before` return type is now `RouteHandlerResult | Promise<RouteHandlerResult>` (may return `ROUTE_HALT` / `'halt'`)
 - New exports: `MiddlewareRoute`, `RouteHandlerResult`, `ROUTE_HALT`
@@ -165,6 +168,7 @@ Titanium **mixins and decorators** (`ThemePreference`, `promiseTracking`, …) a
 | `titanium-date-input`                                                                                    | composes | `md-filled-field`                                                                                                         |
 | `titanium-date-range-selector`                                                                           | composes | `md-filled-field`, `md-menu`, `md-list`                                                                                   |
 | `titanium-single-select-base` and all `leavitt-*-select`, `titanium-icon-picker`, `google-address-input` | composes | `md-filled-text-field`, `md-menu`, `md-menu-item`                                                                         |
+| `titanium-multi-select-base`                                                                             | composes | `titanium-filled-input-validator` (extends `MdFilledField`), `md-menu`, `md-menu-item`, `titanium-chip`                   |
 | `titanium-chip-multi-select`                                                                             | composes | `titanium-filled-input-validator` (extends `MdFilledField`); slots intended for `md-filled-tonal-button`, `md-input-chip` |
 | `titanium-confirmation-dialog` and most modal/dialog components                                          | composes | `md-dialog` (+ `md-filled-button` / `md-text-button` actions)                                                             |
 | `titanium-data-table-core`                                                                               | composes | `md-checkbox`, `md-icon-button`, `md-menu`                                                                                |
@@ -349,6 +353,7 @@ Titanium class inheritance (in addition to Material Web extend/compose — see *
 | `MdFilledTextField`        | `@material/web/textfield/filled-text-field`      | `titanium-filled-duration-input`, `titanium-filled-youtube-input`                                          |
 | `MdFilledField`            | `@material/web/field/filled-field`               | `titanium-filled-input-validator`                                                                          |
 | `TitaniumSingleSelectBase` | `titanium/single-select-base/single-select-base` | All `leavitt-*-select`, `titanium-icon-picker`, `google-address-input`                                     |
+| `TitaniumMultiSelectBase`  | `titanium/multi-select-base/multi-select-base`   | Usable directly; extend for remote-search multi selects                                                    |
 | `google-address-input`     | `titanium/address-input/google-address-input`    | `titanium-address-input`                                                                                   |
 | `ThemePreference` mixin    | `leavitt/theme/theme-preference`                 | `leavitt-app-logo`, `leavitt-error-page`, `leavitt-service-worker-notifier`, `titanium-single-select-base` |
 
@@ -913,6 +918,64 @@ Row clicks with `itemLinkUrl` navigate directly via `window.navigation.navigate(
 
 ---
 
+### `titanium-multi-select-base`
+
+**Purpose:** Generic multi select combobox. Selected items render as removable chips inside the field; the search input lives in the popover directly above the selectable items.
+
+**Material Web:** Composes `titanium-filled-input-validator` (extends `MdFilledField`) as the field, plus `md-menu` + `md-menu-item` for the popover and `titanium-chip` for the chips.
+
+**Import:** `import '@leavittsoftware/web/titanium/multi-select-base/multi-select-base.js'`
+
+**Source:** `titanium/multi-select-base/multi-select-base.ts`
+
+| Kind      | Name                                                   | Type / values                                    | Notes                                                       |
+| --------- | ------------------------------------------------------ | ------------------------------------------------ | ----------------------------------------------------------- |
+| Property  | `selected`                                             | `T[]`                                            | Selected items                                              |
+| Property  | `items`                                                | `T[]`                                            | Full catalog; searched locally with fuse.js                 |
+| Property  | `sections`                                             | `TitaniumMultiSelectSection<T>[]`                | Optional grouping shown when no search term is entered      |
+| Property  | `label`, `placeholder`                                 | `string`                                         | `placeholder` shows in the field when nothing is selected   |
+| Attribute | `search-placeholder`                                   | `string`                                         | Placeholder of the popover search input                     |
+| Property  | `pathToSelectedText`                                   | `string`                                         | Default `'Name'`; key holding the display text              |
+| Property  | `pathToIcon`                                           | `string`                                         | Optional key holding a Material Symbols icon name           |
+| Property  | `searchKeys`                                           | `string[]`                                       | fuse.js keys; defaults to `[pathToSelectedText]`            |
+| Attribute | `max-selected`                                         | `number`                                         | `0` (default) allows an unlimited number                    |
+| Property  | `required`, `disabled`, `error`                        | `boolean`                                        | `required` = at least one selection                         |
+| Property  | `errorText`, `supportingText`                          | `string`                                         |                                                             |
+| Attribute | `no-items-text`, `no-results-text`                     | `string`                                         | Empty-state text for an empty catalog / an unmatched search |
+| Attribute | `has-leading-icon`, `no-asterisk`, `disable-clear-all` | `boolean`                                        |                                                             |
+| Attribute | `match-input-width`                                    | `boolean`                                        | ResizeObserver keeps the popover the width of the field     |
+| Attribute | `menu-open`                                            | `boolean`                                        | Reflected; read via the `isOpen` getter                     |
+| Property  | `positioning`                                          | `absolute` \| `fixed` \| `document` \| `popover` | Default `popover`                                           |
+| Getter    | `isOpen`, `isAtMaxSelected`                            | `boolean`                                        |                                                             |
+| State     | `isLoading`                                            | `boolean`                                        | Via `promiseTracking` / `trackLoadingPromise`               |
+
+**Methods:** `open()`, `close()`, `toggleMenu()`, `focus()`, `selectItem(item)`, `deselectItem(item)`, `toggleItem(item)`, `isSelected(item)`, `clear()`, `reset()`, `softReset()`, `checkValidity()`, `reportValidity()`, `trackLoadingPromise(promise)`
+
+**Events:** `selected-changed` (composed) — read `event.target.selected`; redispatches menu `opening`/`opened`/`closing`/`closed`
+
+**Slots:** `leading-icon` (requires `has-leading-icon`)
+
+**CSS parts:** `menu`
+
+**CSS custom properties:** `--titanium-multi-select-menu-max-height` (default `460px`), `--titanium-multi-select-search-height` (default `52px`)
+
+**Exported types:** `TitaniumMultiSelectSection<T>` — `{ key, headline, supportingText?, icon?, items }`
+
+**Usage notes / gotchas:**
+
+- Items may appear in more than one section (e.g. "Frequently used" + "All"); identity comes from `Id`, falling back to the display text, so duplicates stay in sync
+- Searching always renders a flat list across the whole catalog, never the sections
+- Menu items are rendered with `keep-open`, so the popover stays open while toggling; the base handles click / Enter / Space selection so `renderSuggestion` overrides only need markup
+- Keyboard: `ArrowDown` from the search input moves into the list, `ArrowUp` on the first item returns to the search input, `Backspace` on an empty search removes the last chip, `Escape` closes
+- Validity is reported when the popover closes; `required` fields do not error before the user has interacted
+- `positioning='popover'` falls back to `'fixed'` in Firefox
+
+**Subclassing (remote search):** override `onInputChanged(searchTerm)` and call `showSuggestions(results, totalCount)` — same hooks as `titanium-single-select-base`. Override `renderSuggestion`, `renderChip`, `renderSectionHeader`, `renderTrailingMenuSlot`, `getItemText`, `getItemIcon`, or `getItemKey` to customize rendering and identity.
+
+**Pairs with:** `titanium-chip`, `titanium-filled-input-validator`
+
+---
+
 ### `titanium-icon-picker`
 
 **Purpose:** Material Symbols icon search and select.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leavittsoftware/web",
-  "version": "11.0.1",
+  "version": "11.1.0",
   "license": "Apache-2.0",
   "description": "",
   "files": [
@@ -42,5 +42,5 @@
     "url": "https://github.com/LeavittSoftware/titanium-elements/issues"
   },
   "homepage": "https://github.com/LeavittSoftware/titanium-elements/#readme",
-  "gitHead": "fa73c6359a09f0857876271457795ad38f45b85b"
+  "gitHead": "82d2a75718eeced0e64f20dd84a1c5a4c5625b75"
 }

package/titanium/multi-select-base/multi-select-base.d.ts

@@ -0,0 +1,274 @@
+import '@material/web/icon/icon';
+import '@material/web/iconbutton/icon-button';
+import '@material/web/menu/menu';
+import '@material/web/menu/menu-item';
+import '@material/web/progress/circular-progress';
+import '../chip/chip';
+import '../input-validator/filled-input-validator';
+import { LitElement, nothing, PropertyValues, TemplateResult } from 'lit';
+import { Identifier } from '../types/identifier-interface';
+import { Menu } from '@material/web/menu/internal/menu';
+import { TitaniumFilledInputValidator } from '../input-validator/filled-input-validator';
+/**
+ * A group of items rendered under a header when no search term is entered.
+ */
+export type TitaniumMultiSelectSection<T> = {
+    /**
+     *  Unique key of the section. Used for list diffing.
+     */
+    key: string;
+    /**
+     *  Header text of the section.
+     */
+    headline: string;
+    /**
+     *  Optional second line of the section header.
+     */
+    supportingText?: string;
+    /**
+     *  Optional Material Symbols icon name shown before the header text.
+     */
+    icon?: string;
+    /**
+     *  Items belonging to the section. Items may appear in more than one section.
+     */
+    items: Array<T>;
+};
+/**
+ *  Generic multi select combobox. Selected items are displayed as chips inside the field
+ *  and the search input lives in the popover above the selectable items.
+ *
+ *  Use directly for locally searchable lists or extend it to supply remote search results.
+ *
+ *  @element titanium-multi-select-base
+ *
+ *  @fires selected-changed - Fired when the user adds or removes an item. Read the new value from `event.target.selected`.
+ *
+ *  @slot leading-icon - Icon displayed at the start of the field. Requires `has-leading-icon`.
+ *
+ *  @cssprop --titanium-multi-select-menu-max-height - Max height of the popover. Defaults to 460px.
+ *  @cssprop --titanium-multi-select-search-height - Height of the sticky search row. Defaults to 52px.
+ */
+export declare class TitaniumMultiSelectBase<T extends Identifier = Identifier> extends LitElement {
+    #private;
+    accessor isLoading: boolean;
+    trackLoadingPromise: (promise: Promise<unknown>) => Promise<void>;
+    /**
+     *  Sets floating label value.
+     */
+    accessor label: string;
+    /**
+     *  Text displayed in the field when nothing is selected.
+     */
+    accessor placeholder: string;
+    /**
+     *  Placeholder text of the search input inside the popover.
+     */
+    accessor searchPlaceholder: string;
+    /**
+     *  The items selected by the user.
+     */
+    accessor selected: Array<T>;
+    /**
+     *  Every selectable item. Searched locally with fuse.js and rendered when `sections` is empty.
+     */
+    accessor items: Array<T>;
+    /**
+     *  Optional grouping of items rendered when no search term is entered. Search results are always
+     *  rendered as a flat list.
+     */
+    accessor sections: Array<TitaniumMultiSelectSection<T>>;
+    /**
+     *  Key on an item holding the text to display in chips and menu items.
+     */
+    accessor pathToSelectedText: string;
+    /**
+     *  Optional key on an item holding a Material Symbols icon name.
+     */
+    accessor pathToIcon: string;
+    /**
+     *  Keys searched by the local fuse.js search. Defaults to `[pathToSelectedText]`.
+     */
+    accessor searchKeys: Array<string>;
+    /**
+     *  Maximum number of items the user is allowed to select. Zero allows an unlimited number.
+     */
+    accessor maxSelected: number;
+    /**
+     *  Displays error state when nothing is selected.
+     */
+    accessor required: boolean;
+    /**
+     *  Whether or not the input should be disabled.
+     */
+    accessor disabled: boolean;
+    /**
+     *  Gets or sets whether or not the field is in a visually invalid state.
+     */
+    accessor error: boolean;
+    /**
+     *  Error message displayed below the field when it is in an invalid state.
+     */
+    accessor errorText: string;
+    /**
+     *  Conveys additional information below the field, such as how it should be used.
+     */
+    accessor supportingText: string;
+    /**
+     *  Disables the asterisk on the floating label when the field is required.
+     */
+    accessor noAsterisk: boolean;
+    /**
+     *  Renders the `leading-icon` slot at the start of the field.
+     */
+    accessor hasLeadingIcon: boolean;
+    /**
+     *  Text displayed in the popover when there is nothing to select.
+     */
+    accessor noItemsText: string;
+    /**
+     *  Text displayed in the popover when a search returns no results.
+     */
+    accessor noResultsText: string;
+    /**
+     *  Hides the clear all button that appears in the field once something is selected.
+     */
+    accessor disableClearAll: boolean;
+    /**
+     *  Positioning strategy of the popover. `popover` falls back to `fixed` in browsers without popover support.
+     */
+    accessor positioning: 'absolute' | 'fixed' | 'document' | 'popover';
+    /**
+     *  When enabled, uses a ResizeObserver to keep the popover width in sync with the field width.
+     */
+    accessor matchInputWidth: boolean;
+    private accessor menuOpen;
+    protected accessor searchTerm: string;
+    /**
+     *  Results of the last search. Rendered instead of `items` / `sections` while a search term is entered.
+     */
+    protected accessor suggestions: Array<T>;
+    protected accessor count: number;
+    private accessor menuWidth;
+    protected accessor menu: Menu | null;
+    protected accessor field: TitaniumFilledInputValidator | null;
+    protected accessor searchInput: HTMLInputElement | null;
+    /**
+     *  Whether or not the popover is open.
+     */
+    get isOpen(): boolean;
+    /**
+     *  Whether or not `maxSelected` has been reached.
+     */
+    get isAtMaxSelected(): boolean;
+    /**
+     *  Items currently rendered in the popover, flattened across sections.
+     */
+    protected get visibleItems(): Array<T>;
+    /**
+     *  Items searched by the local search. Falls back to the items of every section when `items` is empty.
+     */
+    protected get searchPool(): Array<T>;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    update(changed: PropertyValues<this>): void;
+    updated(changed: PropertyValues<this>): void;
+    /**
+     *  Opens the popover and focuses the search input.
+     */
+    open(): void;
+    /**
+     *  Closes the popover.
+     */
+    close(): void;
+    /**
+     *  Opens the popover when closed, closes it when open.
+     */
+    toggleMenu(): void;
+    /**
+     *  Sets focus on the field.
+     */
+    focus(): Promise<void>;
+    /**
+     *  Returns true when the given item is selected.
+     */
+    isSelected(item: T): boolean;
+    /**
+     *  Adds an item to the selection. Does nothing when it is already selected or `maxSelected` is reached.
+     */
+    selectItem(item: T): void;
+    /**
+     *  Removes an item from the selection.
+     */
+    deselectItem(item: T): void;
+    /**
+     *  Adds the item when it is not selected, removes it when it is.
+     */
+    toggleItem(item: T): void;
+    /**
+     *  Removes every selected item.
+     */
+    clear(): void;
+    /**
+     *  Clears the selection, the search term and the validity state.
+     */
+    reset(): void;
+    /**
+     *  Clears the search term and its results.
+     */
+    softReset(): void;
+    /**
+     *  Returns true if the field passes validity checks.
+     */
+    checkValidity(): boolean;
+    /**
+     *  Runs checkValidity() method, and if it returns false, then it reports to the user that the field is invalid.
+     */
+    reportValidity(): boolean;
+    /**
+     *  Called with the current search term after every keystroke. Override to supply remote results
+     *  and call `showSuggestions()` when they arrive.
+     */
+    protected onInputChanged(searchTerm: string): void;
+    /**
+     *  Renders the given search results in the popover.
+     */
+    protected showSuggestions(suggestions: Array<T>, totalSuggestionCount: number): Promise<void>;
+    /**
+     *  Unique key of an item. Used for list diffing and selection comparisons.
+     */
+    protected getItemKey(item: T): string;
+    /**
+     *  Text of an item shown in its chip and menu item.
+     */
+    protected getItemText(item: T): string;
+    /**
+     *  Material Symbols icon name of an item, or an empty string when it has none.
+     */
+    protected getItemIcon(item: T): string;
+    static styles: import("lit").CSSResult[];
+    /**
+     *  Renders the chip of a selected item. Override to customize.
+     */
+    protected renderChip(item: T): TemplateResult<1>;
+    /**
+     *  Renders a selectable item. Override to customize. Bind the item to the `item` property of the
+     *  `md-menu-item` and keep `keep-open` so the popover stays open on selection.
+     */
+    protected renderSuggestion(item: T): TemplateResult<1>;
+    /**
+     *  Renders the header of a section. Override to customize.
+     */
+    protected renderSectionHeader(section: TitaniumMultiSelectSection<T>): TemplateResult<1>;
+    /**
+     *  Renders content at the bottom of the popover, below the selectable items.
+     */
+    protected renderTrailingMenuSlot(): TemplateResult | typeof nothing;
+    render(): TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'titanium-multi-select-base': TitaniumMultiSelectBase;
+    }
+}
+//# sourceMappingURL=multi-select-base.d.ts.map