@rcarls/rc-search-bar 0.3.1 → 0.4.0

package/README.md

@@ -1,6 +1,7 @@
 # `@rcarls/rc-search-bar`
 
-Search field wrapper for a native `<input type="search">` with icon chrome, clear button, and debounced events.
+Search field and view wrapper for a native `<input type="search">` with icon chrome, a clear
+button, suggestions, and debounced events.
 
 Docs: [https://richardcarls.github.io/rc-webcomponents/components/rc-search-bar](https://richardcarls.github.io/rc-webcomponents/components/rc-search-bar).
 
@@ -43,8 +44,8 @@ import { RCSearchBar } from '@rcarls/rc-search-bar';
 ```
 
 The component's shadow CSS already strips the slotted input's native border,
-background, and outline so it blends into the wrapper chrome — no consumer reset
-needed.
+background, and outline so it blends into the wrapper chrome without a consumer
+reset.
 
 The native WebKit cancel button is suppressed automatically. Set
 `allow-native-clear` to restore it.
@@ -57,7 +58,10 @@ The native WebKit cancel button is suppressed automatically. Set
 
 | Property           | Attribute             | Type                  | Default          | Description                                                                             |
 | ------------------ | --------------------- | --------------------- | ---------------- | --------------------------------------------------------------------------------------- |
-| `value`            | —                     | `string`              | `''`             | Current search value; reads from the native input, host writes are silent               |
+| `variant`          | `variant`             | `'bar' \| 'view'`     | `'bar'`          | Presentation mode: docked field or expandable search view                               |
+| `open`             | `open`                | `boolean`             | `false`          | Controlled search view open state; host writes are silent                               |
+| `defaultOpen`      | `default-open`        | `boolean`             | `false`          | Initial uncontrolled search view open state                                             |
+| `value`            | None                  | `string`              | `''`             | Current search value; reads from the native input, host writes are silent               |
 | `defaultValue`     | `default-value`       | `string \| undefined` | `undefined`      | Initial uncontrolled value hint, applied once                                           |
 | `debounce`         | `debounce`            | `number`              | `200`            | Debounce window in ms for `rc-search-bar-input`; `0` dispatches synchronously           |
 | `clearLabel`       | `clear-label`         | `string`              | `'Clear search'` | Accessible label for the clear button                                                   |
@@ -79,6 +83,19 @@ The native WebKit cancel button is suppressed automatically. Set
 | `--rc-search-bar-height`         | `var(--rc-control-block-size, 2.5rem)`      | Wrapper block size                        |
 | `--rc-search-bar-padding-inline` | `var(--rc-control-padding-inline, 0.75rem)` | Wrapper horizontal padding                |
 | `--rc-search-bar-gap`            | `var(--rc-control-gap, 0.25em)`             | Gap between icon, input, and clear button |
+| `--rc-search-bar-input-color`    | inherit                                     | Input text color                          |
+| `--rc-search-bar-input-font-family` | inherit                                  | Input font family                         |
+| `--rc-search-bar-input-font-size` | inherit                                    | Input font size                           |
+| `--rc-search-bar-view-bg`        | `var(--rc-search-bar-bg)`                   | Search view panel background              |
+| `--rc-search-bar-view-color`     | `var(--rc-search-bar-color)`                | Search view panel text color              |
+| `--rc-search-bar-view-radius`    | `var(--rc-search-bar-radius)`               | Search view panel radius                  |
+| `--rc-search-bar-view-shadow`    | `var(--rc-search-bar-shadow)`               | Search view panel elevation               |
+| `--rc-search-bar-view-border`    | `var(--rc-search-bar-border)`               | Search view panel border                  |
+| `--rc-search-bar-view-offset`    | `0.25rem`                                   | Gap between the search bar and the view panel below it |
+| `--rc-search-bar-view-padding-block` | `0.5rem`                                | Search view suggestion list block padding |
+| `--rc-search-bar-suggestion-min-block-size` | `2.75rem`                         | Datalist-derived suggestion row minimum block size |
+| `--rc-search-bar-suggestion-padding-inline` | `1rem`                            | Datalist-derived suggestion inline padding |
+| `--rc-search-bar-suggestion-hover-bg` | `ButtonFace`                         | Datalist-derived suggestion hover/focus background |
 
 ### CSS parts
 
@@ -86,7 +103,11 @@ The native WebKit cancel button is suppressed automatically. Set
 | --------- | ------------- | ------------------------------------ |
 | `root`    | wrapper `div` | The field chrome                     |
 | `leading` | `span`        | Wrapper around the leading icon slot |
+| `trailing` | `span`       | Wrapper around the trailing slot     |
 | `clear`   | `button`      | The clear button                     |
+| `view`    | `div`         | Search view panel                    |
+| `suggestions` | `div`     | Suggestions container                |
+| `suggestion` | `button`   | Datalist-derived suggestion button   |
 
 ### Slots
 
@@ -96,19 +117,33 @@ The native WebKit cancel button is suppressed automatically. Set
 | `leading`    | Decorative leading icon; mark it `aria-hidden="true"`                     |
 | `clear-icon` | Optional glyph replacing the default ✕ in the clear button                |
 | `trailing`   | Optional content after the clear button (supplementary badges or actions) |
+| `suggestions` | Rich search view suggestions; takes precedence over datalist suggestions |
 
 ### Events
 
 | Event                 | Detail              | Description                                                                  |
 | --------------------- | ------------------- | ---------------------------------------------------------------------------- |
-| `rc-search-bar-input` | `{ value: string }` | Debounced after typing; fired immediately (pending timer cancelled) on clear |
+| `rc-search-bar-input` | `{ value: string }` | Debounced after typing; fired immediately (pending timer canceled) on clear |
 | `rc-search-bar-clear` | `{}`                | Fired when the clear button is activated                                     |
+| `rc-search-bar-toggle` | `{ open: boolean }` | Fired when user interaction opens or closes the search view                  |
+| `rc-search-bar-suggestion-select` | `{ value: string, label: string }` | Fired when a datalist-derived suggestion is activated |
+
+### Search view suggestions
+
+Use `variant="view"` for the expandable search view. Rich Material-style
+suggestions should be rendered in the `suggestions` slot. For simple text
+suggestions, the component reads the native input's `list` attribute and renders
+the associated `<datalist><option>` values when the slot is empty.
+
+`<datalist>` remains a progressive-enhancement path with browser-dependent
+styling and accessibility behavior; prefer slotted suggestions when rows need
+icons, supporting text, actions, or stronger AT/styling control.
 
 ---
 
 ## Accessibility notes
 
-- The component writes no ARIA to the input — `type="search"` already exposes
+- The component writes no ARIA to the input because `type="search"` already exposes
   the `searchbox` role, and author labels are never overwritten. Label the
   input with `label[for]`, a wrapping `<label>`, or `aria-label`.
 - The component adds no `role="search"` landmark; wrap in `<search>` or

package/dist/custom-elements.json

@@ -110,6 +110,56 @@
             {
               "description": "Input text color (inherits when unset)",
               "name": "--rc-search-bar-input-color"
+            },
+            {
+              "description": "Search view panel background",
+              "name": "--rc-search-bar-view-bg",
+              "default": "var(--rc-search-bar-bg)"
+            },
+            {
+              "description": "Search view panel text color",
+              "name": "--rc-search-bar-view-color",
+              "default": "var(--rc-search-bar-color)"
+            },
+            {
+              "description": "Search view panel radius",
+              "name": "--rc-search-bar-view-radius",
+              "default": "var(--rc-search-bar-radius)"
+            },
+            {
+              "description": "Search view panel shadow",
+              "name": "--rc-search-bar-view-shadow",
+              "default": "var(--rc-search-bar-shadow)"
+            },
+            {
+              "description": "Search view panel border",
+              "name": "--rc-search-bar-view-border",
+              "default": "var(--rc-search-bar-border)"
+            },
+            {
+              "description": "Gap between the search bar and the view panel below it",
+              "name": "--rc-search-bar-view-offset",
+              "default": "0.25rem"
+            },
+            {
+              "description": "Search view suggestion list block padding",
+              "name": "--rc-search-bar-view-padding-block",
+              "default": "0.5rem"
+            },
+            {
+              "description": "Datalist-derived suggestion row minimum block size",
+              "name": "--rc-search-bar-suggestion-min-block-size",
+              "default": "2.75rem"
+            },
+            {
+              "description": "Datalist-derived suggestion inline padding",
+              "name": "--rc-search-bar-suggestion-padding-inline",
+              "default": "1rem"
+            },
+            {
+              "description": "Datalist-derived suggestion hover/focus background",
+              "name": "--rc-search-bar-suggestion-hover-bg",
+              "default": "ButtonFace"
             }
           ],
           "cssParts": [
@@ -128,6 +178,18 @@
             {
               "description": "The clear button",
               "name": "clear"
+            },
+            {
+              "description": "Search view panel",
+              "name": "view"
+            },
+            {
+              "description": "Suggestions container",
+              "name": "suggestions"
+            },
+            {
+              "description": "Datalist-derived suggestion button",
+              "name": "suggestion"
             }
           ],
           "slots": [
@@ -146,9 +208,24 @@
             {
               "description": "Optional glyph replacing the default clear glyph",
               "name": "clear-icon"
+            },
+            {
+              "description": "Rich search view suggestions; takes precedence over datalist-derived suggestions.",
+              "name": "suggestions"
             }
           ],
           "members": [
+            {
+              "kind": "field",
+              "name": "variant",
+              "type": {
+                "text": "RCSearchBarVariant"
+              },
+              "default": "'bar'",
+              "description": "Presentation mode: docked search bar or expandable search view.",
+              "attribute": "variant",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "debounce",
@@ -209,6 +286,33 @@
               "description": "Placeholder mirrored onto the native input.\n\nConsumer `placeholder` attribute is always honored.",
               "attribute": "placeholder"
             },
+            {
+              "kind": "field",
+              "name": "_open",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "_defaultOpen",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "_openInitialized",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
             {
               "kind": "field",
               "name": "_value",
@@ -273,6 +377,15 @@
               "privacy": "private",
               "default": "undefined"
             },
+            {
+              "kind": "field",
+              "name": "_$dataListRef",
+              "type": {
+                "text": "WeakRef<HTMLDataListElement> | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
             {
               "kind": "field",
               "name": "_hasInput",
@@ -318,6 +431,24 @@
               "privacy": "private",
               "default": "false"
             },
+            {
+              "kind": "field",
+              "name": "_hasSuggestionsSlot",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "_dataListSuggestions",
+              "type": {
+                "text": "RCSearchBarSuggestion[]"
+              },
+              "privacy": "private",
+              "default": "[]"
+            },
             {
               "kind": "field",
               "name": "_disabledHost",
@@ -353,14 +484,40 @@
               "name": "_disabledObserver",
               "privacy": "private",
               "readonly": true,
-              "default": "new MutationObserver(() => { const $input = this._$input(); if ($input) { this._inputDisabled = $input.disabled; } })"
+              "default": "new MutationObserver(() => { const $input = this._$input(); if ($input) { this._inputDisabled = $input.disabled; this._syncDataListSuggestions($input); } })"
+            },
+            {
+              "kind": "field",
+              "name": "_dataListObserver",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new MutationObserver(() => this._syncDataListSuggestions())"
             },
             {
               "kind": "field",
               "name": "_inputController",
               "privacy": "private",
               "readonly": true,
-              "default": "new NativeChildController<HTMLInputElement>(this, { selector: ':scope > input[type=\"search\"]', observe: true, onChange: ($input, $previousInput) => this._setupInput($input, $previousInput), onMissing: () => { if (import.meta.env.DEV) { warnMissingDirectChild(this, { selector: ':scope > input[type=\"search\"]', message: '[rc-search-bar] No direct child <input type=\"search\"> found. ' + 'Place a native search input inside <rc-search-bar>.', }); } }, })"
+              "default": "new NativeChildController<HTMLInputElement>(this, { selector: ':scope > input[type=\"search\"]', observe: { childList: true, attributes: true, attributeFilter: ['list'] }, onChange: ($input, $previousInput) => this._setupInput($input, $previousInput), onMissing: () => { if (import.meta.env.DEV) { warnMissingDirectChild(this, { selector: ':scope > input[type=\"search\"]', message: '[rc-search-bar] No direct child <input type=\"search\"> found. ' + 'Place a native search input inside <rc-search-bar>.', }); } }, })"
+            },
+            {
+              "kind": "field",
+              "name": "open",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether the search view panel is open. Host writes are silent.",
+              "attribute": "open",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "defaultOpen",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Initial uncontrolled search view open state.",
+              "attribute": "default-open"
             },
             {
               "kind": "field",
@@ -465,6 +622,12 @@
               "privacy": "private",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "_onNativeKeyDown",
+              "privacy": "private",
+              "readonly": true
+            },
             {
               "kind": "method",
               "name": "_scheduleInputEvent",
@@ -511,6 +674,91 @@
                 }
               ]
             },
+            {
+              "kind": "method",
+              "name": "_setUserOpen",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "open",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "showView",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Opens the search view and fires `rc-search-bar-toggle` when it changes."
+            },
+            {
+              "kind": "method",
+              "name": "closeView",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Closes the search view and fires `rc-search-bar-toggle` when it changes."
+            },
+            {
+              "kind": "method",
+              "name": "toggleView",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Toggles the search view and fires `rc-search-bar-toggle` when it changes."
+            },
+            {
+              "kind": "method",
+              "name": "_syncDataListSuggestions",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "$input",
+                  "default": "this._$input()"
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_selectDataListSuggestion",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "suggestion",
+                  "type": {
+                    "text": "RCSearchBarSuggestion"
+                  }
+                }
+              ]
+            },
             {
               "kind": "method",
               "name": "_handleClear",
@@ -532,6 +780,11 @@
               },
               "description": "Programmatically clears the value and fires rc-search-bar-clear + rc-search-bar-input."
             },
+            {
+              "kind": "method",
+              "name": "_renderSearchView",
+              "privacy": "private"
+            },
             {
               "kind": "method",
               "name": "_onLeadingSlotChange",
@@ -567,6 +820,24 @@
                   }
                 }
               ]
+            },
+            {
+              "kind": "method",
+              "name": "_onSuggestionsSlotChange",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "Event"
+                  }
+                }
+              ]
             }
           ],
           "events": [
@@ -577,6 +848,20 @@
               },
               "description": "Debounced after typing, immediate on clear; `detail: { value }`"
             },
+            {
+              "name": "rc-search-bar-toggle",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "When user interaction opens or closes the search view; `detail: { open }`"
+            },
+            {
+              "name": "rc-search-bar-suggestion-select",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "When a datalist-derived suggestion is activated; `detail: { value, label }`"
+            },
             {
               "name": "rc-search-bar-clear",
               "type": {
@@ -587,63 +872,88 @@
           ],
           "attributes": [
             {
+              "description": "Presentation mode: docked search bar or expandable search view.",
+              "name": "variant",
+              "type": {
+                "text": "RCSearchBarVariant"
+              },
+              "default": "'bar'",
+              "fieldName": "variant"
+            },
+            {
+              "description": "Debounce window in ms for `rc-search-bar-input`; `0` dispatches synchronously.",
               "name": "debounce",
               "type": {
                 "text": "number"
               },
               "default": "200",
-              "description": "Debounce window in ms for `rc-search-bar-input`; `0` dispatches synchronously.",
               "fieldName": "debounce"
             },
             {
+              "description": "Accessible label for the clear button.",
               "name": "clear-label",
               "type": {
                 "text": "string"
               },
               "default": "'Clear search'",
-              "description": "Accessible label for the clear button.",
               "fieldName": "clearLabel"
             },
             {
+              "description": "When set, leaves the browser's native WebKit cancel button visible.",
               "name": "allow-native-clear",
               "type": {
                 "text": "boolean"
               },
               "default": "false",
-              "description": "When set, leaves the browser's native WebKit cancel button visible.",
               "fieldName": "allowNativeClear"
             },
             {
+              "description": "When set, the clear button is visible whenever the input is focused.\n\nMatching the Apple HIG \"cancel\" pattern.\nConsider setting `clear-label=\"Cancel\"` in this mode.",
               "name": "show-clear-on-focus",
               "type": {
                 "text": "boolean"
               },
               "default": "false",
-              "description": "When set, the clear button is visible whenever the input is focused.\n\nMatching the Apple HIG \"cancel\" pattern.\nConsider setting `clear-label=\"Cancel\"` in this mode.",
               "fieldName": "showClearOnFocus"
             },
             {
+              "description": "Disables the component and mirrors the state to the slotted input.",
               "name": "disabled",
               "type": {
                 "text": "boolean"
               },
-              "description": "Disables the component and mirrors the state to the slotted input.",
               "fieldName": "disabled"
             },
             {
+              "description": "Placeholder mirrored onto the native input.\n\nConsumer `placeholder` attribute is always honored.",
               "name": "placeholder",
               "type": {
                 "text": "string | undefined"
               },
-              "description": "Placeholder mirrored onto the native input.\n\nConsumer `placeholder` attribute is always honored.",
               "fieldName": "placeholder"
             },
             {
+              "description": "Whether the search view panel is open. Host writes are silent.",
+              "name": "open",
+              "type": {
+                "text": "boolean"
+              },
+              "fieldName": "open"
+            },
+            {
+              "description": "Initial uncontrolled search view open state.",
+              "name": "default-open",
+              "type": {
+                "text": "boolean"
+              },
+              "fieldName": "defaultOpen"
+            },
+            {
+              "description": "Initial uncontrolled value hint. Applied once, and only when neither an\nauthor `value`, a host `value` write, nor user input owns the value.",
               "name": "default-value",
               "type": {
                 "text": "string | undefined"
               },
-              "description": "Initial uncontrolled value hint. Applied once, and only when neither an\nauthor `value`, a host `value` write, nor user input owns the value.",
               "fieldName": "defaultValue"
             }
           ],