rich-input 1.3.0 → 1.4.0

package/README.md

@@ -5,18 +5,20 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Custom Elements](https://img.shields.io/badge/Web_Components-Custom_Elements_v1-orange.svg)](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)
 
-The `<rich-input>` component is a rich input field that acts like a standard `<input type="text">` so users can type ordinary text or search terms, but enhances it with contextual autocomplete and in-input highlighting for structured `keyword:value` entries (such as `label:"We Play House Recordings" year:2026 playlist:"WPH Classics"`).
+The `<rich-input>` component is a rich input field that acts like a standard `<input type="text">` so users can type ordinary text or search terms, but enhances it with contextual autocomplete and in-input highlighting for structured queries with `keyword:value` filters, prefix `operators` (e.g. `-`), boolean `combinators` (e.g. `AND`, `OR`), and grouping `delimiters` (e.g. `()`), such as `(label:"We Play House Recordings" OR year:2026) AND -style:"Acid House"`.
 
 ---
 
 ## Features
 
 - **Standard Input Ergonomics**: Acts and feels like a regular `<input type="text">` with standard value access, selection ranges, and events.
-- **Dual Contextual Autocomplete**:
-  - **Keywords**: Typing at the start of a token (e.g. typing `a`) suggests configured keywords like `artist:` and `style:`.
+- **Contextual Autocomplete**:
+  - **Keywords**: Typing at the start of a token or after an operator/delimiter (e.g. typing `a` or `-s`) suggests configured keywords like `artist:` and `-style:`.
+  - **Combinators**: Typing a configured boolean combinator (e.g. `A` or `O` when `combinators="AND OR"` is set) suggests `AND` and `OR`.
   - **Values**: Typing within a keyword value (e.g. `label:"K` or `label:K`) suggests matching options like `"Keinemusik"` and `"Kranky"`.
+- **Configurable Operators, Combinators & Delimiters**: Configure prefix operators (`operators="- ~ +"`), boolean combinators (`combinators="AND OR NOT"`), and grouping delimiter pairs (`delimiters="() [] {}"`) per instance via HTML attributes / JS properties, or globally via static properties on `RichInput`.
 - **Range-Based Positioning via OpaqueRange**: Positions autocomplete dropdown popovers anchored to the start of the active `OpaqueRange` (e.g. at the opening quotation mark of a value) using `range.getBoundingClientRect()`, rather than shifting with the cursor (with a hidden mirror-div fallback in unsupported browsers).
-- **Native In-Input Highlighting via CSS Custom Highlight API**: Highlights keyword values inside the `<input>` control using standard CSS rules like `::highlight(label)` or `::highlight(year)` without brittle mirror-div overlays.
+- **Native In-Input Highlighting via CSS Custom Highlight API**: Highlights keyword values, operators, combinators, delimiters, and invalid tokens inside the `<input>` control using standard CSS rules like `::highlight(label)`, `::highlight(rich-input-operator)`, `::highlight(rich-input-combinator)`, and `::highlight(rich-input-delimiter)` without brittle mirror-div overlays.
 - **Declarative Configuration via `<datalist>`**: Configure keywords and options purely in HTML by nesting standard `<datalist>` elements with `<option>` tags inside `<rich-input>`.
 - **Rich Option Markup**: Embed custom HTML markup (such as logos, images, icons, and avatars) directly inside `<option>` elements for rich, visual suggestion popovers.
 - **Form Associated**: Implements `static formAssociated = true` and `ElementInternals` to participate seamlessly in `<form>` submission, `FormData`, and form reset lifecycles.
@@ -36,8 +38,11 @@ The visual below illustrates the internal Shadow DOM elements, exposed CSS Shado
 
 - `<rich-input>`: The host custom element wrapping the control, datalists, and suggestions popover.
 - `::part(control)`: The outer input container enclosing the icon, input, and clear button.
-- `::part(icon)`: The default leading search magnifying glass SVG icon (fallback in `slot="leading"`).
+- `::part(icon)`: The leading icon element (defaults to a search magnifying glass, customizable via CSS `content` or `background`).
 - `::highlight(<keyword>)`: Target pseudo-element for styling keyword values via the CSS Custom Highlight API (e.g. `::highlight(label)`, `::highlight(year)`).
+- `::highlight(rich-input-operator)`: Target pseudo-element for styling keyword operators (e.g. `-` in `-style:"Acid House"`).
+- `::highlight(rich-input-combinator)`: Target pseudo-element for styling query combinators (e.g. `OR` in `artist:"Aphex Twin" OR label:"Defected"`).
+- `::highlight(rich-input-delimiter)`: Target pseudo-element for styling grouping delimiters (e.g. `(` and `)` in `(artist:"Aphex Twin" OR label:"Defected")`).
 - `::highlight(rich-input-keyword)`: Target pseudo-element for styling keyword prefixes (e.g. `label:`, `year:`).
 - `::highlight(rich-input-invalid)`: Target pseudo-element for marking unrecognized keywords or invalid keyword values (not in datalist) with a squiggly underline.
 - `::part(clear-button)`: The clear button (visible when text is present).
@@ -49,6 +54,7 @@ The visual below illustrates the internal Shadow DOM elements, exposed CSS Shado
 - `::part(suggestion-item-selected)`: The suggestion row matching the value currently echoed in the input.
 - `::part(suggestion-image)`: The circular logo, icon, or avatar image prepended to rich suggestions.
 - `::part(suggestion-keyword)`: The keyword label text inside a keyword suggestion.
+- `::part(suggestion-combinator)`: The combinator label text inside a combinator suggestion.
 - `::part(suggestion-value)`: The value label text inside a value suggestion.
 
 ---
@@ -77,10 +83,15 @@ Or via CDN:
 
 ### 2. Basic Usage
 
-Nest `<datalist>` elements inside `<rich-input>` to configure keywords and autocomplete suggestions:
+Nest `<datalist>` elements inside `<rich-input>` to configure keywords and autocomplete suggestions, and optionally configure `operators`, `combinators`, and `delimiters`:
 
 ```html
-<rich-input placeholder="Search music catalog...">
+<rich-input
+  operators="-"
+  combinators="AND OR"
+  delimiters="()"
+  placeholder="Search music catalog..."
+>
   <datalist id="label" label="Record Label">
     <option value="Defected"></option>
     <option value="House"></option>
@@ -99,21 +110,25 @@ Nest `<datalist>` elements inside `<rich-input>` to configure keywords and autoc
     <option value="2024"></option>
   </datalist>
 
-  <datalist id="playlist" label="Playlist">
-    <option value="WPH Classics"></option>
-    <option value="Late Night Grooves"></option>
+  <datalist id="style" label="Style">
+    <option value="Acid House"></option>
+    <option value="Deep House"></option>
+    <option value="Dub Techno"></option>
   </datalist>
 </rich-input>
 ```
 
 ---
 
-## Datalist Configuration
+## Datalist & Syntax Configuration
 
-Configuration is defined by standard HTML `<datalist>` elements placed inside the `<rich-input>` element:
+Configuration is defined by attributes on `<rich-input>` and standard HTML `<datalist>` elements placed inside the `<rich-input>` element:
 
 | Element / Attribute | Type | Description |
 |---|---|---|
+| `<rich-input operators="...">` | `string` | Optional space-separated list of single-character prefix operators (e.g. `operators="- ~ +"`). Defaults to `"-"` (negative filter). Set `operators=""` to disable operators. |
+| `<rich-input combinators="...">` | `string` | Optional space-separated list of boolean query combinators (e.g. `combinators="AND OR NOT"`). Defaults to `""` (empty array). |
+| `<rich-input delimiters="...">` | `string` | Optional space-separated list of two-character opening/closing delimiter pairs (e.g. `delimiters="() [] {}"`). Defaults to `"()"` (parentheses). Set `delimiters=""` to disable delimiters. |
 | `<datalist id="...">` | `string` | **Required.** The keyword identifier used in queries (e.g. `id="artist"` produces `artist:`). Case-insensitive. |
 | `<datalist label="...">` | `string` | Human-readable label displayed in suggestion headers. Defaults to capitalized `id`. |
 | `<datalist data-type="...">` | `string` | Optional data type (`"string"` or `"number"`). |
@@ -121,63 +136,55 @@ Configuration is defined by standard HTML `<datalist>` elements placed inside th
 | `<option label="...">` | `string` | Optional descriptive label shown alongside the value. |
 | `<option>` children | `Node` | Optional image (`<img>`) prepended to the suggested value. |
 
-Datalists can be added, updated, or removed dynamically at runtime; `<rich-input>` observes changes via `slotchange` and `MutationObserver`.
+Datalists and syntax attributes can be added, updated, or removed dynamically at runtime; `<rich-input>` observes changes via `attributeChangedCallback` and `MutationObserver`.
+
+### Configuring Operators, Combinators & Delimiters via JavaScript
+
+In addition to HTML attributes, you can configure `operators`, `combinators`, and `delimiters` per instance or globally on the `RichInput` class (which sets the default for newly created instances that do not specify a local override):
+
+```javascript
+import { RichInput } from '@bramus/rich-input';
+
+// Set global defaults for newly created <rich-input> elements
+RichInput.operators = ['-', '+'];
+RichInput.combinators = ['AND', 'OR', 'NOT'];
+RichInput.delimiters = ['()', '[]'];
+
+// Or configure an individual instance via properties or methods
+const input = document.querySelector('rich-input');
+input.operators = ['-'];
+input.combinators = ['AND', 'OR'];
+input.delimiters = ['()'];
+
+// Reset an instance or global setting back to defaults by assigning null
+input.operators = null;
+```
 
 ---
 
-## Rich Option Markup
+## Rich Option Markup (`<img>` Support)
 
-`<rich-input>` supports rich HTML markup inside `<option>` elements. For example, for record labels or artists, you can prepend a logo image:
+Options inside a `<datalist>` can include an `<img>` element to display thumbnails, avatars, or record label logos in the autocomplete suggestions popover:
 
 ```html
-<rich-input placeholder="Search...">
-  <datalist id="label" label="Record Label">
-    <option value="Defected">
-      <img src="assets/defected.jpg" height="50" width="50" alt="Defected Logo">
-      Defected
-    </option>
-    <option value="House">
-      <img src="assets/house.jpg" height="50" width="50" alt="House Logo">
-      House
-    </option>
-    <option value="Keinemusik">
-      <img src="assets/keinemusik.jpg" height="50" width="50" alt="Keinemusik Logo">
-      Keinemusik
-    </option>
-    <option value="Kranky">
-      <img src="assets/kranky.jpg" height="50" width="50" alt="Kranky Logo">
-      Kranky
-    </option>
-    <option value="Madhouse Records">
-      <img src="assets/madhouse-records.jpg" height="50" width="50" alt="Madhouse Records Logo">
-      Madhouse Records
-    </option>
-    <option value="Ninja Tune">
-      <img src="assets/ninja-tune.jpg" height="50" width="50" alt="Ninja Tune Logo">
-      Ninja Tune
-    </option>
-    <option value="Warp Records">
-      <img src="assets/warp-records.png" height="50" width="50" alt="Warp Records Logo">
-      Warp Records
-    </option>
-    <option value="We Play House Recordings">
-      <img src="assets/we-play-house-recordings.jpg" height="50" width="50" alt="We Play House Recordings Logo">
-      We Play House Recordings
-    </option>
-    <option value="XL Recordings">
-      <img src="assets/xl-recordings.jpg" height="50" width="50" alt="XL Recordings Logo">
-      XL Recordings
-    </option>
-  </datalist>
-</rich-input>
+<datalist id="label" label="Record Label">
+  <option value="We Play House Recordings">
+    <img src="assets/we-play-house-recordings.jpg" height="50" width="50" alt="WPH">
+    We Play House Recordings
+  </option>
+  <option value="Defected">
+    <img src="assets/defected.jpg" height="50" width="50" alt="Defected">
+    Defected
+  </option>
+</datalist>
 ```
 
-When suggesting values for `label:`, `<rich-input>` sniffs the image inside the `<option>`, renders it alongside the option's text content, and exposes `::part(suggestion-image)` for external CSS styling (e.g. as a `1em` circular icon):
+When `<rich-input>` parses a `<datalist>`, it clones any `<img>` found inside `<option>` and renders it inside the corresponding suggestion row with `part="suggestion-image"`. You can style these images from your stylesheet using `::part(suggestion-image)`:
 
 ```css
 rich-input::part(suggestion-image) {
-  width: 1em;
-  height: 1em;
+  width: 2.5em;
+  height: 2.5em;
   border-radius: 50%;
   object-fit: cover;
 }
@@ -185,43 +192,22 @@ rich-input::part(suggestion-image) {
 
 ---
 
-## Custom Leading Icon & Slots
-
-`<rich-input>` provides named slots to customize elements inside the control:
+## Customizing the Leading Icon via `::part(icon)`
 
-- **`slot="leading"`**: Replace the leading icon. The default magnifying glass SVG is provided as fallback content inside the slot, so passing a custom element into `slot="leading"` automatically replaces it without needing CSS overrides.
-- **`slot="trailing"`**: Add controls or elements after the clear button (e.g. submit button, voice input, keyboard shortcut badge).
+By default, `<rich-input>` renders a leading search magnifying glass icon exposed as `::part(icon)`. You can customize or replace this icon using either the CSS `content` property (for example, to display an emoji) or the CSS `background` property (to display a custom SVG or image):
 
-### Passing a Custom Leading Icon
-
-Provide your own SVG or image with `slot="leading"`:
+```css
+/* Option 1: Show an emoji or text via the CSS content property */
+rich-input::part(icon) {
+  content: "🎵";
+}
 
-```html
-<rich-input placeholder="Search music catalog...">
-  <!-- Custom leading music icon -->
-  <svg slot="leading" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
-    <path d="M9 18V5l12-2v13"></path>
-    <circle cx="6" cy="18" r="3"></circle>
-    <circle cx="18" cy="16" r="3"></circle>
-  </svg>
-
-  <datalist id="genre" label="Genre">
-    <option value="House"></option>
-    <option value="Techno"></option>
-  </datalist>
-</rich-input>
+/* Option 2: Show a custom SVG/image via the CSS background property */
+rich-input::part(icon) {
+  background: url("music-note.svg") no-repeat center / contain;
+}
 ```
 
-When an element with `slot="leading"` is supplied, the default search magnifying glass icon is automatically suppressed. If no slotted element is provided, the default magnifying glass icon renders as fallback.
-
-### Available Slots
-
-| Slot Name | Description |
-|---|---|
-| `leading` | Custom leading icon or content. Defaults to the search magnifying glass icon (`::part(icon)`). |
-| `trailing` | Custom content rendered after the clear button. |
-| *(default)* | Unnamed slot where `<datalist>` configuration elements are placed (visually hidden). |
-
 ---
 
 ## The OpaqueRange API
@@ -275,6 +261,24 @@ Values corresponding to configured keywords are registered into the global `CSS.
   color: oklch(0.32 0.14 320);
 }
 
+/* Generic prefix highlight for operators (e.g. "-" in "-style:Acid") */
+::highlight(rich-input-operator) {
+  color: #e11d48;
+  text-shadow: 0 0 1px rgba(225, 29, 72, 0.2);
+}
+
+/* Generic highlight for combinators (e.g. "OR" in "artist:Aphex OR label:Defected") */
+::highlight(rich-input-combinator) {
+  color: #7c3aed;
+  text-shadow: 0 0 1px rgba(124, 58, 237, 0.2);
+}
+
+/* Generic highlight for delimiters (e.g. "(" and ")") */
+::highlight(rich-input-delimiter) {
+  color: #0284c7;
+  text-shadow: 0 0 1px rgba(2, 132, 199, 0.25);
+}
+
 /* Generic prefix highlight for keyword labels (e.g. "label:", "year:") */
 ::highlight(rich-input-keyword) {
   color: #64748b;
@@ -345,7 +349,7 @@ rich-input::part(suggestion-item-active) {
 |---|---|
 | `::part(control)` | The wrapper container enclosing the search icon, input, and clear button |
 | `::part(input)` | The internal native `<input type="text">` |
-| `::part(icon)` | The default leading search icon SVG (fallback in `slot="leading"`) |
+| `::part(icon)` | The leading icon element (defaults to a search magnifying glass, customizable via CSS `content` or `background`) |
 | `::part(clear-button)` | The clear button (visible when text is present) |
 | `::part(popover)` | The autocomplete popover container |
 | `::part(suggestions-header)` | The header bar at the top of the popover |
@@ -354,6 +358,7 @@ rich-input::part(suggestion-item-active) {
 | `::part(suggestion-item-active)` | The currently focused / hovered suggestion item |
 | `::part(suggestion-item-selected)` | The suggestion item matching the value currently echoed in the input |
 | `::part(suggestion-keyword)` | Keyword name element in suggestion items |
+| `::part(suggestion-combinator)` | Combinator name element in suggestion items |
 | `::part(suggestion-value)` | Value element in suggestion items |
 | `::part(suggestion-content)` | The content container inside each suggestion item |
 | `::part(suggestion-image)` | Image or icon element rendered inside rich suggestion items |
@@ -365,6 +370,12 @@ rich-input::part(suggestion-item-active) {
 ### Properties
 
 - `value` (`string`): Gets or sets the search input value. Updates highlights and form value automatically.
+- `operators` (`string[] | string`): Gets or sets the prefix operators (e.g. `['-', '~', '+']` or `'- ~ +'`) for this instance. Defaults to `RichInput.operators` (`['-']`). Setting to `null` clears the instance override and falls back to the global configuration.
+- `RichInput.operators` (`string[] | string`): Static getter and setter to configure global default operators for all instances without a local override.
+- `combinators` (`string[] | string`): Gets or sets the query combinators (e.g. `['AND', 'OR', 'NOT']` or `'AND OR NOT'`) for this instance. Defaults to `RichInput.combinators` (`[]`). Setting to `null` clears the instance override and falls back to the global configuration.
+- `RichInput.combinators` (`string[] | string`): Static getter and setter to configure global default combinators for all instances without a local override.
+- `delimiters` (`string[] | string`): Gets or sets the delimiter pairs (e.g. `['()', '{}', '[]']` or `'{} () []'`) for this instance. Defaults to `RichInput.delimiters` (`['()']`). Setting to `null` clears the instance override and falls back to the global configuration.
+- `RichInput.delimiters` (`string[] | string`): Static getter and setter to configure global default delimiter pairs for all instances without a local override.
 - `placeholder` (`string`): Gets or sets the input placeholder text.
 - `disabled` (`boolean`): Disables or enables the input control.
 - `name` (`string`): Form field name when submitted inside a `<form>`.
@@ -372,19 +383,30 @@ rich-input::part(suggestion-item-active) {
 
 ### Methods
 
-- `getParsedQuery()`: Returns a parsed object representing the search query:
+- `getParsedQuery()`: Returns a parsed object containing the `raw` query string and an ordered `tokens` array (`keyword`, `combinator`, `delimiter`, `text`, and `whitespace` tokens):
   ```json
   {
-    "raw": "label:\"We Play House Recordings\" year:2026 chicago house",
-    "text": "chicago house",
-    "keywords": {
-      "label": ["We Play House Recordings"],
-      "year": ["2026"]
-    },
-    "tokens": [...]
+    "raw": "(artist:\"Aphex Twin\" OR year:2026) AND -style:\"Acid House\"",
+    "tokens": [
+      { "type": "delimiter", "raw": "(", "delimiter": "(", "pair": "()", "role": "open", "start": 0, "end": 1 },
+      { "type": "keyword", "operator": null, "keyword": "artist", "innerValue": "Aphex Twin", "start": 1, "end": 20 },
+      { "type": "whitespace", "raw": " ", "start": 20, "end": 21 },
+      { "type": "combinator", "raw": "OR", "combinator": "OR", "start": 21, "end": 23 },
+      { "type": "whitespace", "raw": " ", "start": 23, "end": 24 },
+      { "type": "keyword", "operator": null, "keyword": "year", "innerValue": "2026", "start": 24, "end": 33 },
+      { "type": "delimiter", "raw": ")", "delimiter": ")", "pair": "()", "role": "close", "start": 33, "end": 34 },
+      { "type": "whitespace", "raw": " ", "start": 34, "end": 35 },
+      { "type": "combinator", "raw": "AND", "combinator": "AND", "start": 35, "end": 38 },
+      { "type": "whitespace", "raw": " ", "start": 38, "end": 39 },
+      { "type": "keyword", "operator": "-", "keyword": "style", "innerValue": "Acid House", "start": 39, "end": 58 }
+    ]
   }
   ```
 - `getKeywords()`: Returns an array of configured keyword definitions from the datalists.
+- `getOperators()` / `setOperators(operators)`: Gets or sets the operators for this instance (or globally via `RichInput.getOperators()` / `RichInput.setOperators(operators)`).
+- `getCombinators()` / `setCombinators(combinators)`: Gets or sets the combinators for this instance (or globally via `RichInput.getCombinators()` / `RichInput.setCombinators(combinators)`).
+- `getDelimiters()` / `setDelimiters(delimiters)`: Gets or sets the delimiters for this instance (or globally via `RichInput.getDelimiters()` / `RichInput.setDelimiters(delimiters)`).
+- `getActiveValueRanges()` / `getActiveKeywordRanges()` / `getActiveOperatorRanges()` / `getActiveCombinatorRanges()` / `getActiveDelimiterRanges()` / `getActiveInvalidRanges()`: Returns the active highlight range descriptors for each token category.
 - `focus(options)`: Focuses the internal input.
 - `blur()`: Removes focus from the internal input.
 - `select()`: Selects all text inside the input.
@@ -396,7 +418,7 @@ rich-input::part(suggestion-item-active) {
 - `change`: Dispatched on blur or when a search change is committed.
 - `search`: Dispatched when the user presses `Enter` with suggestions closed.
 - `rich-input-select`: Dispatched when an autocomplete suggestion is selected.
-  - `event.detail`: `{ type, keyword, value, label, query }`
+  - `event.detail`: `{ type, operator, keyword, value, label, query }`
 
 ---