@qontinui/ui-bridge 0.1.1 → 0.2.0

package/dist/react/index.mjs

@@ -188,6 +188,376 @@ function findElementByIdentifier(identifier, root = document) {
   return null;
 }
 
+// src/ai/fuzzy-matcher.ts
+var DEFAULT_FUZZY_CONFIG = {
+  threshold: 0.7,
+  levenshteinWeight: 0.3,
+  jaroWinklerWeight: 0.4,
+  ngramWeight: 0.3,
+  ngramSize: 2,
+  caseSensitive: false,
+  ignoreWhitespace: true
+};
+function levenshteinDistance(s1, s2) {
+  const len1 = s1.length;
+  const len2 = s2.length;
+  const matrix = Array(len1 + 1).fill(null).map(() => Array(len2 + 1).fill(0));
+  for (let i = 0; i <= len1; i++) matrix[i][0] = i;
+  for (let j = 0; j <= len2; j++) matrix[0][j] = j;
+  for (let i = 1; i <= len1; i++) {
+    for (let j = 1; j <= len2; j++) {
+      const cost = s1[i - 1] === s2[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,
+        // deletion
+        matrix[i][j - 1] + 1,
+        // insertion
+        matrix[i - 1][j - 1] + cost
+        // substitution
+      );
+    }
+  }
+  return matrix[len1][len2];
+}
+function levenshteinSimilarity(s1, s2) {
+  if (s1.length === 0 && s2.length === 0) return 1;
+  if (s1.length === 0 || s2.length === 0) return 0;
+  const distance = levenshteinDistance(s1, s2);
+  const maxLength = Math.max(s1.length, s2.length);
+  return 1 - distance / maxLength;
+}
+function jaroSimilarity(s1, s2) {
+  if (s1.length === 0 && s2.length === 0) return 1;
+  if (s1.length === 0 || s2.length === 0) return 0;
+  const matchDistance = Math.floor(Math.max(s1.length, s2.length) / 2) - 1;
+  const s1Matches = new Array(s1.length).fill(false);
+  const s2Matches = new Array(s2.length).fill(false);
+  let matches = 0;
+  let transpositions = 0;
+  for (let i = 0; i < s1.length; i++) {
+    const start = Math.max(0, i - matchDistance);
+    const end = Math.min(i + matchDistance + 1, s2.length);
+    for (let j = start; j < end; j++) {
+      if (s2Matches[j] || s1[i] !== s2[j]) continue;
+      s1Matches[i] = true;
+      s2Matches[j] = true;
+      matches++;
+      break;
+    }
+  }
+  if (matches === 0) return 0;
+  let k = 0;
+  for (let i = 0; i < s1.length; i++) {
+    if (!s1Matches[i]) continue;
+    while (!s2Matches[k]) k++;
+    if (s1[i] !== s2[k]) transpositions++;
+    k++;
+  }
+  return (matches / s1.length + matches / s2.length + (matches - transpositions / 2) / matches) / 3;
+}
+function jaroWinklerSimilarity(s1, s2, prefixScale = 0.1) {
+  const jaroSim = jaroSimilarity(s1, s2);
+  let prefixLength = 0;
+  const maxPrefix = Math.min(4, Math.min(s1.length, s2.length));
+  for (let i = 0; i < maxPrefix; i++) {
+    if (s1[i] === s2[i]) {
+      prefixLength++;
+    } else {
+      break;
+    }
+  }
+  return jaroSim + prefixLength * prefixScale * (1 - jaroSim);
+}
+function generateNgrams(s, n) {
+  const ngrams = /* @__PURE__ */ new Set();
+  if (s.length < n) {
+    ngrams.add(s);
+    return ngrams;
+  }
+  for (let i = 0; i <= s.length - n; i++) {
+    ngrams.add(s.substring(i, i + n));
+  }
+  return ngrams;
+}
+function ngramSimilarity(s1, s2, n = 2) {
+  if (s1.length === 0 && s2.length === 0) return 1;
+  if (s1.length === 0 || s2.length === 0) return 0;
+  const ngrams1 = generateNgrams(s1, n);
+  const ngrams2 = generateNgrams(s2, n);
+  let intersection = 0;
+  for (const ngram of ngrams1) {
+    if (ngrams2.has(ngram)) {
+      intersection++;
+    }
+  }
+  const union = ngrams1.size + ngrams2.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+function normalizeString(s, config = {}) {
+  let normalized = s;
+  if (!config.caseSensitive) {
+    normalized = normalized.toLowerCase();
+  }
+  if (config.ignoreWhitespace !== false) {
+    normalized = normalized.replace(/\s+/g, " ").trim();
+  }
+  return normalized;
+}
+function fuzzyMatch(source, target, config = {}) {
+  const finalConfig = { ...DEFAULT_FUZZY_CONFIG, ...config };
+  const normalizedSource = normalizeString(source, finalConfig);
+  const normalizedTarget = normalizeString(target, finalConfig);
+  const levenshteinScore = levenshteinSimilarity(normalizedSource, normalizedTarget);
+  const jaroWinklerScore = jaroWinklerSimilarity(normalizedSource, normalizedTarget);
+  const ngramScore = ngramSimilarity(normalizedSource, normalizedTarget, finalConfig.ngramSize);
+  const similarity = levenshteinScore * finalConfig.levenshteinWeight + jaroWinklerScore * finalConfig.jaroWinklerWeight + ngramScore * finalConfig.ngramWeight;
+  return {
+    similarity,
+    isMatch: similarity >= finalConfig.threshold,
+    scores: {
+      levenshtein: levenshteinScore,
+      jaroWinkler: jaroWinklerScore,
+      ngram: ngramScore
+    },
+    normalizedSource,
+    normalizedTarget
+  };
+}
+function tokenize(s) {
+  return s.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[_-]/g, " ").replace(/\s+/g, " ").trim().toLowerCase().split(" ").filter((token) => token.length > 0);
+}
+
+// src/ai/alias-generator.ts
+var DEFAULT_ALIAS_CONFIG = {
+  includeText: true,
+  includeAriaLabel: true,
+  includePlaceholder: true,
+  includeTitle: true,
+  includeSynonyms: true,
+  maxAliases: 20,
+  minLength: 2,
+  maxLength: 50
+};
+var SYNONYMS = {
+  // Submit-related
+  submit: ["send", "go", "confirm", "ok", "apply", "save", "done", "finish"],
+  send: ["submit", "deliver", "post"],
+  save: ["submit", "store", "keep", "apply"],
+  cancel: ["close", "dismiss", "abort", "back", "exit", "quit", "nevermind"],
+  close: ["cancel", "dismiss", "exit", "x"],
+  delete: ["remove", "trash", "erase", "clear", "destroy"],
+  remove: ["delete", "clear", "discard"],
+  edit: ["modify", "change", "update", "alter"],
+  update: ["edit", "modify", "save", "refresh"],
+  add: ["create", "new", "plus", "insert"],
+  create: ["add", "new", "make"],
+  search: ["find", "lookup", "query", "filter"],
+  find: ["search", "locate", "lookup"],
+  login: ["signin", "sign in", "log in", "authenticate", "enter"],
+  logout: ["signout", "sign out", "log out", "exit"],
+  register: ["signup", "sign up", "join", "create account"],
+  next: ["continue", "forward", "proceed", "advance"],
+  previous: ["back", "backward", "return", "prior"],
+  back: ["previous", "return", "backward"],
+  start: ["begin", "launch", "initiate", "run", "execute"],
+  stop: ["end", "halt", "pause", "terminate"],
+  enable: ["activate", "turn on", "switch on"],
+  disable: ["deactivate", "turn off", "switch off"],
+  show: ["display", "reveal", "view", "open"],
+  hide: ["conceal", "collapse", "close"],
+  expand: ["open", "show", "unfold", "reveal"],
+  collapse: ["close", "hide", "fold", "minimize"],
+  yes: ["ok", "confirm", "agree", "accept"],
+  no: ["cancel", "decline", "reject", "deny"],
+  help: ["support", "assistance", "info", "information", "faq"],
+  settings: ["preferences", "options", "config", "configuration"],
+  profile: ["account", "user", "me"],
+  download: ["export", "save", "get"],
+  upload: ["import", "load", "attach"],
+  refresh: ["reload", "update", "sync"],
+  copy: ["duplicate", "clone"],
+  paste: ["insert"],
+  select: ["choose", "pick"],
+  toggle: ["switch", "flip"],
+  // Form fields
+  email: ["e-mail", "mail"],
+  password: ["pass", "pwd", "secret"],
+  username: ["user", "login", "account", "name"],
+  firstname: ["first name", "given name", "forename"],
+  lastname: ["last name", "surname", "family name"],
+  fullname: ["full name", "name", "complete name"],
+  phone: ["telephone", "tel", "mobile", "cell"],
+  address: ["location", "street"],
+  city: ["town"],
+  country: ["nation"],
+  zip: ["zipcode", "postal", "postal code", "postcode"],
+  // Navigation
+  home: ["main", "start", "dashboard"],
+  menu: ["navigation", "nav"],
+  sidebar: ["side bar", "side panel", "side menu"]
+};
+var ELEMENT_ACTION_WORDS = {
+  button: ["button", "btn", "click"],
+  input: ["input", "field", "textbox", "box"],
+  textarea: ["textarea", "text area", "text field", "multiline"],
+  select: ["select", "dropdown", "combo", "picker", "chooser"],
+  checkbox: ["checkbox", "check", "tick"],
+  radio: ["radio", "option", "choice"],
+  link: ["link", "anchor", "href"],
+  form: ["form"],
+  menu: ["menu"],
+  menuitem: ["menu item", "option"],
+  tab: ["tab"],
+  dialog: ["dialog", "modal", "popup"],
+  switch: ["switch", "toggle"],
+  slider: ["slider", "range"]
+};
+function normalizeAlias(text) {
+  return text.toLowerCase().replace(/[^\w\s]/g, " ").replace(/\s+/g, " ").trim();
+}
+function extractWords(text) {
+  const tokens = tokenize(text);
+  return tokens.filter((t) => t.length >= 2);
+}
+function generateTextAliases(text, config) {
+  if (!text || !config.includeText) return [];
+  const aliases = [];
+  const normalized = normalizeAlias(text);
+  if (normalized.length >= config.minLength && normalized.length <= config.maxLength) {
+    aliases.push(normalized);
+  }
+  const words = extractWords(text);
+  for (const word of words) {
+    if (word.length >= config.minLength) {
+      aliases.push(word);
+    }
+  }
+  if (words.length >= 2 && words.length <= 4) {
+    const twoWords = words.slice(0, 2).join(" ");
+    if (twoWords.length <= config.maxLength) {
+      aliases.push(twoWords);
+    }
+    if (words.length > 2) {
+      const lastTwo = words.slice(-2).join(" ");
+      if (lastTwo.length <= config.maxLength) {
+        aliases.push(lastTwo);
+      }
+    }
+  }
+  return aliases;
+}
+function generateSynonyms(aliases, config) {
+  if (!config.includeSynonyms) return [];
+  const synonyms = [];
+  for (const alias of aliases) {
+    const words = alias.toLowerCase().split(/\s+/);
+    for (const word of words) {
+      if (SYNONYMS[word]) {
+        for (const synonym of SYNONYMS[word]) {
+          const newAlias = alias.toLowerCase().replace(word, synonym);
+          if (newAlias !== alias.toLowerCase()) {
+            synonyms.push(newAlias);
+          }
+          if (synonym.length >= config.minLength) {
+            synonyms.push(synonym);
+          }
+        }
+      }
+    }
+  }
+  return synonyms;
+}
+function generateTypeAliases(elementType) {
+  const type = elementType.toLowerCase();
+  return ELEMENT_ACTION_WORDS[type] || [type];
+}
+function generateAliases(input, config = {}) {
+  const finalConfig = { ...DEFAULT_ALIAS_CONFIG, ...config };
+  const aliasSet = /* @__PURE__ */ new Set();
+  const addAlias = (alias) => {
+    const normalized = normalizeAlias(alias);
+    if (normalized.length >= finalConfig.minLength && normalized.length <= finalConfig.maxLength) {
+      aliasSet.add(normalized);
+    }
+  };
+  const addAliases = (aliases2) => {
+    for (const alias of aliases2) {
+      addAlias(alias);
+    }
+  };
+  if (finalConfig.includeText && input.textContent) {
+    addAliases(generateTextAliases(input.textContent, finalConfig));
+  }
+  if (finalConfig.includeAriaLabel && input.ariaLabel) {
+    addAliases(generateTextAliases(input.ariaLabel, finalConfig));
+  }
+  if (finalConfig.includeAriaLabel && input.ariaLabelledBy) {
+    addAliases(generateTextAliases(input.ariaLabelledBy, finalConfig));
+  }
+  if (finalConfig.includePlaceholder && input.placeholder) {
+    addAliases(generateTextAliases(input.placeholder, finalConfig));
+  }
+  if (finalConfig.includeTitle && input.title) {
+    addAliases(generateTextAliases(input.title, finalConfig));
+  }
+  if (input.labelText) {
+    addAliases(generateTextAliases(input.labelText, finalConfig));
+  }
+  if (input.id) {
+    addAliases(extractWords(input.id));
+  }
+  if (input.name) {
+    addAliases(extractWords(input.name));
+  }
+  if (input.value && (input.elementType === "button" || input.inputType === "submit" || input.inputType === "button")) {
+    addAliases(generateTextAliases(input.value, finalConfig));
+  }
+  if (input.elementType) {
+    addAliases(generateTypeAliases(input.elementType));
+  }
+  if (input.inputType) {
+    addAlias(input.inputType);
+    if (input.inputType === "email") {
+      addAliases(["email", "e-mail", "email address"]);
+    } else if (input.inputType === "password") {
+      addAliases(["password", "pass", "pwd"]);
+    } else if (input.inputType === "tel") {
+      addAliases(["phone", "telephone", "mobile"]);
+    } else if (input.inputType === "url") {
+      addAliases(["url", "website", "link", "address"]);
+    } else if (input.inputType === "search") {
+      addAliases(["search", "find", "query"]);
+    }
+  }
+  if (finalConfig.includeSynonyms) {
+    const currentAliases = Array.from(aliasSet);
+    addAliases(generateSynonyms(currentAliases, finalConfig));
+  }
+  let aliases = Array.from(aliasSet);
+  aliases.sort((a, b) => a.length - b.length);
+  if (aliases.length > finalConfig.maxAliases) {
+    aliases = aliases.slice(0, finalConfig.maxAliases);
+  }
+  return aliases;
+}
+function generateDescription(input) {
+  const parts = [];
+  let name = input.ariaLabel || input.labelText || input.textContent || input.placeholder || input.title || input.id || input.name;
+  if (name) {
+    name = name.trim();
+    if (name.length > 30) {
+      name = name.substring(0, 27) + "...";
+    }
+    parts.push(`"${name}"`);
+  }
+  const typeWords = ELEMENT_ACTION_WORDS[input.elementType || ""] || [input.elementType || "element"];
+  parts.push(typeWords[0]);
+  if (input.inputType && input.inputType !== "text") {
+    parts.push(`(${input.inputType})`);
+  }
+  return parts.join(" ");
+}
+
 // src/core/registry.ts
 function getElementState(element) {
   const rect = element.getBoundingClientRect();
@@ -386,9 +756,13 @@ var UIBridgeRegistry = class {
   registerElement(id, element, options = {}) {
     const type = options.type ?? inferElementType(element);
     const actions = options.actions ?? inferActions(type);
-    element.setAttribute("data-ui-id", id);
+    const existingUiId = element.getAttribute("data-ui-id");
+    const actualId = existingUiId || id;
+    if (!existingUiId) {
+      element.setAttribute("data-ui-id", actualId);
+    }
     const registered = {
-      id,
+      id: actualId,
       element,
       type,
       label: options.label,
@@ -399,8 +773,8 @@ var UIBridgeRegistry = class {
       registeredAt: Date.now(),
       mounted: true
     };
-    this.elements.set(id, registered);
-    this.emit("element:registered", { id, type, label: options.label });
+    this.elements.set(actualId, registered);
+    this.emit("element:registered", { id: actualId, type, label: options.label });
     return registered;
   }
   /**
@@ -440,6 +814,209 @@ var UIBridgeRegistry = class {
     }
     return void 0;
   }
+  /**
+   * Search for elements using AI search criteria
+   */
+  searchElements(criteria) {
+    const results = [];
+    const threshold = criteria.fuzzyThreshold ?? 0.7;
+    for (const element of this.elements.values()) {
+      if (!element.mounted) continue;
+      const state = element.getState();
+      if (!criteria.fuzzy && !state.visible) continue;
+      const aliases = element.aliases ?? this.generateElementAliases(element);
+      const textContent = state.textContent?.trim() || "";
+      const label = element.label || "";
+      let maxScore = 0;
+      const matchReasons = [];
+      const scores = {};
+      if (criteria.text) {
+        if (textContent.toLowerCase() === criteria.text.toLowerCase() || label.toLowerCase() === criteria.text.toLowerCase()) {
+          maxScore = 1;
+          matchReasons.push("exact text match");
+          scores.text = 1;
+        } else if (criteria.fuzzy !== false) {
+          const textResult = fuzzyMatch(criteria.text, textContent, { threshold });
+          const labelResult = fuzzyMatch(criteria.text, label, { threshold });
+          const bestResult = textResult.similarity > labelResult.similarity ? textResult : labelResult;
+          if (bestResult.isMatch) {
+            scores.text = bestResult.similarity;
+            if (bestResult.similarity > maxScore) {
+              maxScore = bestResult.similarity;
+              matchReasons.push(`text similarity: ${(bestResult.similarity * 100).toFixed(0)}%`);
+            }
+          }
+        }
+      }
+      if (criteria.textContains) {
+        if (textContent.toLowerCase().includes(criteria.textContains.toLowerCase()) || label.toLowerCase().includes(criteria.textContains.toLowerCase())) {
+          const containsScore = 0.85;
+          scores.text = Math.max(scores.text ?? 0, containsScore);
+          if (containsScore > maxScore) {
+            maxScore = containsScore;
+            matchReasons.push("text contains");
+          }
+        }
+      }
+      if (criteria.accessibleName) {
+        const ariaLabel = element.element.getAttribute("aria-label") || "";
+        const accessibleName = ariaLabel || label || textContent;
+        if (accessibleName.toLowerCase() === criteria.accessibleName.toLowerCase()) {
+          scores.accessibility = 1;
+          if (1 > maxScore) {
+            maxScore = 1;
+            matchReasons.push("accessible name match");
+          }
+        } else if (criteria.fuzzy !== false) {
+          const result = fuzzyMatch(criteria.accessibleName, accessibleName, { threshold });
+          if (result.isMatch) {
+            scores.accessibility = result.similarity;
+            if (result.similarity > maxScore) {
+              maxScore = result.similarity;
+              matchReasons.push(`accessible name similarity: ${(result.similarity * 100).toFixed(0)}%`);
+            }
+          }
+        }
+      }
+      if (criteria.role) {
+        const role = element.element.getAttribute("role") || this.inferRole(element.type);
+        if (role?.toLowerCase() === criteria.role.toLowerCase()) {
+          scores.role = 1;
+          if (1 > maxScore) {
+            maxScore = 1;
+            matchReasons.push(`role: ${criteria.role}`);
+          }
+        }
+      }
+      if (criteria.type) {
+        if (element.type === criteria.type) {
+          const typeScore = 0.9;
+          scores.role = Math.max(scores.role ?? 0, typeScore);
+          if (typeScore > maxScore) {
+            maxScore = typeScore;
+            matchReasons.push(`type: ${criteria.type}`);
+          }
+        }
+      }
+      for (const alias of aliases) {
+        const searchText = criteria.text || criteria.textContains || criteria.accessibleName;
+        if (searchText) {
+          if (alias.toLowerCase() === searchText.toLowerCase()) {
+            scores.fuzzy = 1;
+            if (1 > maxScore) {
+              maxScore = 1;
+              matchReasons.push(`alias: "${alias}"`);
+            }
+          } else if (criteria.fuzzy !== false) {
+            const result = fuzzyMatch(searchText, alias, { threshold });
+            if (result.isMatch && result.similarity > (scores.fuzzy ?? 0)) {
+              scores.fuzzy = result.similarity;
+              if (result.similarity > maxScore) {
+                maxScore = result.similarity;
+                matchReasons.push(`fuzzy alias: "${alias}"`);
+              }
+            }
+          }
+        }
+      }
+      if (maxScore >= threshold) {
+        const aiElement = {
+          id: element.id,
+          type: element.type,
+          label: element.label,
+          tagName: element.element.tagName.toLowerCase(),
+          role: element.element.getAttribute("role") || void 0,
+          accessibleName: element.element.getAttribute("aria-label") || element.label,
+          actions: element.actions,
+          state,
+          registered: true,
+          description: element.description || generateDescription({
+            textContent,
+            ariaLabel: element.element.getAttribute("aria-label"),
+            elementType: element.type,
+            id: element.id,
+            labelText: element.label
+          }),
+          aliases,
+          purpose: element.purpose,
+          suggestedActions: [],
+          semanticType: element.semanticType
+        };
+        results.push({
+          element: aiElement,
+          confidence: maxScore,
+          matchReasons,
+          scores
+        });
+      }
+    }
+    results.sort((a, b) => b.confidence - a.confidence);
+    return results;
+  }
+  /**
+   * Find element by visible text
+   */
+  findByText(text, fuzzy = true) {
+    const results = this.searchElements({ text, fuzzy, fuzzyThreshold: fuzzy ? 0.7 : 1 });
+    if (results.length > 0) {
+      return this.elements.get(results[0].element.id);
+    }
+    return void 0;
+  }
+  /**
+   * Find element by accessible name
+   */
+  findByAccessibleName(name) {
+    const results = this.searchElements({ accessibleName: name, fuzzy: true });
+    if (results.length > 0) {
+      return this.elements.get(results[0].element.id);
+    }
+    return void 0;
+  }
+  /**
+   * Generate aliases for an element
+   */
+  generateElementAliases(element) {
+    const state = element.getState();
+    return generateAliases({
+      textContent: state.textContent,
+      ariaLabel: element.element.getAttribute("aria-label"),
+      placeholder: element.element.getAttribute("placeholder"),
+      title: element.element.getAttribute("title"),
+      elementType: element.type,
+      tagName: element.element.tagName.toLowerCase(),
+      id: element.id,
+      labelText: element.label
+    });
+  }
+  /**
+   * Infer ARIA role from element type
+   */
+  inferRole(type) {
+    const roleMap = {
+      button: "button",
+      input: "textbox",
+      select: "combobox",
+      checkbox: "checkbox",
+      radio: "radio",
+      link: "link",
+      form: void 0,
+      textarea: "textbox",
+      menu: "menu",
+      menuitem: "menuitem",
+      tab: "tab",
+      dialog: "dialog",
+      custom: void 0,
+      switch: "switch",
+      slider: "slider",
+      combobox: "combobox",
+      listbox: "listbox",
+      option: "option",
+      textbox: "textbox",
+      generic: void 0
+    };
+    return roleMap[type];
+  }
   /**
    * Register a component
    */
@@ -4134,24 +4711,24 @@ function useAutoRegister(options = {}) {
         const type = inferElementType2(element);
         const actions = inferActions2(type);
         const label = getAccessibleLabel(element);
-        bridge.registry.registerElement(uniqueId, element, {
+        const registered = bridge.registry.registerElement(uniqueId, element, {
           type,
           actions,
           label
         });
-        registeredElementsRef.current.set(element, uniqueId);
-        onRegister?.(uniqueId, element);
+        registeredElementsRef.current.set(element, registered.id);
+        onRegister?.(registered.id, element);
       } else {
         const type = inferElementType2(element);
         const actions = inferActions2(type);
         const label = getAccessibleLabel(element);
-        bridge.registry.registerElement(id, element, {
+        const registered = bridge.registry.registerElement(id, element, {
           type,
           actions,
           label
         });
-        registeredElementsRef.current.set(element, id);
-        onRegister?.(id, element);
+        registeredElementsRef.current.set(element, registered.id);
+        onRegister?.(registered.id, element);
       }
     },
     [bridge, idStrategy, customGenerateId, onRegister]