gbs-add-block 1.2.8 → 1.2.10

package/source/beta-components/combobox/core/filter.ts

@@ -0,0 +1,155 @@
+import type {
+  ComboboxOption,
+  ListItem,
+  MatchRange,
+  OptionEntry,
+  OptionValue,
+} from "./types";
+
+/** Ranges of `text` matching every search term, or null when one term is missing. */
+export function matchRanges(text: string, terms: readonly string[]): MatchRange[] | null {
+  if (terms.length === 0) return [];
+  const haystack = text.toLocaleLowerCase();
+  const ranges: MatchRange[] = [];
+  for (const term of terms) {
+    const start = haystack.indexOf(term);
+    if (start === -1) return null;
+    ranges.push([start, start + term.length]);
+  }
+  return mergeRanges(ranges);
+}
+
+function mergeRanges(ranges: MatchRange[]): MatchRange[] {
+  const sorted = [...ranges].sort((a, b) => a[0] - b[0]);
+  const merged: MatchRange[] = [];
+  for (const range of sorted) {
+    const last = merged.at(-1);
+    if (last && range[0] <= last[1]) last[1] = Math.max(last[1], range[1]);
+    else merged.push([...range]);
+  }
+  return merged;
+}
+
+export const splitTerms = (search: string) =>
+  search.trim().toLocaleLowerCase().split(/\s+/).filter(Boolean);
+
+/**
+ * Filters options by search text. The label is matched first; description and
+ * keywords also match but are not highlighted.
+ */
+export function filterOptions<V extends OptionValue>(
+  options: readonly ComboboxOption<V>[],
+  search: string,
+  filterFn?: (option: ComboboxOption<V>, search: string) => boolean,
+): OptionEntry<V>[] {
+  const terms = splitTerms(search);
+  if (terms.length === 0 && !filterFn) {
+    return options.map((option) => ({ option, matches: [] }));
+  }
+
+  const entries: OptionEntry<V>[] = [];
+  for (const option of options) {
+    if (filterFn) {
+      if (filterFn(option, search)) entries.push({ option, matches: matchRanges(option.label, terms) ?? [] });
+      continue;
+    }
+    const labelMatches = matchRanges(option.label, terms);
+    if (labelMatches) {
+      entries.push({ option, matches: labelMatches });
+      continue;
+    }
+    const extra = [option.description, ...(option.keywords ?? [])].filter(Boolean).join(" ");
+    if (extra && matchRanges(extra, terms)) entries.push({ option, matches: [] });
+  }
+  return entries;
+}
+
+/** Adds group headings, keeping the order in which groups first appear. */
+export function buildListItems<V extends OptionValue>(entries: readonly OptionEntry<V>[]): ListItem<V>[] {
+  const hasGroups = entries.some((entry) => entry.option.group);
+  if (!hasGroups) {
+    return entries.map((entry, index) => ({ kind: "option", entry, index }));
+  }
+
+  const groups = new Map<string, OptionEntry<V>[]>();
+  for (const entry of entries) {
+    const key = entry.option.group ?? "";
+    const list = groups.get(key);
+    if (list) list.push(entry);
+    else groups.set(key, [entry]);
+  }
+
+  const items: ListItem<V>[] = [];
+  let index = 0;
+  for (const [group, list] of groups) {
+    if (group) items.push({ kind: "group", label: group });
+    for (const entry of list) items.push({ kind: "option", entry, index: index++ });
+  }
+  return items;
+}
+
+/** Next selectable option index, skipping disabled options. Wraps around. */
+export function nextEnabledIndex<V extends OptionValue>(
+  entries: readonly OptionEntry<V>[],
+  from: number,
+  delta: number,
+): number {
+  const count = entries.length;
+  if (count === 0) return -1;
+  let index = from;
+  for (let step = 0; step < count; step++) {
+    index = index + delta;
+    if (index < 0) index = count - 1;
+    if (index >= count) index = 0;
+    if (!entries[index].option.disabled) return index;
+  }
+  return -1;
+}
+
+/** First selectable option at or after `from` (searching forward, no wrap). */
+export function firstEnabledIndex<V extends OptionValue>(
+  entries: readonly OptionEntry<V>[],
+  from = 0,
+): number {
+  for (let index = Math.max(0, from); index < entries.length; index++) {
+    if (!entries[index].option.disabled) return index;
+  }
+  for (let index = Math.min(from, entries.length) - 1; index >= 0; index--) {
+    if (!entries[index].option.disabled) return index;
+  }
+  return -1;
+}
+
+export function lastEnabledIndex<V extends OptionValue>(entries: readonly OptionEntry<V>[]): number {
+  for (let index = entries.length - 1; index >= 0; index--) {
+    if (!entries[index].option.disabled) return index;
+  }
+  return -1;
+}
+
+/** Adds or removes a value, respecting `max` (ignored when removing). */
+export function toggleValue<V extends OptionValue>(
+  values: readonly V[],
+  value: V,
+  max?: number,
+): V[] {
+  if (values.includes(value)) return values.filter((v) => v !== value);
+  if (max !== undefined && values.length >= max) return [...values];
+  return [...values, value];
+}
+
+/** Index of the first option matching a typed prefix, for type-ahead. */
+export function findByPrefix<V extends OptionValue>(
+  entries: readonly OptionEntry<V>[],
+  prefix: string,
+  from: number,
+): number {
+  const needle = prefix.toLocaleLowerCase();
+  const count = entries.length;
+  for (let step = 1; step <= count; step++) {
+    const index = (from + step + count) % count;
+    const { option } = entries[index];
+    if (!option.disabled && option.label.toLocaleLowerCase().startsWith(needle)) return index;
+  }
+  return -1;
+}

package/source/beta-components/combobox/core/index.ts

@@ -0,0 +1,16 @@
+// Framework-free helpers: the same filtering and list building the components
+// use, so a server (or a test) can reproduce them.
+export {
+  buildListItems,
+  filterOptions,
+  findByPrefix,
+  firstEnabledIndex,
+  lastEnabledIndex,
+  matchRanges,
+  nextEnabledIndex,
+  splitTerms,
+  toggleValue,
+} from "./filter";
+export { getVisibleRange, measureItems, scrollToItem } from "./virtual";
+export type { ItemSizes, ListMetrics, Range } from "./virtual";
+export type * from "./types";

package/source/beta-components/combobox/core/types.ts

@@ -0,0 +1,48 @@
+import type { ReactNode } from "react";
+
+export type OptionValue = string | number;
+
+export interface ComboboxOption<V extends OptionValue = string> {
+  value: V;
+  label: string;
+  /** Secondary line shown under the label. */
+  description?: string;
+  /** Options with the same group are listed under one heading. */
+  group?: string;
+  disabled?: boolean;
+  /** Rendered before the label. */
+  icon?: ReactNode;
+  /** Extra text the search should match (synonyms, codes). */
+  keywords?: string[];
+}
+
+/** Character range of a search hit, used to highlight the label. */
+export type MatchRange = [start: number, end: number];
+
+export interface OptionEntry<V extends OptionValue = string> {
+  option: ComboboxOption<V>;
+  /** Ranges in `option.label` that matched the search. */
+  matches: MatchRange[];
+}
+
+/** One row of the rendered list: a group heading or an option. */
+export type ListItem<V extends OptionValue = string> =
+  | { kind: "group"; label: string }
+  | { kind: "option"; entry: OptionEntry<V>; index: number };
+
+export type ComboboxSize = "sm" | "md" | "lg";
+
+export interface ComboboxLocaleText {
+  searchPlaceholder: string;
+  noResults: string;
+  loading: string;
+  loadMore: string;
+  clear: string;
+  clearAll: string;
+  selectAll: string;
+  createOption(label: string): string;
+  selectedCount(count: string): string;
+  moreCount(count: string): string;
+  removeOption(label: string): string;
+  maxReached(max: string): string;
+}

package/source/beta-components/combobox/core/virtual.ts

@@ -0,0 +1,67 @@
+import type { ListItem, OptionValue } from "./types";
+
+export interface ItemSizes {
+  option: number;
+  group: number;
+}
+
+export interface ListMetrics {
+  /** Offset of each item, plus the total height as the last entry. */
+  offsets: number[];
+  total: number;
+}
+
+export function measureItems<V extends OptionValue>(
+  items: readonly ListItem<V>[],
+  sizes: ItemSizes,
+): ListMetrics {
+  const offsets = new Array<number>(items.length + 1);
+  let offset = 0;
+  for (let i = 0; i < items.length; i++) {
+    offsets[i] = offset;
+    offset += items[i].kind === "group" ? sizes.group : sizes.option;
+  }
+  offsets[items.length] = offset;
+  return { offsets, total: offset };
+}
+
+export interface Range {
+  start: number;
+  end: number;
+}
+
+/** Items intersecting the visible window, plus overscan. */
+export function getVisibleRange(metrics: ListMetrics, scrollTop: number, height: number, overscan = 4): Range {
+  const count = metrics.offsets.length - 1;
+  if (count === 0 || height === 0) return { start: 0, end: count };
+
+  const find = (position: number) => {
+    let lo = 0;
+    let hi = count;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (metrics.offsets[mid + 1] <= position) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  };
+
+  const start = find(scrollTop);
+  const end = find(scrollTop + height) + 1;
+  return { start: Math.max(0, start - overscan), end: Math.min(count, end + overscan) };
+}
+
+/** Scroll position that brings an item fully into view, or null if it already is. */
+export function scrollToItem(
+  metrics: ListMetrics,
+  itemIndex: number,
+  scrollTop: number,
+  height: number,
+): number | null {
+  const top = metrics.offsets[itemIndex];
+  const bottom = metrics.offsets[itemIndex + 1];
+  if (top === undefined || bottom === undefined) return null;
+  if (top < scrollTop) return top;
+  if (bottom > scrollTop + height) return bottom - height;
+  return null;
+}

package/source/beta-components/combobox/index.ts

@@ -0,0 +1,13 @@
+export { Select } from "./react/Select";
+export type { SelectProps } from "./react/Select";
+export { MultiSelect } from "./react/MultiSelect";
+export type { MultiSelectProps } from "./react/MultiSelect";
+export { useCombobox } from "./react/useCombobox";
+export { defaultComboboxText } from "./react/locale";
+export type {
+  ComboboxHandle,
+  ComboboxSharedProps,
+  ComboboxSlot,
+  OptionState,
+} from "./react/props";
+export * from "./core";

package/source/beta-components/combobox/react/Listbox.tsx

@@ -0,0 +1,302 @@
+"use client";
+
+import {
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type KeyboardEvent,
+  type ReactNode,
+  type RefObject,
+  type UIEvent,
+} from "react";
+import type {
+  ComboboxLocaleText,
+  ComboboxOption,
+  ComboboxSize,
+  ListItem,
+  MatchRange,
+  OptionValue,
+} from "../core/types";
+import { getVisibleRange, measureItems, scrollToItem } from "../core/virtual";
+import { CheckIcon, PlusIcon, SearchIcon, SpinnerIcon } from "./icons";
+import { cx, type ComboboxSlot, type OptionState } from "./props";
+
+const OPTION_HEIGHT: Record<ComboboxSize, number> = { sm: 30, md: 34, lg: 40 };
+const GROUP_HEIGHT = 26;
+const DESCRIPTION_EXTRA = 16;
+const VIRTUALIZE_FROM = 80;
+
+interface ListboxProps<V extends OptionValue> {
+  listboxId: string;
+  labelledBy: string;
+  items: ListItem<V>[];
+  optionCount: number;
+  activeIndex: number;
+  multiple: boolean;
+  size: ComboboxSize;
+  maxHeight: number;
+  virtualize: boolean | number;
+  loading: boolean;
+  hasMore?: boolean;
+  searchable: boolean;
+  search: string;
+  searchRef: RefObject<HTMLInputElement | null>;
+  listRef: RefObject<HTMLDivElement | null>;
+  text: ComboboxLocaleText;
+  classNames: Partial<Record<ComboboxSlot, string>> | undefined;
+  emptyMessage: ReactNode;
+  createLabel: string | null;
+  footer?: ReactNode;
+  getOptionId(index: number): string;
+  isSelected(value: V): boolean;
+  onSelect(option: ComboboxOption<V>): void;
+  onActiveIndexChange(index: number): void;
+  onSearchChange(search: string): void;
+  onKeyDown(event: KeyboardEvent<HTMLElement>): void;
+  onLoadMore?(): void;
+  onCreate(): void;
+  renderOption?(option: ComboboxOption<V>, state: OptionState): ReactNode;
+}
+
+function Highlight({ text, matches }: { text: string; matches: MatchRange[] }) {
+  if (matches.length === 0) return text;
+  const parts: ReactNode[] = [];
+  let cursor = 0;
+  matches.forEach(([start, end], i) => {
+    if (start > cursor) parts.push(text.slice(cursor, start));
+    parts.push(
+      <mark className="cb-mark" key={i}>
+        {text.slice(start, end)}
+      </mark>,
+    );
+    cursor = end;
+  });
+  if (cursor < text.length) parts.push(text.slice(cursor));
+  return parts;
+}
+
+export function Listbox<V extends OptionValue>({
+  listboxId,
+  labelledBy,
+  items,
+  optionCount,
+  activeIndex,
+  multiple,
+  size,
+  maxHeight,
+  virtualize,
+  loading,
+  hasMore,
+  searchable,
+  search,
+  searchRef,
+  listRef,
+  text,
+  classNames,
+  emptyMessage,
+  createLabel,
+  footer,
+  getOptionId,
+  isSelected,
+  onSelect,
+  onActiveIndexChange,
+  onSearchChange,
+  onKeyDown,
+  onLoadMore,
+  onCreate,
+  renderOption,
+}: ListboxProps<V>) {
+  const [scrollTop, setScrollTop] = useState(0);
+
+  const hasDescription = useMemo(
+    () => items.some((item) => item.kind === "option" && item.entry.option.description),
+    [items],
+  );
+  const sizes = useMemo(
+    () => ({
+      option: OPTION_HEIGHT[size] + (hasDescription ? DESCRIPTION_EXTRA : 0),
+      group: GROUP_HEIGHT,
+    }),
+    [size, hasDescription],
+  );
+
+  const isVirtual =
+    typeof virtualize === "number" ? optionCount > virtualize : virtualize && optionCount > VIRTUALIZE_FROM;
+  const metrics = useMemo(() => measureItems(items, sizes), [items, sizes]);
+  const listHeight = Math.min(maxHeight, metrics.total + 8);
+
+  // Item index of each option, so the active option can be scrolled into view.
+  const itemIndexByOption = useMemo(() => {
+    const map = new Array<number>(optionCount);
+    items.forEach((item, index) => {
+      if (item.kind === "option") map[item.index] = index;
+    });
+    return map;
+  }, [items, optionCount]);
+
+  useLayoutEffect(() => {
+    const el = listRef.current;
+    const itemIndex = itemIndexByOption[activeIndex];
+    if (!el || activeIndex < 0 || itemIndex === undefined) return;
+    const next = scrollToItem(metrics, itemIndex, el.scrollTop, el.clientHeight);
+    if (next !== null) {
+      el.scrollTop = next;
+      setScrollTop(next);
+    }
+  }, [activeIndex, itemIndexByOption, metrics, listRef]);
+
+  // If the list is already scrolled to the end when new options arrive, no
+  // scroll event follows, so ask for the next page once per list length.
+  const autoLoadedAt = useRef(-1);
+  useLayoutEffect(() => {
+    const el = listRef.current;
+    if (!el || !hasMore || loading || !onLoadMore || autoLoadedAt.current === items.length) return;
+    if (el.scrollHeight - el.scrollTop - el.clientHeight < 80) {
+      autoLoadedAt.current = items.length;
+      onLoadMore();
+    }
+  }, [hasMore, loading, onLoadMore, items.length, listRef]);
+
+  const onScroll = (event: UIEvent<HTMLDivElement>) => {
+    const el = event.currentTarget;
+    setScrollTop(el.scrollTop);
+    if (hasMore && !loading && onLoadMore && el.scrollTop + el.clientHeight >= metrics.total - 80) {
+      onLoadMore();
+    }
+  };
+
+  const range = isVirtual
+    ? getVisibleRange(metrics, scrollTop, listHeight)
+    : { start: 0, end: items.length };
+
+  const renderItem = (item: ListItem<V>, itemIndex: number): ReactNode => {
+    const style: CSSProperties | undefined = isVirtual
+      ? { top: metrics.offsets[itemIndex], height: item.kind === "group" ? sizes.group : sizes.option }
+      : undefined;
+
+    if (item.kind === "group") {
+      return (
+        <div key={`group-${item.label}-${itemIndex}`} className="cb-group" role="presentation" style={style}>
+          {item.label}
+        </div>
+      );
+    }
+
+    const { option, matches } = item.entry;
+    const selected = isSelected(option.value);
+    const active = activeIndex === item.index;
+    return (
+      <div
+        key={String(option.value)}
+        id={getOptionId(item.index)}
+        role="option"
+        aria-selected={selected}
+        aria-disabled={option.disabled || undefined}
+        className={cx("cb-item", classNames?.option)}
+        style={style}
+        data-active={active || undefined}
+        data-selected={selected || undefined}
+        data-disabled={option.disabled || undefined}
+        // Keep focus in the search box so typing continues to work.
+        onPointerDown={(event) => event.preventDefault()}
+        onPointerMove={() => !option.disabled && !active && onActiveIndexChange(item.index)}
+        onClick={() => !option.disabled && onSelect(option)}
+      >
+        <CheckIcon className="cb-item-check" />
+        {option.icon && <span className="cb-item-icon">{option.icon}</span>}
+        {renderOption ? (
+          renderOption(option, { selected, active })
+        ) : (
+          <span className="cb-item-body">
+            <span className="cb-item-label">
+              <Highlight text={option.label} matches={matches} />
+            </span>
+            {option.description && <span className="cb-item-description">{option.description}</span>}
+          </span>
+        )}
+      </div>
+    );
+  };
+
+  const empty = items.length === 0 && !createLabel;
+
+  return (
+    <>
+      {searchable && (
+        <div className={cx("cb-search", classNames?.search)}>
+          <SearchIcon />
+          <input
+            ref={searchRef}
+            type="text"
+            role="combobox"
+            aria-expanded="true"
+            aria-controls={listboxId}
+            aria-autocomplete="list"
+            aria-activedescendant={activeIndex >= 0 ? getOptionId(activeIndex) : undefined}
+            aria-label={text.searchPlaceholder}
+            autoComplete="off"
+            spellCheck={false}
+            data-autofocus=""
+            placeholder={text.searchPlaceholder}
+            value={search}
+            onChange={(event) => onSearchChange(event.target.value)}
+            onKeyDown={onKeyDown}
+          />
+          {loading && <SpinnerIcon aria-label={text.loading} />}
+        </div>
+      )}
+
+      <div
+        ref={listRef}
+        id={listboxId}
+        role="listbox"
+        aria-labelledby={labelledBy}
+        aria-multiselectable={multiple || undefined}
+        className={cx("cb-list", classNames?.list)}
+        style={{ height: empty ? undefined : listHeight }}
+        data-virtual={isVirtual || undefined}
+        tabIndex={searchable ? -1 : 0}
+        onScroll={onScroll}
+        onKeyDown={searchable ? undefined : onKeyDown}
+      >
+        {isVirtual && <div style={{ height: metrics.total }} aria-hidden="true" />}
+        {items.slice(range.start, range.end).map((item, i) => renderItem(item, range.start + i))}
+
+        {createLabel && (
+          <div
+            role="option"
+            aria-selected={false}
+            className="cb-item cb-create"
+            data-active={activeIndex === -1 || undefined}
+            onPointerDown={(event) => event.preventDefault()}
+            onClick={onCreate}
+          >
+            <PlusIcon className="cb-item-check" style={{ opacity: 1 }} />
+            <span className="cb-item-body">
+              <span className="cb-item-label">{text.createOption(createLabel)}</span>
+            </span>
+          </div>
+        )}
+
+        {empty && !loading && <div className="cb-empty">{emptyMessage ?? text.noResults}</div>}
+        {loading && items.length === 0 && (
+          <div className="cb-status">
+            <SpinnerIcon />
+            {text.loading}
+          </div>
+        )}
+        {hasMore && items.length > 0 && (
+          <div className="cb-status">
+            <button type="button" className="cb-link-button" disabled={loading} onClick={() => onLoadMore?.()}>
+              {loading ? text.loading : text.loadMore}
+            </button>
+          </div>
+        )}
+      </div>
+
+      {footer && <div className={cx("cb-footer", classNames?.footer)}>{footer}</div>}
+    </>
+  );
+}