@threadlabs/looma 0.14.5 → 0.14.7

package/components/shared/authoring.js

@@ -0,0 +1,46 @@
+// Warnings about authoring mistakes the controllers work around but cannot fix. They run in
+// development only: bundlers replace process.env.NODE_ENV, the convention Vue and React follow, and a
+// production build ("production") skips them. Without a bundler there is no process, and they run.
+export const DEV = (() => {
+  try {
+    return process.env.NODE_ENV !== "production";
+  } catch {
+    return true;
+  }
+})();
+
+// True when another element in the same document or shadow root has this element's id.
+export function duplicateId(element) {
+  return Boolean(element.id) && element.getRootNode().querySelectorAll(`[id="${CSS.escape(element.id)}"]`).length > 1;
+}
+
+// A Form Field's authoring problems, read before the field links its label and input.
+export function fieldProblems(label, input) {
+  const problems = [];
+  const target = label?.getAttribute("for");
+  if (label && !target && !label.contains(input)) {
+    problems.push(
+      "ui-form-field: the label has no for, so the field linked it to its input, which works only once JavaScript runs. Give the input an id and the label a matching for, or put the input inside the label, so the label works without JavaScript.",
+    );
+  }
+  if (duplicateId(input)) {
+    problems.push(
+      `ui-form-field: the input's id "${input.id}" is used by another element in the same document or shadow root, so its label and description can reach the wrong element. Give each input its own id.`,
+    );
+  }
+  if (target && input.getRootNode().querySelector(`#${CSS.escape(target)}`) !== input) {
+    problems.push(
+      `ui-form-field: the label's for="${target}" does not point at this field's input, so the label names another element or none. Set for to the input's id.`,
+    );
+  }
+  return problems;
+}
+
+// Each problem is said once per field, with the field, however often the controller re-links it.
+export function warnOnce(warned, problems, element) {
+  for (const problem of problems) {
+    if (warned.has(problem)) continue;
+    warned.add(problem);
+    console.warn(problem, element);
+  }
+}

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();

package/components/ui-form-field/ui-form-field.js

@@ -1,3 +1,5 @@
+import { DEV, fieldProblems, warnOnce } from "../shared/authoring.js";
+
 let nextFieldId = 0;
 
 function id(prefix) {
@@ -14,6 +16,7 @@ export default function controller(host) {
   let activeInput = null;
   let owned = new Set();
   let queued = false;
+  const warned = new Set();
   const removeOwned = (input) => {
     if (!input || owned.size === 0) return;
     const remaining = descriptionIds(input).filter((value) => !owned.has(value));
@@ -32,6 +35,7 @@ export default function controller(host) {
       owned = new Set();
     }
     if (!input) return;
+    if (DEV) warnOnce(warned, fieldProblems(label, input), element);
     if (!input.id) input.id = id("form-field-input");
     if (label && !label.getAttribute("for")) label.setAttribute("for", input.id);
     const external = descriptionIds(input).filter((value) => !owned.has(value));

package/components/ui-input-group/ui-input-group.js

@@ -1,3 +1,5 @@
+import { DEV, duplicateId, warnOnce } from "../shared/authoring.js";
+
 let nextAffixId = 0;
 // An affix holding a control keeps it: its clicks are its own, and it is not hidden or described.
 const INTERACTIVE = "a[href], button, input, select, textarea, [tabindex], [contenteditable]";
@@ -6,6 +8,9 @@ function descriptionIds(input) {
   return (input.getAttribute("aria-describedby") ?? "").split(/\s+/).filter(Boolean);
 }
 
+const affixProblem = (affix) =>
+  `ui-input-group: the affix id "${affix.id}" is used by another element in the same document or shadow root, so the input's description can read the wrong element. Give each affix its own id, or leave it off and the group adds one.`;
+
 // A text affix is hidden from assistive technology and linked to the input as its description
 // instead, so the input's name stays its label and the affix is read once, with the input. The
 // consumer's own aria-describedby (or a Form Field's) is kept. A press on an affix, or anywhere in
@@ -14,6 +19,7 @@ export default function controller(host) {
   const element = host.element;
   let owned = [];
   let described = null;
+  const warned = new Set();
   const wire = () => {
     const input = element.querySelector(".field input");
     const affixes = Array.from(element.querySelectorAll(":scope > .affix")).filter((affix) => {
@@ -23,6 +29,7 @@ export default function controller(host) {
       return text;
     });
     for (const affix of affixes) affix.id ||= `ui-input-group-affix-${(nextAffixId += 1)}`;
+    if (DEV) warnOnce(warned, affixes.filter(duplicateId).map(affixProblem), element);
     if (described && described !== input) {
       const rest = descriptionIds(described).filter((id) => !owned.includes(id));
       if (rest.length) described.setAttribute("aria-describedby", rest.join(" "));