@lo-tek/interfaces 0.0.0 → 0.37.0

package/src/components/frame/suggestion/suggestion.css

@@ -0,0 +1,132 @@
+@import "../../css/label/label.css";
+@import "../../css/input/input.css";
+@import "../../css/help-text/help-text.css";
+@import "../../css/error-text/error-text.css";
+@import "../../css/sr-only/sr-only.css";
+
+@layer lotek {
+  lt-suggestion {
+    display: block;
+  }
+
+  .lt-suggestion__list {
+    box-sizing: border-box;
+    margin: var(--lt-spacing-1) 0 0;
+    padding: 0;
+    list-style: none;
+    max-block-size: var(
+      --lt-suggestion-max-height,
+      calc(var(--lt-spacing-10) * 4)
+    );
+    overflow-y: auto;
+    background: var(--lt-color-neutral-canvas);
+    border: 1px solid var(--lt-color-neutral-border);
+    border-radius: var(--lt-suggestion-radius, var(--lt-spacing-1));
+    box-shadow: var(--lt-shadow-overlay);
+  }
+
+  /* When open, the list sits in the top layer, `popover="manual"`, so a
+     parent with `overflow`, such as the body of a dialog, does not clip it.
+     The web component computes the position and width from the field.
+     Without the popover, as in a list no web component has handled, it sits
+     in the flow below the field. `--lt-suggestion-left` is the distance from
+     the left edge of the viewport; in a right-to-left document it is flipped
+     below, as in `<lt-popover>`. */
+  .lt-suggestion__list:popover-open {
+    position: fixed;
+    inset: auto;
+    inset-block-start: var(--lt-suggestion-top, 0);
+    inset-inline-start: var(--lt-suggestion-left, 0);
+    inline-size: var(--lt-suggestion-width, auto);
+    margin: 0;
+  }
+
+  .lt-suggestion__list:popover-open:dir(rtl) {
+    inset-inline-start: auto;
+    inset-inline-end: var(--lt-suggestion-left, 0);
+  }
+
+  .lt-suggestion__list[hidden] {
+    display: none;
+  }
+
+  /* Markup written without JavaScript arrives without `hidden` on the list,
+     and the web component only closes it once it is registered. Until then
+     it is hidden, so it does not stand open below a field nobody has
+     touched. */
+  lt-suggestion:not(:defined) .lt-suggestion__list {
+    display: none;
+  }
+
+  .lt-suggestion__option {
+    padding: var(
+      --lt-suggestion-option-padding,
+      var(--lt-spacing-2) var(--lt-spacing-3)
+    );
+    font-family: inherit;
+    font-size: var(--lt-font-size-m);
+    line-height: var(--lt-line-height-default);
+    color: var(--lt-color-neutral-text-strong);
+    cursor: pointer;
+  }
+
+  .lt-suggestion__option:hover {
+    background: var(--lt-color-accent-surface);
+  }
+
+  /* The highlight follows aria-selected, the same information the screen
+     reader reads. What is shown and what is announced cannot then drift
+     apart. */
+  .lt-suggestion__option[aria-selected="true"] {
+    background: var(--lt-color-accent-fill);
+    color: var(--lt-color-accent-content);
+  }
+
+  /* The hidden field for the code. A `type="hidden"` is never shown; the rule
+     is there so the class also works when someone gives the field another
+     type. */
+  .lt-suggestion__value {
+    display: none;
+  }
+
+  .lt-suggestion__empty {
+    padding: var(
+      --lt-suggestion-option-padding,
+      var(--lt-spacing-2) var(--lt-spacing-3)
+    );
+    font-size: var(--lt-font-size-m);
+    color: var(--lt-color-neutral-text-subtle);
+  }
+
+  /* The empty message follows the list: when the list is closed, it is not
+     shown. The rule is in the stylesheet and not in the web component,
+     because the app controls the empty message when it filters itself, and
+     does not know whether the list is open. It only knows whether the search
+     found anything. The empty message must come after the list, as a
+     sibling. */
+  .lt-suggestion__list[hidden] ~ .lt-suggestion__empty {
+    display: none;
+  }
+
+  /* While the answer to the search is on its way, the list says
+     `aria-busy`, and "No matches" would be untrue. */
+  .lt-suggestion__list[aria-busy="true"] ~ .lt-suggestion__empty {
+    display: none;
+  }
+
+  /* Before registration the list is hidden by the rule above, without
+     `hidden`. */
+  lt-suggestion:not(:defined) .lt-suggestion__empty {
+    display: none;
+  }
+
+  /* High contrast: the highlight is shown only with background and text
+     colour, which the mode replaces. The system colours bring the difference
+     back. */
+  @media (forced-colors: active) {
+    .lt-suggestion__option[aria-selected="true"] {
+      background-color: Highlight;
+      color: HighlightText;
+    }
+  }
+}

package/src/components/frame/suggestion/suggestion.ts

@@ -0,0 +1,172 @@
+import { attributes, checkedKeys, idOrFallback } from "../../css/shared.js"
+import {
+  computeFieldAttributes,
+  type FieldOptions,
+} from "../field/field-core.js"
+
+export const SUGGESTION_CLASS = "lt-suggestion" as const
+export const SUGGESTION_LIST_CLASS = "lt-suggestion__list" as const
+export const SUGGESTION_OPTION_CLASS = "lt-suggestion__option" as const
+export const SUGGESTION_EMPTY_CLASS = "lt-suggestion__empty" as const
+export const SUGGESTION_VALUE_CLASS = "lt-suggestion__value" as const
+export const SUGGESTION_STATUS_CLASS = "lt-sr-only" as const
+
+export type SuggestionOptions = Omit<FieldOptions, "id"> & {
+  /**
+   * Shared id stem. The control becomes `${id}`, the list `${id}-list`, and
+   * the options `${id}-option-${key}`.
+   */
+  id: string
+  /**
+   * One key per option the server sends, taken from the data, such as a
+   * record id. The key gives the option its id, so an update that sends the
+   * list again recognises the options. An empty key, whitespace or two
+   * identical keys throw. Default: no options.
+   */
+  keys?: string[]
+  /** The option highlighted with the arrow keys. Default: none. */
+  activeIndex?: number
+  /** The list is open. Default: closed. */
+  open?: boolean
+  /**
+   * The answer to the search has not arrived yet. The list gets `aria-busy`,
+   * and the empty message stays hidden, so an asynchronous search does not
+   * say "No matches" in the gap between the keystroke and the answer.
+   */
+  pending?: boolean
+}
+
+/**
+ * The attributes for a field with a suggestion list.
+ *
+ * The server writes both the field and the list. The web component filters,
+ * handles the arrow keys and keeps `aria-activedescendant` in sync. It
+ * renders nothing: it used to create the whole field itself, and then there
+ * was nothing to fill in before the script had run.
+ *
+ * No preserve list. The attributes that change while the user types are set
+ * by the web component, and it sets them back when a patch strips them. If
+ * something else has already filtered, set `prefiltered` on
+ * `<lt-suggestion>`, and the web component leaves both the options and the
+ * empty message alone. If the server should also decide whether the list is
+ * expanded and which option is highlighted, set `server-controlled` as well.
+ */
+export const suggestion = ({
+  id: givenId,
+  keys: givenKeys = [],
+  activeIndex = -1,
+  open = false,
+  pending = false,
+  ...field
+}: SuggestionOptions) => {
+  // The fallback only matters for callers without a type check.
+  const id = idOrFallback("lt.suggestion()", givenId)
+  const keys = checkedKeys("lt.suggestion()", givenKeys)
+  const count = keys.length
+  const computed = computeFieldAttributes({ ...field, id })
+  const listId = `${id}-list`
+  const labelId = `${id}-label`
+  const statusId = `${id}-status`
+  const optionId = (index: number) => `${id}-option-${keys[index]}`
+  // The highlight is written only when the list is open, both halves
+  // together. The web component removes both as the list closes, and a
+  // closed list with a highlighted option would point
+  // `aria-activedescendant` into something hidden.
+  const marked =
+    open &&
+    Number.isInteger(activeIndex) &&
+    activeIndex >= 0 &&
+    activeIndex < count
+
+  return {
+    // The label also names the list, through `aria-labelledby`.
+    label: attributes({ ...computed.label, id: labelId }, computed.label),
+    control: attributes(
+      {
+        ...computed.control,
+        class: "lt-input" as const,
+        type: "text" as const,
+        role: "combobox" as const,
+        autocomplete: "off" as const,
+        "aria-expanded": (open ? "true" : "false") as "true" | "false",
+        "aria-controls": listId,
+        "aria-describedby": [computed.control["aria-describedby"], statusId]
+          .filter(Boolean)
+          .join(" "),
+        "aria-autocomplete": "list" as const,
+        "aria-activedescendant": marked ? optionId(activeIndex) : undefined,
+      },
+      computed.control,
+    ),
+    /**
+     * The list. It sits in the top layer, `popover="manual"`, so a parent
+     * with `overflow` does not clip it. `hidden` still says whether it is
+     * open; the web component opens and closes the popover from that.
+     */
+    list: attributes({
+      class: SUGGESTION_LIST_CLASS,
+      id: listId,
+      role: "listbox" as const,
+      "aria-labelledby": labelId,
+      popover: "manual" as const,
+      hidden: open ? undefined : (true as const),
+      "aria-busy": pending ? ("true" as const) : undefined,
+    }),
+    options: keys.map((_, index) =>
+      attributes({
+        class: SUGGESTION_OPTION_CLASS,
+        id: optionId(index),
+        role: "option" as const,
+        "aria-selected": (marked && index === activeIndex ? "true" : "false") as
+          | "true"
+          | "false",
+      }),
+    ),
+    /**
+     * The text shown when nothing matches.
+     *
+     * It follows the list: visible only when the list is open and empty. The
+     * stylesheet handles a closed list, with a rule that hides the empty
+     * message after a list with `hidden`. The builder function therefore
+     * only says whether there are matches, and whether the answer has
+     * arrived (`pending`). It used to read `open`, and with `prefiltered` the
+     * app controls the empty message without knowing whether the list is
+     * open: that state belongs to the web component, so the message could
+     * never be shown.
+     */
+    empty: attributes({
+      class: SUGGESTION_EMPTY_CLASS,
+      hidden: count === 0 && !pending ? undefined : (true as const),
+    }),
+    /**
+     * The region that announces the number of matches to screen readers.
+     *
+     * The web component writes the text while the user types, so it is not
+     * in the server's version. If an update empties the element, the web
+     * component writes the text again. The element must still be in the
+     * markup the server sends, or there is nothing to announce into before
+     * the script has run. `role="status"` implies `aria-live="polite"`.
+     */
+    status: attributes({
+      class: SUGGESTION_STATUS_CLASS,
+      id: statusId,
+      role: "status" as const,
+    }),
+    /**
+     * The hidden field that receives the code of the option the user chose.
+     *
+     * The field shows the text, and without JavaScript the text is what is
+     * submitted. With JavaScript the web component writes `data-value` from
+     * the option here, or the text when the option has no `data-value`, and
+     * empties it when the user changes the text. You write `name` yourself;
+     * it belongs to your form.
+     */
+    value: attributes({
+      class: SUGGESTION_VALUE_CLASS,
+      type: "hidden" as const,
+    }),
+    help: computed.help,
+    error: computed.error,
+    state: computed.state,
+  }
+}