vectis-ui 0.1.0

package/dist/components/VCombobox/VCombobox.d.ts

@@ -0,0 +1,183 @@
+import { IconSource } from '../VIcon/types.js';
+/**
+ * A field one types into to search a list, and picks one or several values from. It is
+ * built out of a text field, a floating panel holding the list, and chips for the values
+ * already chosen.
+ *
+ * The platform offers nothing to build this on: its own suggestion list can be neither
+ * styled nor made to accept several values. So the JavaScript here implements the whole
+ * pattern assistive technology expects of a combobox — the filtering, the moving of the
+ * highlight, and the selection.
+ *
+ * One decision shapes all the rest: the DOM focus NEVER leaves the text field. What
+ * moves as the reader presses the arrows is a pointer naming the current option, which
+ * is why the panel has no keyboard of its own and why this component owns the entire
+ * accessibility contract of the field.
+ *
+ * The panel is opened in the mode where nothing dismisses it by itself, and closing is
+ * decided by the focus leaving the component — which the field being OUTSIDE the panel
+ * makes possible.
+ */
+/** One thing that can be chosen. */
+export interface ComboboxOption {
+    /** What choosing it means: this is what the value holds. */
+    value: string;
+    /** What it is called on screen, and what the search matches against. */
+    label: string;
+    /** An icon before the label: an icon name, or an explicit render. */
+    icon?: IconSource;
+    /** Shows the option without allowing it to be chosen. */
+    disabled?: boolean;
+}
+/**
+ * A named block of options — the equivalent of the grouping a native list offers. A
+ * group none of whose options survive the search disappears entirely, its name
+ * included.
+ */
+export interface ComboboxGroup {
+    /** The name of the block. */
+    label: string;
+    /** The options it holds. */
+    options: ComboboxOption[];
+}
+/**
+ * A rule drawn between two blocks of options. It is purely decorative, and a separator
+ * the search leaves stranded — at the top, at the bottom, or against another one — is
+ * simply not drawn.
+ */
+export interface ComboboxSeparator {
+    separator: true;
+}
+/** Anything the list may hold: an option, a named block, or a separator. */
+export type ComboboxItem = ComboboxOption | ComboboxGroup | ComboboxSeparator;
+/**
+ * How the list is narrowed as one types: by the component itself, not at all — when the
+ * options already arrive filtered by a server — or by a rule of your own.
+ */
+export type ComboboxFilter = boolean | ((option: ComboboxOption, query: string) => boolean);
+interface ComboboxProps {
+    /**
+     * What the list offers. An entry may be an option, a named block of options, or a
+     * separator; a plain list of options remains perfectly valid.
+     */
+    options: ComboboxItem[];
+    /**
+     * Allows several values to be chosen, which makes the value a list and shows what has
+     * been chosen as chips inside the field.
+     */
+    multiple?: boolean;
+    /** The height of the field: 32, 40 or 48 pixels. */
+    size?: 'sm' | 'md' | 'lg';
+    /** Takes 4px off the height, as everywhere else in the design system. */
+    compact?: boolean;
+    /** What the field says while nothing is chosen and nothing has been typed. */
+    placeholder?: string;
+    /** Makes the field unusable, greyed out through the colour tokens. */
+    disabled?: boolean;
+    /** Marks the field as invalid — for a rule of your own. */
+    invalid?: boolean;
+    /** Offers a cross that empties both the selection and the search. */
+    clearable?: boolean;
+    /** What the panel says when the search matches nothing. */
+    emptyText?: string;
+    /**
+     * How the list is narrowed as one types. Turning it off means the options already
+     * arrive filtered by their source and are shown exactly as they come.
+     *
+     * A rule of your own receives the query as it was TYPED, merely trimmed — not the
+     * accent-insensitive form used internally.
+     */
+    filter?: ComboboxFilter;
+    /**
+     * How long to wait before telling the source what is being searched for, in
+     * milliseconds. Zero tells it at once, which suits a source that is not a network
+     * request.
+     */
+    searchDebounce?: number;
+    /**
+     * Says that something is being loaded. With no option yet, the whole panel says so;
+     * with options already listed, a spinner appears at the foot of the list, since what
+     * is loading is then the next page. Either way the field replaces its chevron with a
+     * spinner.
+     */
+    loading?: boolean;
+    /** What is said while loading, and what the spinner is announced as. */
+    loadingText?: string;
+    /**
+     * Says that there are more pages to come, which is what makes the component ask for
+     * the next one as the end of the list comes into view.
+     */
+    hasMore?: boolean;
+}
+type __VLS_Props = ComboboxProps;
+type __VLS_Slots = {
+    /**
+     * What a row of the list shows, in place of the plain label — a subtitle, an avatar,
+     * a badge. It is told whether the row is the highlighted one and whether it is
+     * already chosen, so the rendering can react to both.
+     */
+    option?(props: {
+        option: ComboboxOption;
+        index: number;
+        active: boolean;
+        selected: boolean;
+    }): unknown;
+    /**
+     * Replaces the chip standing for one chosen value.
+     *
+     * Three of the values it receives are what make it usable without regressions:
+     * `remove`, without which the value could no longer be taken back, and the size and
+     * density worked out to sit inside the field, which cannot be guessed from outside.
+     * The option itself may be missing, if that value has never appeared among the
+     * options.
+     */
+    chip?(props: {
+        value: string;
+        option: ComboboxOption | undefined;
+        label: string;
+        remove: () => void;
+        size: 'xs' | 'sm';
+        compact: boolean;
+    }): unknown;
+    /** What the panel shows when nothing matches. It receives the term that was searched. */
+    empty?(props: {
+        query: string;
+    }): unknown;
+    /** What the panel shows while loading its first options. */
+    loading?(): unknown;
+};
+type __VLS_ModelProps = {
+    modelValue?: string | string[];
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_base: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    search: (query: string) => any;
+    "update:modelValue": (value: string | string[]) => any;
+    "load-more": () => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onSearch?: ((query: string) => any) | undefined;
+    "onUpdate:modelValue"?: ((value: string | string[]) => any) | undefined;
+    "onLoad-more"?: (() => any) | undefined;
+}>, {
+    loading: boolean;
+    placeholder: string;
+    size: "sm" | "md" | "lg";
+    filter: ComboboxFilter;
+    compact: boolean;
+    disabled: boolean;
+    multiple: boolean;
+    invalid: boolean;
+    clearable: boolean;
+    emptyText: string;
+    searchDebounce: number;
+    loadingText: string;
+    hasMore: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/VCombobox/VCombobox.js

@@ -0,0 +1,9 @@
+import './VCombobox.css';
+import e from "./VCombobox.vue_vue_type_script_setup_true_lang.js";
+/* empty css                                          */
+//#region src/components/VCombobox/VCombobox.vue
+var t = e;
+//#endregion
+export { t as default };
+
+//# sourceMappingURL=VCombobox.js.map

package/dist/components/VCombobox/VCombobox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VCombobox.js","names":[],"sources":["../../../src/components/VCombobox/VCombobox.vue"],"sourcesContent":["<script setup lang=\"ts\">\nimport { computed, nextTick, reactive, ref, useId, watch, watchEffect } from 'vue'\n\nimport VChip from '../VChip/VChip.vue'\nimport VIcon from '../VIcon/VIcon.vue'\nimport { expand_more as expandMoreIcon } from '../VIcon/icons/expand_more'\nimport type { IconSource } from '../VIcon/types'\nimport VInput from '../VInput/VInput.vue'\nimport VPopover from '../VPopover/VPopover.vue'\nimport VComboboxOption from './VComboboxOption.vue'\nimport VComboboxGroup from './VComboboxGroup.vue'\nimport VComboboxSeparator from './VComboboxSeparator.vue'\nimport { useInfiniteScroll } from './infiniteScroll'\nimport VSpinner from '../VSpinner/VSpinner.vue'\n\nimport { toggleValue } from '../../utils/array'\nimport { chipScaleFor } from '../../utils/chip'\nimport { normalizeText } from '../../utils/text'\n\nimport { useRootAttrs } from '../../composables/useRootAttrs'\n\nimport { useFocusoutDismiss } from '../../composables/useFocusoutDismiss'\n\nimport { useTimer } from '../../composables/useTimer'\nimport { useMessages } from '../../i18n/state'\n\n// @a11y @keyboard @core\n/**\n * A field one types into to search a list, and picks one or several values from. It is\n * built out of a text field, a floating panel holding the list, and chips for the values\n * already chosen.\n *\n * The platform offers nothing to build this on: its own suggestion list can be neither\n * styled nor made to accept several values. So the JavaScript here implements the whole\n * pattern assistive technology expects of a combobox — the filtering, the moving of the\n * highlight, and the selection.\n *\n * One decision shapes all the rest: the DOM focus NEVER leaves the text field. What\n * moves as the reader presses the arrows is a pointer naming the current option, which\n * is why the panel has no keyboard of its own and why this component owns the entire\n * accessibility contract of the field.\n *\n * The panel is opened in the mode where nothing dismisses it by itself, and closing is\n * decided by the focus leaving the component — which the field being OUTSIDE the panel\n * makes possible.\n */\n/** One thing that can be chosen. */\nexport interface ComboboxOption {\n  /** What choosing it means: this is what the value holds. */\n  value: string\n  /** What it is called on screen, and what the search matches against. */\n  label: string\n  /** An icon before the label: an icon name, or an explicit render. */\n  icon?: IconSource\n  /** Shows the option without allowing it to be chosen. */\n  disabled?: boolean\n}\n\n/**\n * A named block of options — the equivalent of the grouping a native list offers. A\n * group none of whose options survive the search disappears entirely, its name\n * included.\n */\nexport interface ComboboxGroup {\n  /** The name of the block. */\n  label: string\n  /** The options it holds. */\n  options: ComboboxOption[]\n}\n\n/**\n * A rule drawn between two blocks of options. It is purely decorative, and a separator\n * the search leaves stranded — at the top, at the bottom, or against another one — is\n * simply not drawn.\n */\nexport interface ComboboxSeparator {\n  separator: true\n}\n\n/** Anything the list may hold: an option, a named block, or a separator. */\nexport type ComboboxItem = ComboboxOption | ComboboxGroup | ComboboxSeparator\n\nconst isGroup = (item: ComboboxItem): item is ComboboxGroup => 'options' in item\nconst isSeparator = (item: ComboboxItem): item is ComboboxSeparator => 'separator' in item\n\n/**\n * How the list is narrowed as one types: by the component itself, not at all — when the\n * options already arrive filtered by a server — or by a rule of your own.\n */\nexport type ComboboxFilter = boolean | ((option: ComboboxOption, query: string) => boolean)\n\ninterface ComboboxProps {\n  /**\n   * What the list offers. An entry may be an option, a named block of options, or a\n   * separator; a plain list of options remains perfectly valid.\n   */\n  options: ComboboxItem[]\n  /**\n   * Allows several values to be chosen, which makes the value a list and shows what has\n   * been chosen as chips inside the field.\n   */\n  multiple?: boolean\n  /** The height of the field: 32, 40 or 48 pixels. */\n  size?: 'sm' | 'md' | 'lg'\n  /** Takes 4px off the height, as everywhere else in the design system. */\n  compact?: boolean\n  /** What the field says while nothing is chosen and nothing has been typed. */\n  placeholder?: string\n  /** Makes the field unusable, greyed out through the colour tokens. */\n  disabled?: boolean\n  /** Marks the field as invalid — for a rule of your own. */\n  invalid?: boolean\n  /** Offers a cross that empties both the selection and the search. */\n  clearable?: boolean\n  /** What the panel says when the search matches nothing. */\n  emptyText?: string\n  /**\n   * How the list is narrowed as one types. Turning it off means the options already\n   * arrive filtered by their source and are shown exactly as they come.\n   *\n   * A rule of your own receives the query as it was TYPED, merely trimmed — not the\n   * accent-insensitive form used internally.\n   */\n  filter?: ComboboxFilter\n  /**\n   * How long to wait before telling the source what is being searched for, in\n   * milliseconds. Zero tells it at once, which suits a source that is not a network\n   * request.\n   */\n  searchDebounce?: number\n  /**\n   * Says that something is being loaded. With no option yet, the whole panel says so;\n   * with options already listed, a spinner appears at the foot of the list, since what\n   * is loading is then the next page. Either way the field replaces its chevron with a\n   * spinner.\n   */\n  loading?: boolean\n  /** What is said while loading, and what the spinner is announced as. */\n  loadingText?: string\n  /**\n   * Says that there are more pages to come, which is what makes the component ask for\n   * the next one as the end of the list comes into view.\n   */\n  hasMore?: boolean\n}\n\nconst props = withDefaults(defineProps<ComboboxProps>(), {\n  multiple: false,\n  size: 'md',\n  compact: false,\n  placeholder: undefined,\n  disabled: false,\n  invalid: false,\n  clearable: true,\n  emptyText: undefined,\n  filter: true,\n  searchDebounce: 250,\n  loading: false,\n  loadingText: undefined,\n  hasMore: false,\n})\n\nconst m = useMessages()\nconst resolvedEmptyText = computed(() => props.emptyText ?? m.value.combobox.empty)\nconst resolvedLoadingText = computed(() => props.loadingText ?? m.value.common.loading)\n\nconst emit = defineEmits<{\n  /**\n   * What is being searched for, to be sent to the source. It is delayed by\n   * `searchDebounce` while typing, and emitted at once when the panel opens so that a\n   * first page can be loaded.\n   *\n   * The same term is never emitted twice in a row, so reopening the panel does not\n   * repeat a request that has already been answered.\n   */\n  search: [query: string]\n  /** The end of the list has come into view: send the next page. */\n  'load-more': []\n}>()\n\ndefineSlots<{\n  /**\n   * What a row of the list shows, in place of the plain label — a subtitle, an avatar,\n   * a badge. It is told whether the row is the highlighted one and whether it is\n   * already chosen, so the rendering can react to both.\n   */\n  option?(props: {\n    option: ComboboxOption\n    index: number\n    active: boolean\n    selected: boolean\n  }): unknown\n  /**\n   * Replaces the chip standing for one chosen value.\n   *\n   * Three of the values it receives are what make it usable without regressions:\n   * `remove`, without which the value could no longer be taken back, and the size and\n   * density worked out to sit inside the field, which cannot be guessed from outside.\n   * The option itself may be missing, if that value has never appeared among the\n   * options.\n   */\n  chip?(props: {\n    value: string\n    option: ComboboxOption | undefined\n    label: string\n    remove: () => void\n    size: 'xs' | 'sm'\n    compact: boolean\n  }): unknown\n  /** What the panel shows when nothing matches. It receives the term that was searched. */\n  empty?(props: { query: string }): unknown\n  /** What the panel shows while loading its first options. */\n  loading?(): unknown\n}>()\n\n// The size, the density and the HEIGHT of the chips sitting inside the field, worked out\n// once in `utils/chip.ts` and shared with VFileInput. The height is set inline below\n// rather than restated as a table of CSS rules: it is the height the field forces on its\n// input, and deriving both from the same pair is what stops them drifting apart.\nconst chipScale = computed(() => chipScaleFor(props.size, props.compact))\n\nconst model = defineModel<string | string[]>({ default: '' })\n\n// `class` and `style` stay on the wrapper, where a consumer expects to style the\n// component; everything else — a name above all — goes down to the text field, which is\n// the element assistive technology treats as the combobox.\ndefineOptions({ inheritAttrs: false })\nconst { rootClass, rootStyle, forwardedAttrs } = useRootAttrs()\n\nconst rootEl = ref<HTMLElement | null>(null)\nconst inputRef = ref<InstanceType<typeof VInput> | null>(null)\n// One generated identifier serves twice: as the panel's own id, which the field points\n// at, and as the prefix of every option's id. The two strings can never collide, one\n// being a prefix of longer ones.\nconst optionsId = useId()\n\nconst open = ref(false)\nconst query = ref('')\nconst activeIndex = ref(-1)\nconst focused = ref(false)\n// The text in the field serves two purposes at once: it SHOWS the chosen label when a\n// single value is picked, and it is what one searches with. This flag tells the two\n// apart — while it is false the text is merely a label and narrows nothing, so reopening\n// the panel offers the whole list again. It only becomes true once the reader types.\nconst typed = ref(false)\n\nconst selectedValues = computed<string[]>(() => {\n  if (props.multiple) return Array.isArray(model.value) ? model.value : []\n  return typeof model.value === 'string' && model.value ? [model.value] : []\n})\n\n// Every option, flattened: the blocks unwrapped, the separators dropped, in the order\n// they were given. This is the ONE reading of the options the rest of the component\n// does — the filtering, the memory of what was chosen, the labels and the paging all\n// ignore the hierarchy entirely. Only the rendering below knows about it.\nconst allOptions = computed<ComboboxOption[]>(() =>\n  props.options.flatMap((item) => {\n    if (isSeparator(item)) return []\n    return isGroup(item) ? item.options : [item]\n  }),\n)\n\n// A memory of the options that were CHOSEN. With a source that answers over the network,\n// the options only ever hold the latest results, and something already chosen is usually\n// absent from them — without this, a chip would show a raw identifier instead of a name,\n// and a custom chip would lose the option's icon.\n//\n// It is kept up to date by an effect rather than by watching the options, because the\n// effect tracks the ITERATION and therefore also notices a page appended in place. And\n// it is bounded to what is currently chosen: everything else is read from the options\n// themselves.\nconst optionCache = reactive(new Map<string, ComboboxOption>())\nwatchEffect(() => {\n  const wanted = new Set(selectedValues.value)\n  for (const option of allOptions.value) {\n    if (wanted.has(option.value)) optionCache.set(option.value, option)\n  }\n  // What is no longer chosen is forgotten. Without this the memory would grow with every\n  // value chosen during the session rather than with the current selection — a slow leak\n  // in a long-lived multiple field fed by a paginated source.\n  for (const value of optionCache.keys()) if (!wanted.has(value)) optionCache.delete(value)\n})\n\n/*\n * A lookup from value to option, built once per list of options rather than searched\n * each time. Finding an option is done several times per chip and per render — for the\n * chip itself, its label and the name of its remove button — so a linear search here\n * would cost the number of chips times the number of options, on every keystroke.\n *\n * The FIRST match wins, exactly as a search would have done, so a duplicated value keeps\n * the option that came first.\n */\nconst optionsByValue = computed(() => {\n  const map = new Map<string, ComboboxOption>()\n  for (const option of allOptions.value) if (!map.has(option.value)) map.set(option.value, option)\n  return map\n})\n\n/**\n * The selection as a set, so that asking \"is this one chosen?\" costs nothing however\n * many are — the same device VDataTable uses for its selected rows.\n */\nconst selectedSet = computed(() => new Set(selectedValues.value))\n\n/**\n * The option a value stands for: from the current options first, and from the memory of\n * chosen ones failing that.\n *\n * TRAP — an option coming from that memory is a reactive PROXY, since making the map\n * reactive converts the objects inside it. Compare options by their value and never by\n * identity, or the two forms of the same option will not match.\n */\nfunction optionOf(value: string) {\n  return optionsByValue.value.get(value) ?? optionCache.get(value)\n}\n\nfunction labelOf(value: string) {\n  return optionOf(value)?.label ?? value\n}\n\n/*\n * The labels in their accent-insensitive form, remembered per option and re-checked\n * against the label itself.\n *\n * Normalizing a string means decomposing it, stripping what it decomposed into, and\n * lowercasing it — and the filter below runs on every keystroke. Without this memory the\n * entire list would be normalized again for each character typed.\n *\n * Reading the label on every call, rather than deriving the whole table once, is what\n * keeps the filter reactive: a derived value keyed on the list alone would not notice a\n * label changed in place, since flattening the options only ever touches the containers.\n */\nconst normalizedLabels = new WeakMap<ComboboxOption, { label: string; normalized: string }>()\nfunction normalizedLabelOf(option: ComboboxOption): string {\n  const hit = normalizedLabels.get(option)\n  if (hit && hit.label === option.label) return hit.normalized\n  const normalized = normalizeText(option.label)\n  normalizedLabels.set(option, { label: option.label, normalized })\n  return normalized\n}\n\n// ONE search term, read both by the local filter and by what is sent to the source: the\n// list on screen and the request in flight therefore cannot describe different searches.\n// With nothing typed the term is empty, so a label merely being displayed never narrows\n// the list.\nconst searchTerm = computed(() => (typed.value ? query.value.trim() : ''))\n\n// The options that survive the search, flat and in the order they are shown. This is\n// what the keyboard counts through: blocks and separators do not appear in it, which is\n// exactly why the arrows never stop on one.\nconst filtered = computed(() => {\n  const matcher = props.filter\n  const list = allOptions.value\n  if (matcher === false) return list\n  const q = searchTerm.value\n  if (!q) return list\n  if (typeof matcher === 'function') return list.filter((o) => matcher(o, q))\n  const needle = normalizeText(q)\n  return list.filter((o) => normalizedLabelOf(o).includes(needle))\n})\n\n// @a11y\n/**\n * What is announced about the state of the panel — that nothing matches, or that\n * something is loading. It is emptied as soon as there are options to show: a region\n * that announces its changes must only ever hold what is new, or the same sentence is\n * read out again at every keystroke.\n */\nconst stateAnnouncement = computed(() => {\n  if (!open.value || filtered.value.length > 0) return ''\n  return props.loading ? resolvedLoadingText.value : resolvedEmptyText.value\n})\n\n// The render tree: the only place that knows about the hierarchy. Each option there\n// carries its index IN `filtered` (and not its position in the tree): ids, highlight\n// and the #option slot stay aligned on the keyboard navigation.\ntype RenderedOption = { kind: 'option'; key: string; option: ComboboxOption; index: number }\ntype RenderedNode =\n  | RenderedOption\n  | { kind: 'group'; key: string; label: string; options: RenderedOption[] }\n  | { kind: 'separator'; key: string }\n\nconst rendered = computed<RenderedNode[]>(() => {\n  const indexOf = new Map<string, number>()\n  filtered.value.forEach((option, index) => indexOf.set(option.value, index))\n\n  const entryOf = (option: ComboboxOption): RenderedOption | null => {\n    const index = indexOf.get(option.value)\n    if (index === undefined) return null\n    return { kind: 'option', key: `option:${option.value}`, option, index }\n  }\n\n  const nodes: RenderedNode[] = []\n  // A separator is held back and only drawn once something has come BEFORE it and\n  // something comes AFTER it. That single rule covers all three ways the filtering can\n  // strand one: at the top of the list, at the bottom, and two in a row.\n  let pendingSeparator: string | null = null\n\n  for (const [i, item] of props.options.entries()) {\n    if (isSeparator(item)) {\n      if (nodes.length > 0) pendingSeparator = `sep:${i}`\n      continue\n    }\n\n    let node: RenderedNode | null\n    if (isGroup(item)) {\n      const options = item.options\n        .map(entryOf)\n        .filter((entry): entry is RenderedOption => entry !== null)\n      // A block none of whose options survived is dropped entirely, its name included:\n      // a heading over nothing is worse than no heading.\n      node =\n        options.length > 0 ? { kind: 'group', key: `group:${i}`, label: item.label, options } : null\n    } else {\n      node = entryOf(item)\n    }\n    if (!node) continue\n\n    if (pendingSeparator !== null) {\n      nodes.push({ kind: 'separator', key: pendingSeparator })\n      pendingSeparator = null\n    }\n    nodes.push(node)\n  }\n\n  return nodes\n})\n\n// Telling an outside source what is being searched for. Nothing native waits before\n// sending a request, or refrains from sending the same one twice, so both have to be\n// written. The waiting itself is delegated to `useTimer` — re-arming, a delay of zero\n// running at once, cancellation when the component goes away — and what stays here is\n// specific to this component: not repeating a term, and giving up when the panel closes.\nconst searchTimer = useTimer()\n// The last term actually sent, or nothing if none ever was. It is what stops reopening\n// the panel on an unchanged term from firing the request again — a consumer with a cache\n// of their own is of course free to answer instantly.\nlet lastEmitted: string | undefined\n\nconst cancelSearch = searchTimer.cancel\n\nfunction emitSearch(term: string, immediate = false) {\n  cancelSearch()\n  if (term === lastEmitted) return\n  searchTimer.start(\n    () => {\n      // The panel may have closed while we were waiting: there is then nothing left to\n      // load, and the check has to happen HERE rather than before arming the timer.\n      if (!open.value) return\n      lastEmitted = term\n      emit('search', term)\n    },\n    immediate ? 0 : props.searchDebounce,\n  )\n}\n\nwatch(searchTerm, (term) => {\n  if (!open.value) return\n  // A new search means a new list, so the highlight cannot survive it: with an outside\n  // source the options are replaced wholesale, and the old position would name a\n  // completely unrelated option.\n  //\n  // It is moved to the first available option rather than dropped altogether, and that\n  // matters when the filtering is left to the source: the visible list keeps the very\n  // same reference until the answer arrives, so the watcher below would never fire and\n  // Enter would do nothing in the meantime. When the new list does arrive, the position\n  // is still within it and simply names its first option.\n  activeIndex.value = filtered.value.findIndex((o) => !o.disabled)\n  emitSearch(term)\n})\n\nwatch(filtered, (list) => {\n  // While the panel is open there must always be a valid option highlighted. It is moved\n  // back to the first result whenever the highlighted one has fallen out of the list OR\n  // there was none at all — without that second case, a search that passed through \"no\n  // result\" would leave nothing highlighted, and Enter would not choose the single\n  // result that came back.\n  if (!open.value) return\n  if (activeIndex.value < 0 || activeIndex.value >= list.length) {\n    activeIndex.value = list.findIndex((o) => !o.disabled)\n  }\n})\n\n// With a single value, the field shows its label as ordinary text whenever it is not\n// being edited.\nif (!props.multiple && typeof model.value === 'string' && model.value) {\n  query.value = labelOf(model.value)\n}\n\n// That label is a COPY and not something derived, so it has to be refreshed when the\n// options arrive later — otherwise a field mounted with a value but no options yet would\n// show a raw identifier for ever.\n//\n// ONLY the options are watched. Watching the value as well would bring back the\n// premature read that selecting deliberately avoids, and the two guards below are what\n// keep the refresh from ever overwriting something being typed.\nwatch(\n  allOptions,\n  () => {\n    if (props.multiple || open.value || typed.value) return\n    if (typeof model.value === 'string' && model.value) query.value = labelOf(model.value)\n  },\n  { flush: 'post' },\n)\n\n// With several values chosen and the field unfocused, the search input folds away so the\n// chips are not followed by an empty gap. It stays in the page and stays focusable —\n// only its width goes.\nconst collapsed = computed(\n  () => props.multiple && !focused.value && selectedValues.value.length > 0,\n)\n\n// The clear cross has to appear as soon as there is SOMETHING to clear — chosen values,\n// or a search in progress — and not merely when the text field holds text. The field\n// cannot work that out for itself, since the chips live outside its value, so the answer\n// is given to it explicitly, and the room for the cross is reserved accordingly.\nconst canClear = computed(\n  () =>\n    props.clearable &&\n    !props.disabled &&\n    (selectedValues.value.length > 0 || query.value.length > 0),\n)\n\nconst optionId = (index: number) => `${optionsId}-option-${index}`\n\n// A row has to be written twice in the template, once inside a block and once at the top\n// level of the panel, a Vue template having no way to declare a reusable fragment. These\n// two builders are what reduce that duplication to a single line on each side.\nfunction rowProps(entry: RenderedOption) {\n  return {\n    id: optionId(entry.index),\n    icon: entry.option.icon,\n    active: entry.index === activeIndex.value,\n    selected: selectedSet.value.has(entry.option.value),\n    disabled: entry.option.disabled,\n  }\n}\n\nfunction optionSlotProps(entry: RenderedOption) {\n  return {\n    option: entry.option,\n    index: entry.index,\n    active: entry.index === activeIndex.value,\n    selected: selectedSet.value.has(entry.option.value),\n  }\n}\n\nfunction hover(entry: RenderedOption) {\n  if (!entry.option.disabled) activeIndex.value = entry.index\n}\n\n// @a11y\n// Since the focus never leaves the field, the browser has no reason to scroll the\n// highlighted option into view — nothing was focused. It is brought into view by hand\n// instead, and asked for the SMALLEST movement that reveals it, so an option already\n// visible does not make the panel jump.\nwatch(activeIndex, (index) => {\n  if (index < 0) return\n  nextTick(() => {\n    // Called optionally: the unit-test environment implements no scrolling at all.\n    document.getElementById(optionId(index))?.scrollIntoView?.({ block: 'nearest' })\n  })\n})\n\nfunction openPanel() {\n  if (props.disabled || open.value) return\n  open.value = true\n  const list = filtered.value\n  const selectedIdx = list.findIndex((o) => !o.disabled && selectedSet.value.has(o.value))\n  activeIndex.value = selectedIdx >= 0 ? selectedIdx : list.findIndex((o) => !o.disabled)\n  // Told to the source AFTER the panel is marked open — the delayed emission checks that\n  // flag before firing — which is what lets an outside source load its first page as the\n  // panel appears.\n  emitSearch(searchTerm.value, true)\n}\n\n// Asking for the next page as the end of the list is reached. The observer itself, its\n// re-arming after each page and the lock that stops it firing twice all live in\n// `./infiniteScroll`; it is declared here so that closing the panel can reset it.\nconst sentinelEl = ref<HTMLElement | null>(null)\n\nconst infiniteScroll = useInfiniteScroll({\n  sentinelEl,\n  canLoad: () => open.value && props.hasMore && !props.loading,\n  loadedCount: () => allOptions.value.length,\n  onLoadMore: () => emit('load-more'),\n})\n\nfunction closePanel() {\n  if (!open.value) return\n  cancelSearch()\n  // A page that never arrived — a request that failed — must not leave the paging\n  // frozen for good, so the lock is released here.\n  infiniteScroll.reset()\n  open.value = false\n  activeIndex.value = -1\n  typed.value = false\n  query.value =\n    !props.multiple && typeof model.value === 'string' && model.value ? labelOf(model.value) : ''\n}\n\n/**\n * Closes as soon as the focus leaves the component — the panel included, which is a\n * descendant of it even while floating above the page.\n */\nconst onFocusout = useFocusoutDismiss(rootEl, closePanel)\n\n// @a11y\n/*\n * TRAP — the focus must never leave the field, and this is what prevents it. Without\n * cancelling the press, clicking an option takes the focus off the field, the handler\n * above closes the panel BEFORE the click is turned into a selection, and choosing with\n * the mouse stops working entirely.\n *\n * It is invisible in the unit tests, where clicking moves no focus; a browser test\n * covers it.\n */\nfunction onPanelMousedown(event: MouseEvent) {\n  event.preventDefault()\n}\n\n/** The reader is typing: the text becomes a search, and the panel opens. */\nfunction onInput() {\n  typed.value = true\n  openPanel()\n}\n\n/**\n * With a single value chosen, the label shown in the field is selected on focus, so that\n * typing replaces it rather than appending to it — and until something IS typed, the\n * whole list stays on offer.\n */\nfunction selectQuery() {\n  if (!props.multiple && query.value) inputRef.value?.select()\n}\n\nfunction onFocus() {\n  focused.value = true\n  selectQuery()\n}\n\n/** A click anywhere on the field focuses it and opens the panel. */\nfunction onControlClick() {\n  if (props.disabled) return\n  inputRef.value?.focus()\n  openPanel()\n  // Selected again AFTER the click, which has just placed the caret somewhere in the\n  // middle of the label.\n  selectQuery()\n}\n\nfunction select(option: ComboboxOption) {\n  if (option.disabled) return\n  // Remembered immediately: the option may vanish from the list — on the next search —\n  // before the parent has even passed the new value back down.\n  optionCache.set(option.value, option)\n  typed.value = false\n  if (props.multiple) {\n    model.value = toggleValue(selectedValues.value, option.value)\n    query.value = ''\n    inputRef.value?.focus()\n  } else {\n    model.value = option.value\n    // This path does not go through the closing function, so the pending search has to\n    // be cancelled here as well — otherwise the last keystroke would fire its request\n    // after the panel had closed.\n    cancelSearch()\n    // TRAP — the label is taken from the option just chosen and NOT by reading the value\n    // back. With a value bound by the parent, reading it immediately after writing still\n    // returns the OLD one, and the field would show the previously selected label.\n    query.value = option.label\n    open.value = false\n    activeIndex.value = -1\n  }\n}\n\nfunction removeValue(value: string) {\n  if (!props.multiple) return\n  model.value = selectedValues.value.filter((v) => v !== value)\n  inputRef.value?.focus()\n}\n\n/**\n * The clear cross was pressed. The field has already emptied the text it holds; what is\n * left to empty is the selection itself — the single value, or all the chips.\n */\nfunction onClear() {\n  model.value = props.multiple ? [] : ''\n  typed.value = false\n  activeIndex.value = -1\n}\n\n// @keyboard — moves the highlight, skipping over the options that cannot be chosen and\n// wrapping round from one end of the list to the other.\nfunction move(delta: number) {\n  const list = filtered.value\n  if (list.length === 0) return\n  let i = activeIndex.value\n  for (let step = 0; step < list.length; step++) {\n    i = (i + delta + list.length) % list.length\n    if (!list[i]?.disabled) break\n  }\n  activeIndex.value = i\n}\n\n// @keyboard @a11y — the whole keyboard of the pattern. The arrows move the POINTER\n// naming the current option and never the focus itself, which stays in the field\n// throughout; Backspace on an empty field takes back the last chip, the usual gesture in\n// a field holding several values.\nfunction onKeydown(event: KeyboardEvent) {\n  switch (event.key) {\n    case 'ArrowDown':\n      event.preventDefault()\n      if (open.value) move(1)\n      else openPanel()\n      break\n    case 'ArrowUp':\n      event.preventDefault()\n      if (open.value) move(-1)\n      else openPanel()\n      break\n    case 'Enter':\n      if (open.value && activeIndex.value >= 0) {\n        event.preventDefault()\n        const option = filtered.value[activeIndex.value]\n        if (option) select(option)\n      }\n      break\n    case 'Escape':\n      closePanel()\n      break\n    case 'Tab':\n      closePanel()\n      break\n    case 'Backspace':\n      if (props.multiple && !query.value) {\n        const last = selectedValues.value.at(-1)\n        if (last) removeValue(last)\n      }\n      break\n  }\n}\n</script>\n\n<template>\n  <div\n    ref=\"rootEl\"\n    class=\"v-combobox\"\n    :class=\"rootClass\"\n    :style=\"[{ '--chip-height': chipScale.height }, rootStyle]\"\n    :data-size=\"size\"\n    :data-compact=\"compact ? '' : undefined\"\n    :data-multiple=\"multiple ? '' : undefined\"\n    :data-collapsed=\"collapsed ? '' : undefined\"\n    :data-open=\"open ? '' : undefined\"\n    :data-can-clear=\"canClear ? '' : undefined\"\n    @focusout=\"onFocusout\"\n  >\n    <div class=\"v-combobox-control\" @click=\"onControlClick\">\n      <VInput\n        ref=\"inputRef\"\n        v-model=\"query\"\n        role=\"combobox\"\n        aria-haspopup=\"listbox\"\n        aria-autocomplete=\"list\"\n        :aria-expanded=\"open\"\n        :aria-controls=\"optionsId\"\n        v-bind=\"forwardedAttrs\"\n        :size=\"size\"\n        :compact=\"compact\"\n        :invalid=\"invalid\"\n        :disabled=\"disabled\"\n        :clearable=\"clearable\"\n        :clear-visible=\"canClear\"\n        :clear-label=\"m.combobox.clear\"\n        :placeholder=\"selectedValues.length === 0 ? placeholder : undefined\"\n        :aria-activedescendant=\"open && activeIndex >= 0 ? optionId(activeIndex) : undefined\"\n        @input=\"onInput\"\n        @keydown=\"onKeydown\"\n        @focus=\"onFocus\"\n        @blur=\"focused = false\"\n        @clear=\"onClear\"\n      >\n        <template v-if=\"multiple\" #start>\n          <template v-for=\"value in selectedValues\" :key=\"value\">\n            <slot\n              name=\"chip\"\n              :value=\"value\"\n              :option=\"optionOf(value)\"\n              :label=\"labelOf(value)\"\n              :remove=\"() => removeValue(value)\"\n              :size=\"chipScale.size\"\n              :compact=\"chipScale.compact\"\n            >\n              <VChip\n                tone=\"accent\"\n                :size=\"chipScale.size\"\n                :compact=\"chipScale.compact\"\n                dismissible\n                :dismiss-label=\"m.combobox.remove(labelOf(value))\"\n                :disabled=\"disabled\"\n                @dismiss=\"removeValue(value)\"\n                >{{ labelOf(value) }}</VChip\n              >\n            </slot>\n          </template>\n        </template>\n\n        <!-- The chevron sits at the end of the field and turns as the panel opens; the\n             clear cross is rendered by the field itself, to its left.\n\n             While loading, the spinner takes EXACTLY the chevron's place — the field\n             gives a spinner among its direct children the size of an icon — so nothing\n             shifts. The field's own loading option is deliberately not used: it would\n             overwrite this slot, chevron and all.\n\n             The spinner is hidden from screen readers, which neutralizes the status role\n             it carries: what announces the loading is the panel, and once is enough. -->\n        <template #end>\n          <VSpinner v-if=\"loading\" class=\"v-combobox-spinner\" aria-hidden=\"true\" />\n          <VIcon v-else :name=\"expandMoreIcon\" class=\"v-combobox-chevron\" aria-hidden=\"true\" />\n        </template>\n      </VInput>\n    </div>\n\n    <!-- TRAP — the panel itself carries BOTH the listbox role and the scrolling. That\n         single fact is what the observer watching for the end of the list and the\n         scrolling of the highlighted option both rely on: inserting any wrapper between\n         them breaks the two at once. -->\n    <VPopover\n      :id=\"optionsId\"\n      v-model:open=\"open\"\n      mode=\"manual\"\n      anchor=\"--combobox-anchor\"\n      placement=\"bottom-start\"\n      role=\"listbox\"\n      class=\"v-combobox-panel v-control\"\n      :data-size=\"size\"\n      :data-compact=\"compact ? '' : undefined\"\n      :aria-multiselectable=\"multiple ? 'true' : undefined\"\n      @mousedown=\"onPanelMousedown\"\n    >\n      <!-- Blocks and separators exist for the eye alone: the keyboard counts through the\n           flat list of surviving options and therefore never encounters one. -->\n      <template v-for=\"node in rendered\" :key=\"node.key\">\n        <VComboboxSeparator v-if=\"node.kind === 'separator'\" />\n\n        <VComboboxGroup v-else-if=\"node.kind === 'group'\" :label=\"node.label\">\n          <VComboboxOption\n            v-for=\"entry in node.options\"\n            :key=\"entry.key\"\n            v-bind=\"rowProps(entry)\"\n            @select=\"select(entry.option)\"\n            @pointermove=\"hover(entry)\"\n          >\n            <slot name=\"option\" v-bind=\"optionSlotProps(entry)\">{{ entry.option.label }}</slot>\n          </VComboboxOption>\n        </VComboboxGroup>\n\n        <VComboboxOption\n          v-else\n          v-bind=\"rowProps(node)\"\n          @select=\"select(node.option)\"\n          @pointermove=\"hover(node)\"\n        >\n          <slot name=\"option\" v-bind=\"optionSlotProps(node)\">{{ node.option.label }}</slot>\n        </VComboboxOption>\n      </template>\n\n      <!-- The order matters: loading is checked BEFORE emptiness, so that a panel\n           waiting for an answer never claims there is no result.\n\n           Both are hidden from screen readers, and that is not an oversight. A listbox\n           may contain nothing but options and blocks of options, so any other visible\n           child would make the panel invalid — where an EMPTY listbox is perfectly\n           acceptable. What they say is announced instead by the live region outside the\n           panel, which is also the only way a screen reader would ever hear it: plain\n           text sitting inside a combobox's popup is not part of what the field walks\n           through. -->\n      <div v-if=\"loading && filtered.length === 0\" class=\"v-combobox-state\" aria-hidden=\"true\">\n        <slot name=\"loading\">\n          <VSpinner :label=\"resolvedLoadingText\" />\n          <span>{{ resolvedLoadingText }}</span>\n        </slot>\n      </div>\n      <div v-else-if=\"filtered.length === 0\" class=\"v-combobox-state\" aria-hidden=\"true\">\n        <slot name=\"empty\" :query=\"searchTerm\">{{ resolvedEmptyText }}</slot>\n      </div>\n\n      <!-- One element serves as both the marker watched for the end of the list and the\n           place the next-page spinner appears. TRAP — it has to stay a SINGLE element:\n           rendering the spinner conditionally in its place would destroy the marker and\n           silently cancel the observation, and no further page would ever be asked\n           for. -->\n      <div v-if=\"hasMore\" ref=\"sentinelEl\" class=\"v-combobox-more\" aria-hidden=\"true\">\n        <VSpinner v-if=\"loading\" :label=\"resolvedLoadingText\" />\n      </div>\n    </VPopover>\n\n    <!-- The spoken counterpart of the two panel states above. It sits OUTSIDE the\n         listbox, being exactly the kind of content a listbox may not contain. -->\n    <span class=\"v-visually-hidden\" role=\"status\">{{ stateAnnouncement }}</span>\n  </div>\n</template>\n\n<style>\n@layer vectis.components {\n  .v-combobox {\n    /* Confines the anchor name to this instance. It is declared on the root because that\n       is the common ancestor of the field and the panel — a panel drawn above the page\n       remains a descendant of it in the document. */\n    anchor-scope: --combobox-anchor;\n    width: 100%;\n    font-family: var(--vectis-text-family);\n  }\n\n  .v-combobox-control {\n    anchor-name: --combobox-anchor;\n    display: block;\n  }\n\n  /* The panel comes from VPopover, which brings the floating element, its open state, its\n     anchoring, its placement and its surface. It also carries the shared size class, so\n     the options and the state rows read their dimensions from it with no size table\n     here. What stays are the two things specific to a list: a width tied to the field\n     below it, and the scrolling. */\n  .v-combobox-panel {\n    min-inline-size: anchor-size(width);\n    max-block-size: var(--vectis-control-size-combobox-list-max-block);\n    overflow: auto;\n  }\n\n  /* The chevron and the clear cross are lifted out of the field's flow, so that they stay\n     pinned to its end and vertically centred whatever the chips do and whether or not the\n     input has folded away.\n\n     The room they occupy is then reserved with padding, or the text and the chips would\n     run underneath them. That reservation is written as exactly what the flow would have\n     produced with them left in place — one glyph's width each from the field's padding,\n     one gap between two of them — which is what keeps this field's spacing identical to\n     every other field in the design system. It reads from the same two variables as the\n     insets below, so the room reserved and the glyphs it protects cannot drift apart.\n\n     Vertically they are centred with a translation kept SEPARATE from the rotation, since\n     the chevron turns when the panel opens. */\n  .v-combobox .v-input-field {\n    position: relative;\n    padding-inline-end: calc(\n      var(--control-padding-inline-field) + var(--vectis-icon-size) + var(--control-gap)\n    );\n  }\n\n  .v-combobox[data-can-clear] .v-input-field {\n    padding-inline-end: calc(\n      var(--control-padding-inline-field) + 2 * var(--vectis-icon-size) + 2 * var(--control-gap)\n    );\n  }\n\n  /* The chevron and the spinner take turns in the same place and occupy the same box —\n     the field gives a spinner among its direct children the size of an icon — so the\n     padding reserved above serves both, and swapping one for the other shifts\n     nothing. */\n  .v-combobox-chevron,\n  .v-combobox-spinner {\n    position: absolute;\n    inset-inline-end: var(--control-padding-inline-field);\n    top: 50%;\n    translate: 0 -50%;\n    color: var(--vectis-color-text-muted);\n  }\n\n  .v-combobox-chevron {\n    transition: rotate var(--vectis-duration-fast) var(--vectis-ease-default);\n  }\n\n  .v-combobox[data-open] .v-combobox-chevron {\n    rotate: 180deg;\n  }\n\n  /* The clear cross goes just before the chevron, centred the same way.\n\n     TRAP — both insets are measured to the GLYPH's edge, and they get there by different\n     routes: the chevron is a bare icon, whose box IS its glyph, while the cross is one of\n     the field's buttons, whose negative margin — half the difference between icon and\n     button — cancels its own overhang. Because of that the arithmetic reads directly: one\n     glyph's width from the field's padding, then one gap between the two.\n\n     That gap is the field's own, which is the entire point: a number written here instead\n     would drift from every other field in the design system, with nothing to signal\n     it. */\n  .v-combobox .v-input-clear {\n    position: absolute;\n    inset-inline-end: calc(\n      var(--control-padding-inline-field) + var(--vectis-icon-size) + var(--control-gap)\n    );\n    top: 50%;\n    translate: 0 -50%;\n  }\n\n  /* With several values allowed, the field holds the chips and lets them WRAP onto\n     several rows, growing instead of scrolling — but never shrinking below the height of\n     an ordinary control.\n\n     The chips' height is written inline by the same helper that gives them their size,\n     because it belongs to their own subtree and the field cannot read it. The input is\n     then forced to that SAME height rather than the full height it inherits: its natural\n     height is greater than a chip's, and the field would grow the moment it was focused.\n\n     The result is a field that stays exactly one control tall, an input never taller than\n     the chips beside it, and no jump when the focus arrives. */\n  .v-combobox[data-multiple] .v-input-field {\n    flex-wrap: wrap;\n    height: auto;\n    min-height: var(--control-height);\n    padding-block: var(--vectis-space-1);\n  }\n\n  .v-combobox[data-multiple] .v-input-control {\n    height: var(--chip-height);\n  }\n\n  /* Folded away, the input is taken out of the flow entirely rather than merely narrowed:\n     even at zero width it would still occupy a line of its own under the chips and leave\n     a visible gap.\n\n     It remains in the page and remains focusable — clicking the field or tabbing into it\n     brings it straight back, the folded state ending as soon as it has the focus. */\n  .v-combobox[data-collapsed] .v-input-control {\n    position: absolute;\n    width: 0;\n    height: 0;\n    padding: 0;\n  }\n\n  /* The rows saying \"nothing matches\" or \"loading\" are built like an option: they read\n     the same inherited dimensions from the panel, and the spinner follows through the\n     same block's icon context. They refuse to shrink, the panel being a bounded column\n     that would otherwise squash them. */\n  .v-combobox-state {\n    display: flex;\n    flex: none;\n    align-items: center;\n    gap: var(--control-gap);\n    min-height: var(--control-height);\n    padding: var(--vectis-space-1) var(--control-padding-inline);\n    font-size: var(--control-font-size);\n    color: var(--vectis-color-text-muted);\n  }\n\n  /* The foot of the list: the marker watched for the end, and the place the next-page\n     spinner appears. It is given a real height on purpose — a box of no height at all\n     makes the crossing it is watched for unreliable. */\n  .v-combobox-more {\n    display: flex;\n    flex: none;\n    align-items: center;\n    justify-content: center;\n    min-height: var(--vectis-space-6);\n    color: var(--vectis-color-text-muted);\n  }\n\n  @media (prefers-reduced-motion: reduce) {\n    .v-combobox-chevron {\n      transition: none;\n    }\n  }\n}\n</style>\n"],"mappings":""}