rich-input 1.0.0

package/index.js

@@ -0,0 +1,32 @@
+/**
+ * <rich-input> entry point
+ * Defines <rich-input> custom element and exports RichInput class & parser utilities.
+ */
+
+import { RichInput } from './components/rich-input.js';
+import { parseSearchTokens, parseSearchQuery, getCaretContext, getSuggestions, applySuggestion } from './utils/query-parser.js';
+import { highlightManager, isOpaqueRangeSupported, isHighlightSupported } from './utils/highlights.js';
+import { getCaretCoordinates, getRangeCoordinates, positionPopover } from './utils/positioning.js';
+
+if (typeof customElements !== 'undefined') {
+  if (!customElements.get('rich-input')) {
+    customElements.define('rich-input', RichInput);
+  }
+}
+
+export {
+  RichInput,
+  parseSearchTokens,
+  parseSearchQuery,
+  getCaretContext,
+  getSuggestions,
+  applySuggestion,
+  highlightManager,
+  isOpaqueRangeSupported,
+  isHighlightSupported,
+  getCaretCoordinates,
+  getRangeCoordinates,
+  positionPopover,
+};
+
+export default RichInput;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "rich-input",
+  "version": "1.0.0",
+  "description": "A rich input field with keyword-based autocomplete and in-input highlighting powered by <datalist>, OpaqueRange, and the Custom Highlight API",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "keywords": [
+    "rich-input",
+    "custom-element",
+    "web-components",
+    "opaque-range",
+    "custom-highlight-api",
+    "autocomplete",
+    "keyword-search",
+    "search-input"
+  ],
+  "author": {
+    "name": "Bramus Van Damme",
+    "email": "bramus@bram.us",
+    "url": "https://www.bram.us/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bramus/rich-input.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bramus/rich-input/issues"
+  },
+  "homepage": "https://github.com/bramus/rich-input#readme"
+}

package/utils/highlights.js

@@ -0,0 +1,101 @@
+/**
+ * Highlight manager for <rich-input>
+ * Uses the OpaqueRange API and CSS Custom Highlight API to apply syntax highlighting.
+ */
+
+export const isOpaqueRangeSupported =
+  typeof HTMLInputElement !== 'undefined' &&
+  typeof HTMLInputElement.prototype.createValueRange === 'function';
+
+export const isHighlightSupported =
+  typeof window !== 'undefined' &&
+  typeof window.Highlight !== 'undefined' &&
+  typeof CSS !== 'undefined' &&
+  'highlights' in CSS;
+
+class HighlightRegistryManager {
+  constructor() {
+    this.instances = new Set();
+    this.registeredKeywords = new Set();
+  }
+
+  register(instance) {
+    this.instances.add(instance);
+  }
+
+  unregister(instance) {
+    this.instances.delete(instance);
+    this.syncAll();
+  }
+
+  recordKeyword(keyword) {
+    if (keyword) {
+      this.registeredKeywords.add(keyword.toLowerCase());
+    }
+  }
+
+  syncAll() {
+    if (!isHighlightSupported || !isOpaqueRangeSupported) return;
+
+    // Aggregate ranges across all active instances
+    const rangesByKeyword = new Map();
+    const allKeywordRanges = [];
+    const allValueRanges = [];
+
+    for (const inst of this.instances) {
+      const instanceRanges = inst.getActiveHighlightRanges();
+      for (const [kw, data] of instanceRanges.entries()) {
+        const kwLower = kw.toLowerCase();
+        this.registeredKeywords.add(kwLower);
+
+        if (!rangesByKeyword.has(kwLower)) {
+          rangesByKeyword.set(kwLower, []);
+        }
+
+        if (data.valueRanges && data.valueRanges.length > 0) {
+          rangesByKeyword.get(kwLower).push(...data.valueRanges);
+          allValueRanges.push(...data.valueRanges);
+        }
+
+        if (data.keywordRanges && data.keywordRanges.length > 0) {
+          allKeywordRanges.push(...data.keywordRanges);
+        }
+      }
+    }
+
+    // 1. Set/update individual keyword highlights (e.g. ::highlight(label))
+    for (const kw of this.registeredKeywords) {
+      const ranges = rangesByKeyword.get(kw);
+      if (ranges && ranges.length > 0) {
+        try {
+          CSS.highlights.set(kw, new Highlight(...ranges));
+        } catch (e) {
+          console.warn(`[rich-input] Failed to register highlight for "${kw}":`, e);
+        }
+      } else {
+        CSS.highlights.delete(kw);
+      }
+    }
+
+    // 2. Set generic highlights
+    if (allKeywordRanges.length > 0) {
+      try {
+        const kwHl = new Highlight(...allKeywordRanges);
+        CSS.highlights.set('rich-input-keyword', kwHl);
+      } catch (e) {}
+    } else {
+      CSS.highlights.delete('rich-input-keyword');
+    }
+
+    if (allValueRanges.length > 0) {
+      try {
+        const valHl = new Highlight(...allValueRanges);
+        CSS.highlights.set('rich-input-value', valHl);
+      } catch (e) {}
+    } else {
+      CSS.highlights.delete('rich-input-value');
+    }
+  }
+}
+
+export const highlightManager = new HighlightRegistryManager();

package/utils/positioning.js

@@ -0,0 +1,111 @@
+/**
+ * Caret measurement and popover positioning for <rich-input>
+ * Uses OpaqueRange.getBoundingClientRect() with input fallback.
+ */
+
+/**
+ * Gets caret or range coordinates relative to viewport.
+ * Accepts either an OpaqueRange instance or a character offset number.
+ * @param {HTMLInputElement} input
+ * @param {number|OpaqueRange} [target] Caret position number or OpaqueRange
+ * @returns {{ left: number, top: number, bottom: number, height: number, isCaret: boolean }}
+ */
+export function getCaretCoordinates(input, target) {
+  const inputRect = input.getBoundingClientRect();
+  let rect = null;
+  let tempRange = null;
+
+  if (target && typeof target.getBoundingClientRect === 'function') {
+    try {
+      const r = target.getBoundingClientRect();
+      if (r.height > 0 || r.width > 0 || r.left > 0) {
+        rect = r;
+      }
+    } catch (e) {}
+  } else if (typeof input.createValueRange === 'function' && input.value.length > 0) {
+    try {
+      const pos = Math.max(0, Math.min(typeof target === 'number' ? target : 0, input.value.length));
+      tempRange = input.createValueRange(pos, pos);
+      const r = tempRange.getBoundingClientRect();
+      if (r.height > 0 || r.width > 0 || r.left > 0) {
+        rect = r;
+      }
+    } catch (e) {}
+  }
+
+  // Clean up temporary measurement range
+  if (tempRange) {
+    try {
+      tempRange.disconnect();
+    } catch (e) {}
+  }
+
+  if (rect) {
+    // Keep caret left within input bounds
+    const left = Math.max(inputRect.left, Math.min(rect.left, inputRect.right));
+    const bottom = rect.bottom > 0 ? rect.bottom : inputRect.bottom;
+    const top = rect.top > 0 ? rect.top : inputRect.top;
+    return {
+      left,
+      top,
+      bottom,
+      height: rect.height || inputRect.height,
+      isCaret: true,
+    };
+  }
+
+  return {
+    left: inputRect.left,
+    top: inputRect.top,
+    bottom: inputRect.bottom,
+    height: inputRect.height,
+    isCaret: false,
+  };
+}
+
+/**
+ * Alias for getCaretCoordinates that clearly conveys range support.
+ */
+export const getRangeCoordinates = getCaretCoordinates;
+
+/**
+ * Positions popover at caret or input element.
+ * @param {HTMLElement} popover
+ * @param {{ left: number, top: number, bottom: number, height: number }} caretCoords
+ * @param {HTMLInputElement} inputElement
+ */
+export function positionPopover(popover, caretCoords, inputElement) {
+  if (!popover) return;
+
+  const popoverWidth = popover.offsetWidth || 280;
+  const popoverHeight = popover.offsetHeight || 220;
+
+  const viewportWidth = window.innerWidth;
+  const viewportHeight = window.innerHeight;
+
+  let left = caretCoords.left;
+
+  // Viewport right edge clamp
+  if (left + popoverWidth > viewportWidth - 12) {
+    left = viewportWidth - popoverWidth - 12;
+  }
+  // Viewport left edge clamp
+  if (left < 12) {
+    left = 12;
+  }
+
+  let top = caretCoords.bottom + 6;
+
+  // Viewport bottom edge flip
+  if (top + popoverHeight > viewportHeight - 12) {
+    const spaceAbove = caretCoords.top - 6;
+    if (spaceAbove >= popoverHeight) {
+      top = spaceAbove - popoverHeight;
+    }
+  }
+
+  popover.style.margin = '0';
+  popover.style.inset = 'auto';
+  popover.style.left = `${Math.round(left)}px`;
+  popover.style.top = `${Math.round(top)}px`;
+}

package/utils/query-parser.js

@@ -0,0 +1,344 @@
+/**
+ * Query tokenizer and parser for <rich-input>
+ * Handles keyword:value tokenization, caret context inspection, and suggestion application.
+ */
+
+/**
+ * Parses raw search input into token objects.
+ * @param {string} inputStr
+ * @returns {Array<Object>}
+ */
+export function parseSearchTokens(inputStr) {
+  if (typeof inputStr !== 'string') return [];
+
+  const tokens = [];
+  let i = 0;
+  const len = inputStr.length;
+
+  while (i < len) {
+    // 1. Whitespace
+    if (/\s/.test(inputStr[i])) {
+      const wsStart = i;
+      while (i < len && /\s/.test(inputStr[i])) {
+        i++;
+      }
+      tokens.push({
+        type: 'whitespace',
+        raw: inputStr.slice(wsStart, i),
+        start: wsStart,
+        end: i,
+      });
+      continue;
+    }
+
+    const tokenStart = i;
+
+    // 2. Check for keyword pattern: [a-zA-Z0-9_-]+:
+    const remaining = inputStr.slice(i);
+    const colonMatch = remaining.match(/^([a-zA-Z0-9_-]+):/);
+
+    if (colonMatch) {
+      const keyword = colonMatch[1];
+      const keywordStart = i;
+      const colonIndex = i + keyword.length;
+      i += colonMatch[0].length; // Move index past ':'
+
+      const valueStart = i;
+      let quoted = false;
+      let quoteChar = '';
+      let isClosed = false;
+      let innerStart = i;
+      let innerEnd = i;
+
+      if (i < len && (inputStr[i] === '"' || inputStr[i] === "'")) {
+        // Quoted string value
+        quoted = true;
+        quoteChar = inputStr[i];
+        i++; // skip opening quote
+        innerStart = i;
+
+        while (i < len && inputStr[i] !== quoteChar) {
+          i++;
+        }
+        innerEnd = i;
+
+        if (i < len && inputStr[i] === quoteChar) {
+          isClosed = true;
+          i++; // skip closing quote
+        }
+      } else {
+        // Unquoted value: until next whitespace or end
+        innerStart = i;
+        while (i < len && !/\s/.test(inputStr[i])) {
+          i++;
+        }
+        innerEnd = i;
+        isClosed = true;
+      }
+
+      const rawValue = inputStr.slice(valueStart, i);
+      const innerValue = inputStr.slice(innerStart, innerEnd);
+
+      tokens.push({
+        type: 'keyword',
+        raw: inputStr.slice(tokenStart, i),
+        start: tokenStart,
+        end: i,
+        keyword,
+        keywordLower: keyword.toLowerCase(),
+        keywordStart,
+        keywordEnd: colonIndex + 1,
+        colonIndex,
+        valueStart,
+        valueEnd: i,
+        rawValue,
+        innerValue,
+        innerStart,
+        innerEnd,
+        quoted,
+        quoteChar,
+        isClosed,
+      });
+    } else {
+      // 3. Plain text token (single word or unfinished keyword)
+      while (i < len && !/\s/.test(inputStr[i])) {
+        i++;
+      }
+      tokens.push({
+        type: 'text',
+        raw: inputStr.slice(tokenStart, i),
+        start: tokenStart,
+        end: i,
+      });
+    }
+  }
+
+  return tokens;
+}
+
+/**
+ * Parses search query into a structured object with keywords and free text.
+ * @param {string} inputStr
+ * @returns {{ raw: string, text: string, keywords: Record<string, string[]>, tokens: Array<Object> }}
+ */
+export function parseSearchQuery(inputStr) {
+  const tokens = parseSearchTokens(inputStr);
+  const keywords = {};
+  const textWords = [];
+
+  for (const token of tokens) {
+    if (token.type === 'keyword') {
+      const kw = token.keywordLower;
+      if (!keywords[kw]) {
+        keywords[kw] = [];
+      }
+      keywords[kw].push(token.innerValue);
+    } else if (token.type === 'text') {
+      textWords.push(token.raw);
+    }
+  }
+
+  return {
+    raw: inputStr,
+    text: textWords.join(' '),
+    keywords,
+    tokens,
+  };
+}
+
+/**
+ * Determines caret context and what autocomplete suggestions are appropriate.
+ * @param {string} inputStr
+ * @param {number} caretPos
+ * @param {Map<string, Object>|Object} configuredKeywords
+ * @returns {Object}
+ */
+export function getCaretContext(inputStr, caretPos, configuredKeywords) {
+  if (typeof inputStr !== 'string') inputStr = '';
+  caretPos = Math.max(0, Math.min(caretPos || 0, inputStr.length));
+
+  const tokens = parseSearchTokens(inputStr);
+
+  // Find token at caret
+  let activeToken = null;
+  for (const token of tokens) {
+    if (caretPos >= token.start && caretPos <= token.end) {
+      activeToken = token;
+      break;
+    }
+  }
+
+  // If caret is in whitespace or between tokens
+  if (!activeToken || activeToken.type === 'whitespace') {
+    // Check if the previous token was a colon without value or if we're in open space
+    return {
+      mode: 'none',
+      caretPos,
+      tokens,
+    };
+  }
+
+  // 1. Caret is within a keyword token
+  if (activeToken.type === 'keyword') {
+    if (caretPos <= activeToken.colonIndex) {
+      // User is editing the keyword name
+      const query = inputStr.slice(activeToken.start, caretPos);
+      return {
+        mode: 'keyword',
+        query,
+        replaceStart: activeToken.start,
+        replaceEnd: activeToken.colonIndex + 1,
+        caretPos,
+        token: activeToken,
+        tokens,
+      };
+    } else {
+      // User is editing the keyword value
+      const isQuoted = activeToken.quoted;
+      const innerStart = activeToken.innerStart;
+      const innerEnd = activeToken.innerEnd;
+      const valuePrefix = inputStr.slice(innerStart, Math.min(caretPos, innerEnd));
+
+      return {
+        mode: 'value',
+        keyword: activeToken.keyword,
+        keywordLower: activeToken.keywordLower,
+        valuePrefix,
+        quoted: isQuoted,
+        quoteChar: activeToken.quoteChar || '"',
+        isClosed: activeToken.isClosed,
+        replaceStart: activeToken.valueStart,
+        replaceEnd: activeToken.valueEnd,
+        caretPos,
+        token: activeToken,
+        tokens,
+      };
+    }
+  }
+
+  // 2. Caret is within a plain text token
+  if (activeToken.type === 'text') {
+    const query = inputStr.slice(activeToken.start, caretPos);
+    return {
+      mode: 'keyword',
+      query,
+      replaceStart: activeToken.start,
+      replaceEnd: activeToken.end,
+      caretPos,
+      token: activeToken,
+      tokens,
+    };
+  }
+
+  return {
+    mode: 'none',
+    caretPos,
+    tokens,
+  };
+}
+
+/**
+ * Generates suggestions for the given caret context.
+ * @param {Object} context
+ * @param {Map<string, Object>} configuredKeywords
+ * @returns {Array<Object>}
+ */
+export function getSuggestions(context, configuredKeywords) {
+  if (!context || context.mode === 'none') return [];
+
+  const suggestions = [];
+
+  if (context.mode === 'keyword') {
+    const q = (context.query || '').toLowerCase().trim();
+    for (const [id, kw] of configuredKeywords.entries()) {
+      const idLower = id.toLowerCase();
+      const labelLower = (kw.label || '').toLowerCase();
+      const matches = !q || idLower.startsWith(q) || labelLower.startsWith(q) || idLower.includes(q);
+
+      if (matches) {
+        suggestions.push({
+          type: 'keyword',
+          id: kw.id,
+          label: kw.label || kw.id,
+          display: `${kw.id}:`,
+          insertText: `${kw.id}:`,
+          description: kw.label || kw.id,
+          dataType: kw.dataType || 'string',
+        });
+      }
+    }
+  } else if (context.mode === 'value') {
+    const kwConfig = configuredKeywords.get(context.keywordLower);
+    if (!kwConfig) return [];
+
+    const prefix = (context.valuePrefix || '').toLowerCase();
+
+    for (const opt of kwConfig.options) {
+      const valLower = (opt.value || '').toLowerCase();
+      const lblLower = (opt.label || '').toLowerCase();
+      const txtLower = (opt.text || '').toLowerCase();
+      const matches = !prefix || valLower.includes(prefix) || lblLower.includes(prefix) || txtLower.includes(prefix);
+
+      if (matches) {
+        // Needs quotes if option contains spaces, or if already quoted, or if contains colons
+        const needsQuotes = context.quoted || opt.value.includes(' ') || opt.value.includes(':');
+        const quoteChar = context.quoteChar || '"';
+        const formatted = needsQuotes ? `${quoteChar}${opt.value}${quoteChar}` : opt.value;
+        const displayText = opt.text || opt.value;
+
+        suggestions.push({
+          type: 'value',
+          keyword: kwConfig.id,
+          keywordLabel: kwConfig.label || kwConfig.id,
+          value: opt.value,
+          label: opt.label || opt.value,
+          display: displayText,
+          insertText: formatted,
+          description: (opt.label && opt.label !== opt.value && opt.label !== displayText) ? opt.label : '',
+          dataType: kwConfig.dataType || 'string',
+          element: opt.element,
+          image: opt.image,
+        });
+      }
+    }
+  }
+
+  return suggestions;
+}
+
+/**
+ * Applies a selected suggestion to the current input string.
+ * @param {string} inputStr
+ * @param {Object} suggestion
+ * @param {Object} context
+ * @returns {{ newValue: string, newCaret: number }}
+ */
+export function applySuggestion(inputStr, suggestion, context) {
+  const replaceStart = context.replaceStart;
+  const replaceEnd = context.replaceEnd;
+
+  const before = inputStr.slice(0, replaceStart);
+  let after = inputStr.slice(replaceEnd);
+  let insertText = suggestion.insertText;
+
+  if (suggestion.type === 'keyword') {
+    // When inserting a keyword like `mix:`, do not add trailing space so user can immediately type value
+    // If after text starts with colon, remove it to avoid `mix::`
+    if (after.startsWith(':')) {
+      after = after.slice(1);
+    }
+    const newValue = before + insertText + after;
+    const newCaret = before.length + insertText.length;
+    return { newValue, newCaret };
+  }
+
+  // When inserting a value (e.g. `"We Play House Recordings"`)
+  // Add a trailing space if after does not already start with whitespace
+  if (after.length === 0 || !/^\s/.test(after)) {
+    insertText += ' ';
+  }
+
+  const newValue = before + insertText + after;
+  const newCaret = before.length + insertText.length;
+  return { newValue, newCaret };
+}