@threadlabs/looma 0.14.6 → 0.14.8

package/components/ui-combobox/ui-combobox.html

@@ -14,7 +14,9 @@
     <prop name="value" type="string | null"
     >The selected value in single mode, which a named combobox submits with its form. The field shows the matching option's label, and a form reset returns to
       this value.</prop>
-    <prop name="items" type="list(object({ id: string, value: string, label: string, group?: string, disabled?: boolean }))"
+    <prop
+      name="items"
+      type="list(object({ id: string, value: string, label: string, group?: string, disabled?: boolean, description?: string, tag?: object({ label: string, tone?: neutral | accent | info | success | warning | danger }) }))"
     >The selected items in multiple mode, as JSON; a named combobox submits each one's value. A form reset returns to these items, or to none when unset.</prop>
     <prop name="selectedValues" type="list(string)"
     >The selected option values in multiple mode, when the consumer controls the selection. Once set, the consumer owns it: each value shows as a badge with its
@@ -31,6 +33,10 @@
     <prop name="query" type="string"
     >The input's text, when the consumer controls it. Once set, the consumer owns the text: typing reports query-change, and the input returns to query unless
       query is updated to match. Leave it unset to let the combobox manage its own text, showing the chosen option's label.</prop>
+    <prop name="filter" type="label | none" default="label"
+    >How the list narrows as the user types. label lists the options whose label contains the typed text, ignoring case. none lists every authored option, for
+      options already narrowed elsewhere, such as a server search, so a result that matched on data other than its label still shows. Leaving the field still
+      commits an option whose label matches the text, or the only one listed.</prop>
     <prop name="allowFreeText" type="boolean" default="false">Allows values that do not match an authored option.</prop>
     <prop name="allowCreate" type="boolean" default="false"
     >Offers the current query as a new option, reported as create-item. When nothing else matches, the offer is highlighted, so Enter creates it; with nothing
@@ -60,14 +66,18 @@
     <prop name="help" type="string" default=""
     >Help text for the field. When set, a help button appears beside the field and opens a tooltip with this text; while it is open, the input is described by
       it.</prop>
-    <state name="internalItems" type="list(object({ id: string, value: string, label: string, group?: string, disabled?: boolean }))" :value="[]"></state>
+    <state
+      name="internalItems"
+      type="list(object({ id: string, value: string, label: string, group?: string, disabled?: boolean, description?: string, tag?: object({ label: string, tone?: neutral | accent | info | success | warning | danger }) }))"
+      :value="[]"
+    ></state>
     <state name="raw" :value="''"></state>
     <state name="display" :value="''"></state>
     <state name="selected" type="string | null" :value="null"></state>
     <state name="expanded" :value="false"></state>
     <state
       name="rows"
-      type="list(object({ id: string, value: string, label: string, group?: string, disabled: boolean, selected: boolean }))"
+      type="list(object({ id: string, value: string, label: string, group?: string, disabled: boolean, selected: boolean, description?: string, tag?: object({ label: string, tone?: neutral | accent | info | success | warning | danger }) }))"
       :value="[]"
     ></state>
     <state name="active" :value="-1"></state>
@@ -83,7 +93,7 @@
     <state name="submitted" :value="''"></state>
     <state
       name="groups"
-      type="list(object({ name: string, role: group | presentation, label: string | null, rows: list(object({ id: string, value: string, label: string, group?: string, disabled: boolean, selected: boolean, index: integer })) }))"
+      type="list(object({ name: string, role: group | presentation, label: string | null, rows: list(object({ id: string, value: string, label: string, group?: string, disabled: boolean, selected: boolean, description?: string, tag?: object({ label: string, tone?: neutral | accent | info | success | warning | danger }), index: integer, labelledBy: string | null, detail: string | null })) }))"
       :value="[]"
     ></state>
     <state name="creatable" :value="false"></state>
@@ -94,28 +104,31 @@
     <event name="query-change" type="object({ query: string, display: string, trigger: keyboard | pointer | programmatic })"></event>
     <event
       name="value-change"
-      type="object({ value: string | null, query: string, option: object({ id: string, value: string, label: string, group?: string, disabled?: boolean }) | null, kind: selection | clear | free-entry | create, trigger: keyboard | pointer | programmatic }) | list(object({ id: string, value: string, label: string, group?: string, disabled?: boolean }))"
+      type="object({ value: string | null, query: string, option: object({ id: string, value: string, label: string, group?: string, disabled?: boolean, description?: string, tag?: object({ label: string, tone?: neutral | accent | info | success | warning | danger }) }) | null, kind: selection | clear | free-entry | create, trigger: keyboard | pointer | programmatic }) | list(object({ id: string, value: string, label: string, group?: string, disabled?: boolean, description?: string, tag?: object({ label: string, tone?: neutral | accent | info | success | warning | danger }) }))"
     ></event>
     <event
       name="free-entry"
-      type="object({ value: string | null, query: string, option: object({ id: string, value: string, label: string, group?: string, disabled?: boolean }) | null, kind: selection | clear | free-entry | create, trigger: keyboard | pointer | programmatic })"
+      type="object({ value: string | null, query: string, option: object({ id: string, value: string, label: string, group?: string, disabled?: boolean, description?: string, tag?: object({ label: string, tone?: neutral | accent | info | success | warning | danger }) }) | null, kind: selection | clear | free-entry | create, trigger: keyboard | pointer | programmatic })"
     ></event>
     <event
       name="create-entry"
-      type="object({ value: string | null, query: string, option: object({ id: string, value: string, label: string, group?: string, disabled?: boolean }) | null, kind: selection | clear | free-entry | create, trigger: keyboard | pointer | programmatic })"
+      type="object({ value: string | null, query: string, option: object({ id: string, value: string, label: string, group?: string, disabled?: boolean, description?: string, tag?: object({ label: string, tone?: neutral | accent | info | success | warning | danger }) }) | null, kind: selection | clear | free-entry | create, trigger: keyboard | pointer | programmatic })"
     ></event>
     <event
       name="validation-change"
       type="object({ status: pristine | pending | valid | warning | error, touched: boolean, dirty: boolean, issues: list(object({ message: string, path?: list(unknown), severity?: error | warning })), output?: unknown })"
     ></event>
-    <event name="options-change" type="list(object({ id: string, value: string, label: string, group?: string, disabled?: boolean }))"></event>
+    <event
+      name="options-change"
+      type="list(object({ id: string, value: string, label: string, group?: string, disabled?: boolean, description?: string, tag?: object({ label: string, tone?: neutral | accent | info | success | warning | danger }) }))"
+    ></event>
     <event
       name="add-item"
-      type="object({ item: object({ id: string, value: string, label: string, group?: string, disabled?: boolean }), index: integer, trigger: keyboard | pointer | programmatic })"
+      type="object({ item: object({ id: string, value: string, label: string, group?: string, disabled?: boolean, description?: string, tag?: object({ label: string, tone?: neutral | accent | info | success | warning | danger }) }), index: integer, trigger: keyboard | pointer | programmatic })"
     ></event>
     <event
       name="remove-item"
-      type="object({ item: object({ id: string, value: string, label: string, group?: string, disabled?: boolean }), index: integer, trigger: keyboard | pointer | programmatic })"
+      type="object({ item: object({ id: string, value: string, label: string, group?: string, disabled?: boolean, description?: string, tag?: object({ label: string, tone?: neutral | accent | info | success | warning | danger }) }), index: integer, trigger: keyboard | pointer | programmatic })"
     ></event>
     <event name="create-item" type="object({ query: string, trigger: keyboard | pointer | programmatic })"></event>
     <event name="selected-values-change" type="object({ selectedValues: list(string), trigger: keyboard | pointer | programmatic })"></event>
@@ -222,8 +235,19 @@
             :aria-selected="row.selected"
             :aria-disabled="row.disabled"
             :data-index="row.index"
+            :aria-labelledby="row.labelledBy"
+            :aria-describedby="row.detail"
           >
-            <slot :name="format('option-%s', row.id)"><span class="primary" $value="row.label"></span></slot>
+            <slot :name="format('option-%s', row.id)">
+              <span $if="row.detail" class="detail">
+                <span class="line">
+                  <span class="primary" :id="format('%s-option-%s-label', uid, row.index)" $value="row.label"></span>
+                  <ui-badge $if="row.tag" :tone="row.tag.tone"><span :id="format('%s-option-%s-tag', uid, row.index)" $value="row.tag.label"></span></ui-badge>
+                </span>
+                <span $if="row.description" class="description" :id="format('%s-option-%s-description', uid, row.index)" $value="row.description"></span>
+              </span>
+              <span $if="not row.detail" class="primary" $value="row.label"></span>
+            </slot>
           </div>
         </div>
         <div
@@ -486,6 +510,23 @@
       color: var(--_ui-combobox-option-text, var(--ui-text-primary));
       font-weight: 500;
     }
+    /* A row with a tag or a description: the label and its tag on one line, the description under them. */
+    .detail {
+      display: grid;
+      gap: var(--ui-space-0-5);
+      min-inline-size: 0;
+    }
+    .line {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: var(--ui-space-2);
+    }
+    .description {
+      color: var(--ui-text-muted);
+      font-size: var(--ui-font-size-sm);
+      line-height: var(--ui-line-height-md);
+    }
     .message, .group {
       color: var(--_ui-combobox-message-text, var(--ui-text-secondary));
       font-weight: 400;

package/components/ui-combobox/ui-combobox.js

@@ -5,14 +5,21 @@ const instances = new WeakMap();
 
 let comboboxes = 0;
 
+// An option's secondary line and tag ride on data-* attributes: <option> holds only text, so markup inside
+// it would run into its label before JavaScript. A row without them keeps the declared shape exactly.
 function authoredOptions(container) {
-  return Array.from(container.querySelectorAll("option")).map((option, index) => ({
-    id: option.id || option.value || `option-${index}`,
-    value: option.value,
-    label: option.label || option.textContent?.trim() || option.value,
-    group: option.closest("optgroup")?.label || undefined,
-    disabled: option.disabled,
-  }));
+  return Array.from(container.querySelectorAll("option")).map((option, index) => {
+    const { description, tag, tagTone } = option.dataset;
+    return {
+      id: option.id || option.value || `option-${index}`,
+      value: option.value,
+      label: option.label || option.textContent?.trim() || option.value,
+      group: option.closest("optgroup")?.label || undefined,
+      disabled: option.disabled,
+      ...(description ? { description } : {}),
+      ...(tag ? { tag: tagTone ? { label: tag, tone: tagTone } : { label: tag } } : {}),
+    };
+  });
 }
 
 export async function validate(host) {
@@ -48,6 +55,8 @@ export default function controller(host) {
     options: authoredOptions(authored),
     allowFreeText: Boolean(host.state.allowFreeText),
     allowCreate: Boolean(host.state.allowCreate),
+    // "none": the consumer already narrowed the options (a server search), so every one is listed.
+    filterByLabel: host.state.filter !== "none",
   });
   // Selected items work uncontrolled: the component keeps them and reports every change. A consumer
   // that owns `items` stays in charge, because the prop resyncs whatever it sets. A consumer that sets
@@ -142,7 +151,7 @@ export default function controller(host) {
       const filtered = options.filter((option) => {
         if (ids.has(option.id)) return false;
         ids.add(option.id);
-        if (fullSet) return true;
+        if (fullSet || !current.filterByLabel) return true;
         return option.label.toLocaleLowerCase().includes(query.toLocaleLowerCase());
       }).map((option) => ({
         ...option,
@@ -218,12 +227,14 @@ export default function controller(host) {
     host.dispatch("query-change", { query, display: query, trigger });
   };
   // A row carries a view-only `selected` flag; an item is the option itself, in its declared shape.
-  const asItem = ({ id, value, label, group, disabled }) => ({
+  const asItem = ({ id, value, label, group, disabled, description, tag }) => ({
     id,
     value,
     label,
     ...(group === undefined ? {} : { group }),
-    ...(disabled === undefined ? {} : { disabled })
+    ...(disabled === undefined ? {} : { disabled }),
+    ...(description === undefined ? {} : { description }),
+    ...(tag === undefined ? {} : { tag })
   });
   const addSelectedItem = (row, trigger) => {
     const option = asItem(row);
@@ -258,7 +269,8 @@ export default function controller(host) {
   };
   // A strict combobox (single, no free text, no create) behaves like a select: leaving it resolves the
   // typed text to a valid option (the highlighted one, an exact label, the first label it begins, or the
-  // only remaining option); with no match it reverts to the previous selection, or clears.
+  // only remaining option); with no match it reverts to the previous selection, or clears. With filter
+  // "none" the remaining options are all of them, whatever their labels, so the only one listed counts.
   const resolveTyped = (trigger) => {
     const current = config();
     if (host.state.multiple || current.allowFreeText || current.allowCreate) return;
@@ -276,7 +288,7 @@ export default function controller(host) {
         ?? enabled.find((row) => row.label.toLocaleLowerCase() === query)
         ?? enabled.find((row) => row.label.toLocaleLowerCase().startsWith(query))
         ?? (() => {
-          const containing = enabled.filter((option) => option.label.toLocaleLowerCase().includes(query));
+          const containing = current.filterByLabel ? enabled.filter((option) => option.label.toLocaleLowerCase().includes(query)) : enabled;
           return containing.length === 1 ? containing[0] : undefined;
         })();
     if (match) commit(match.value, match.label, match, "selection", trigger);
@@ -363,7 +375,10 @@ export default function controller(host) {
         group = { name, role: name ? "group" : "presentation", label: name || null, rows: [] };
         groups.push(group);
       }
-      group.rows.push({ ...row, index });
+      // The label names the option and the tag and description describe it, as a listbox option's
+      // label and description parts do; a row without either keeps its name from its content.
+      const detail = [row.tag ? `${uid}-option-${index}-tag` : "", row.description ? `${uid}-option-${index}-description` : ""].filter(Boolean).join(" ");
+      group.rows.push({ ...row, index, labelledBy: detail ? `${uid}-option-${index}-label` : null, detail: detail || null });
     });
     host.state.groups = groups;
     host.state.creatable = canCreate();
@@ -491,7 +506,7 @@ export default function controller(host) {
   });
   // Options can change while the list is open, as when a consumer adds the option it just created;
   // the open list shows them at once rather than at the next keystroke.
-  const optionsKey = () => JSON.stringify((config().options ?? []).map((row) => [row.value, row.label, row.disabled]));
+  const optionsKey = () => JSON.stringify((config().options ?? []).map((row) => [row.value, row.label, row.disabled, row.description, row.tag]));
   let lastOptionsKey = optionsKey();
   const observer = new MutationObserver(() => {
     relabel();