gbs-add-block 1.2.7 → 1.2.9

package/source/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/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/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>}
+    </>
+  );
+}

package/source/components/combobox/react/MultiSelect.tsx

@@ -0,0 +1,263 @@
+"use client";
+
+import { useId, useImperativeHandle, useMemo, useRef, type Ref } from "react";
+import type { ComboboxOption, OptionValue } from "../core/types";
+import { ChevronIcon, XIcon } from "./icons";
+import { Listbox } from "./Listbox";
+import { defaultComboboxText } from "./locale";
+import { ComboboxPopover } from "./Popover";
+import { cx, type ComboboxHandle, type ComboboxSharedProps } from "./props";
+import { useCombobox } from "./useCombobox";
+
+export interface MultiSelectProps<V extends OptionValue = string> extends ComboboxSharedProps<V> {
+  value?: V[];
+  defaultValue?: V[];
+  onChange?(values: NoInfer<V>[], options: ComboboxOption<NoInfer<V>>[]): void;
+  /** Maximum number of selections. */
+  max?: number;
+  /** Tags shown before collapsing into "+N more". Default 3. */
+  maxVisibleTags?: number;
+  /** Show "Select all" / "Clear all" under the list. Default true. */
+  showSelectAll?: boolean;
+  /** Close the list after each choice. Default false. */
+  closeOnSelect?: boolean;
+  ref?: Ref<ComboboxHandle<V>>;
+}
+
+/** Multi-select combobox: tags, option search and select-all. */
+export function MultiSelect<V extends OptionValue = string>(props: MultiSelectProps<V>) {
+  const {
+    ref,
+    value,
+    defaultValue,
+    onChange,
+    max,
+    maxVisibleTags = 3,
+    showSelectAll = true,
+    closeOnSelect = false,
+    options,
+    label,
+    placeholder = "Select…",
+    description,
+    error,
+    required = false,
+    disabled = false,
+    clearable = true,
+    size = "md",
+    name,
+    id: idProp,
+    className,
+    classNames,
+    style,
+    localeText,
+    maxHeight = 280,
+    virtualize = true,
+    emptyMessage,
+    searchable = true,
+    loading = false,
+    hasMore,
+    onLoadMore,
+    renderOption,
+  } = props;
+
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  const text = useMemo(() => ({ ...defaultComboboxText, ...localeText }), [localeText]);
+
+  const controlRef = useRef<HTMLDivElement>(null);
+  const searchRef = useRef<HTMLInputElement>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+
+  const combobox = useCombobox<V>({
+    controlRef,
+    searchRef,
+    listRef,
+    ...props,
+    multiple: true,
+    closeOnSelect,
+    max,
+    value,
+    defaultValue: defaultValue ?? [],
+    onValuesChange: (values, selectedOptions) => onChange?.(values, selectedOptions),
+    text,
+    id,
+  });
+
+  const { selectedOptions } = combobox;
+  const hidden = Math.max(0, selectedOptions.length - maxVisibleTags);
+  const visibleTags = hidden > 0 ? selectedOptions.slice(0, maxVisibleTags) : selectedOptions;
+
+  useImperativeHandle(ref, () => combobox.handle, [combobox.handle]);
+
+  const selectableVisible = combobox.entries.filter(
+    (entry) => !entry.option.disabled && !combobox.isSelected(entry.option.value),
+  );
+  const canSelectAll =
+    showSelectAll &&
+    selectableVisible.length > 0 &&
+    (max === undefined || selectedOptions.length + selectableVisible.length <= max);
+
+  return (
+    <div
+      className={cx("cb-root", classNames?.root, className)}
+      style={style}
+      data-size={size}
+      data-state={combobox.open ? "open" : "closed"}
+      data-invalid={error ? "" : undefined}
+    >
+      {label && (
+        <span id={`${id}-label`} className={cx("cb-label", classNames?.label)} data-required={required || undefined}>
+          {label}
+        </span>
+      )}
+
+      <div
+        ref={controlRef}
+        id={id}
+        role="combobox"
+        tabIndex={disabled ? -1 : 0}
+        aria-expanded={combobox.open}
+        aria-haspopup="listbox"
+        aria-controls={combobox.open ? combobox.listboxId : undefined}
+        aria-labelledby={label ? `${id}-label` : undefined}
+        aria-describedby={cx(description ? `${id}-description` : "", error ? `${id}-error` : "") || undefined}
+        aria-required={required || undefined}
+        aria-invalid={error ? true : undefined}
+        aria-disabled={disabled || undefined}
+        className={cx("cb-control", classNames?.control)}
+        data-disabled={disabled || undefined}
+        data-invalid={error ? "" : undefined}
+        onPointerDown={combobox.onControlPointerDown}
+        onClick={combobox.onControlClick}
+        onKeyDown={combobox.onKeyDown}
+      >
+        {selectedOptions.length === 0 ? (
+          <span className={cx("cb-value", classNames?.value)}>
+            <span className="cb-placeholder">{placeholder}</span>
+          </span>
+        ) : (
+          <span className="cb-tags">
+            {visibleTags.map((option) => (
+              <span key={String(option.value)} className={cx("cb-tag", classNames?.tag)}>
+                <span className="cb-tag-label">{option.label}</span>
+                {!disabled && (
+                  <button
+                    type="button"
+                    tabIndex={-1}
+                    className="cb-tag-remove"
+                    aria-label={text.removeOption(option.label)}
+                    onClick={(event) => {
+                      event.stopPropagation();
+                      combobox.removeValue(option.value);
+                    }}
+                  >
+                    <XIcon width={12} height={12} />
+                  </button>
+                )}
+              </span>
+            ))}
+            {hidden > 0 && <span className="cb-tag-overflow">{text.moreCount(String(hidden))}</span>}
+          </span>
+        )}
+
+        <span className="cb-actions">
+          {clearable && selectedOptions.length > 0 && !disabled && (
+            <button
+              type="button"
+              tabIndex={-1}
+              className="cb-icon-button"
+              aria-label={text.clearAll}
+              onClick={(event) => {
+                event.stopPropagation();
+                combobox.clear();
+              }}
+            >
+              <XIcon width={14} height={14} />
+            </button>
+          )}
+          <ChevronIcon className="cb-chevron" />
+        </span>
+      </div>
+
+      {name &&
+        selectedOptions.map((option) => (
+          <input key={String(option.value)} type="hidden" name={name} value={option.value} />
+        ))}
+      {description && (
+        <span id={`${id}-description`} className="cb-description">
+          {description}
+        </span>
+      )}
+      {error && (
+        <span id={`${id}-error`} className="cb-error" role="alert">
+          {error}
+        </span>
+      )}
+
+      {combobox.anchor && (
+        <ComboboxPopover
+          anchor={combobox.anchor}
+          onClose={combobox.onPopoverClose}
+          className={classNames?.popover}
+        >
+          <Listbox<V>
+            listboxId={combobox.listboxId}
+            labelledBy={label ? `${id}-label` : id}
+            items={combobox.items}
+            optionCount={combobox.entries.length}
+            activeIndex={combobox.activeIndex}
+            multiple
+            size={size}
+            maxHeight={maxHeight}
+            virtualize={virtualize}
+            loading={loading}
+            hasMore={hasMore}
+            searchable={searchable}
+            search={combobox.search}
+            searchRef={searchRef}
+            listRef={listRef}
+            text={text}
+            classNames={classNames}
+            emptyMessage={emptyMessage}
+            createLabel={combobox.createLabel}
+            getOptionId={combobox.getOptionId}
+            isSelected={combobox.isSelected}
+            onSelect={combobox.selectOption}
+            onActiveIndexChange={combobox.setActiveIndex}
+            onSearchChange={combobox.setSearch}
+            onKeyDown={combobox.onKeyDown}
+            onLoadMore={onLoadMore}
+            onCreate={combobox.commitCreate}
+            renderOption={renderOption}
+            footer={
+              <>
+                <span className="cb-footer-count">
+                  {max !== undefined && selectedOptions.length >= max
+                    ? text.maxReached(String(max))
+                    : text.selectedCount(String(selectedOptions.length))}
+                </span>
+                <span>
+                  {canSelectAll && (
+                    <button
+                      type="button"
+                      className="cb-link-button"
+                      onClick={() => combobox.selectAllVisible()}
+                    >
+                      {text.selectAll}
+                    </button>
+                  )}
+                  {selectedOptions.length > 0 && (
+                    <button type="button" className="cb-link-button" onClick={() => combobox.clear()}>
+                      {text.clearAll}
+                    </button>
+                  )}
+                </span>
+              </>
+            }
+          />
+        </ComboboxPopover>
+      )}
+      {options.length === 0 && loading && <span className="cb-sr-only">{text.loading}</span>}
+    </div>
+  );
+}