@threadlabs/looma 0.14.6 → 0.14.7

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
@@ -60,14 +62,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 +89,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 +100,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 +231,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 +506,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) {
@@ -218,12 +225,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);
@@ -363,7 +372,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 +503,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();