@arbor-education/design-system.components 0.6.0 → 0.7.0

package/src/components/combobox/combobox.scss

@@ -0,0 +1,390 @@
+.ds-combobox {
+  position: relative;
+  width: 100%;
+}
+
+// Trigger area
+.ds-combobox__trigger {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-small);
+  min-height: var(--form-field-text-medium-height);
+  padding: var(--spacing-xsmall) var(--spacing-small);
+  border: var(--border-weight) solid var(--form-field-combobox-default-color-border);
+  border-radius: var(--form-field-radius);
+  background-color: var(--form-field-combobox-default-color-background);
+  color: var(--form-field-combobox-default-color-text);
+  cursor: text;
+  transition: border-color 0.2s, box-shadow 0.2s, background-color 0.2s;
+  box-sizing: border-box;
+  font-style: normal;
+  line-height: 150%;
+
+  &:hover:not(.ds-combobox__trigger--disabled) {
+    border-color: var(--form-field-combobox-hover-color-border);
+    background-color: var(--form-field-combobox-hover-color-background);
+  }
+
+  &:focus-within:not(.ds-combobox__trigger--disabled) {
+    border-color: var(--form-field-combobox-focus-color-border);
+    background-color: var(--form-field-combobox-focus-color-background);
+    outline: var(--focus-border) solid var(--form-field-combobox-focus-color-border);
+  }
+
+  &--error {
+    border-color: var(--form-field-combobox-error-color-border);
+
+    &:focus-within {
+      border-color: var(--form-field-combobox-error-color-border);
+      box-shadow: 0 0 0 var(--focus-border) var(--form-field-combobox-error-color-border);
+    }
+  }
+
+  &--disabled {
+    background-color: var(--form-field-combobox-disabled-color-background);
+    border-color: var(--form-field-combobox-disabled-color-border);
+    color: var(--form-field-combobox-disabled-color-text);
+    cursor: not-allowed;
+  }
+
+  &--button {
+    cursor: pointer;
+  }
+}
+
+.ds-combobox__chips-and-input {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--spacing-xsmall);
+  flex: 1;
+  min-width: 0;
+}
+
+.ds-combobox__button-content {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-xsmall);
+  flex: 1;
+  min-width: 0;
+}
+
+.ds-combobox__button-tags-viewport {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+}
+
+.ds-combobox__button-tags-track {
+  display: inline-flex;
+  width: auto;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--spacing-xsmall);
+}
+
+.ds-combobox__button-placeholder {
+  color: var(--form-field-combobox-placeholder-color-text);
+  white-space: nowrap;
+}
+
+.ds-combobox__button-ellipsis {
+  flex-shrink: 0;
+  font-size: var(--font-size-medium);
+  margin-left: var(--spacing-xsmall);
+}
+
+.ds-combobox__measure {
+  position: absolute;
+  visibility: hidden;
+  pointer-events: none;
+  left: -9999px;
+  top: -9999px;
+  white-space: nowrap;
+  width: max-content;
+  height: 0;
+  overflow: hidden;
+}
+
+// Input
+.ds-combobox__input {
+  flex: 1;
+  min-width: 80px;
+  border: none;
+  outline: none;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  padding: 0;
+  line-height: var(--line-height-default);
+
+  &::placeholder {
+    color: var(--form-field-combobox-placeholder-color-text);
+  }
+
+  .ds-combobox__trigger--disabled & {
+    cursor: not-allowed;
+  }
+}
+
+// Chevron
+.ds-combobox__chevron {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: transparent;
+  padding: 0;
+  color: inherit;
+  cursor: pointer;
+
+  .ds-combobox__trigger--disabled & {
+    cursor: not-allowed;
+  }
+}
+
+// Popover
+.ds-combobox__popover {
+  min-width: var(--radix-popper-anchor-width);
+
+  &:focus {
+    outline: none;
+  }
+}
+
+// Listbox
+.ds-combobox__listbox {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  max-height: min(
+    var(--form-field-combobox-listbox-max-height),
+    var(--radix-popper-available-height, 150px)
+  );
+  overflow-y: auto;
+}
+
+.ds-combobox__listbox-search-row {
+  list-style: none;
+  background: var(--form-dropdown-color-background);
+  margin-bottom: var(--spacing-small);
+}
+
+.ds-combobox__listbox-search-input-wrap {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-xsmall);
+  width: 100%;
+  border: var(--border-weight) solid var(--form-field-combobox-default-color-border);
+  border-radius: var(--border-radius-round);
+  padding: var(--spacing-xsmall) var(--spacing-small);
+  box-sizing: border-box;
+}
+
+.ds-combobox__input--in-listbox {
+  min-width: 0;
+  width: 100%;
+}
+
+// Loading row uses the same spacing as one option row.
+.ds-combobox__loading-row {
+  list-style: none;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: calc(2 * var(--form-dropdown-form-drop-item-spacing-vertical) + 1.5em);
+  padding: var(--form-dropdown-form-drop-item-spacing-vertical) var(--form-dropdown-form-drop-item-spacing-horizontal);
+}
+
+.ds-combobox__loading-status {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--form-dropdown-form-drop-item-default-color-text);
+}
+
+.ds-combobox__loading-spinner {
+  display: inline-flex;
+  animation: ds-combobox-loader-spin 0.8s linear infinite;
+}
+
+@keyframes ds-combobox-loader-spin {
+  from {
+    transform: rotate(0deg);
+  }
+
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@mixin ds-combobox-option-surface {
+  display: flex;
+  align-items: center;
+  gap: var(--form-dropdown-form-drop-item-spacing-gap-horizontal);
+  padding: var(--form-dropdown-form-drop-item-spacing-vertical) var(--form-dropdown-form-drop-item-spacing-horizontal);
+  border-radius: var(--form-dropdown-form-drop-item-radius, 8px);
+  background: var(--form-dropdown-form-drop-item-default-color-background);
+  color: var(--form-dropdown-form-drop-item-default-color-text);
+  cursor: pointer;
+}
+
+.ds-combobox__option-row {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-xsmall);
+  list-style: none;
+
+  > .ds-combobox__option {
+    @include ds-combobox-option-surface;
+
+    flex: 1;
+    min-width: 0;
+  }
+
+  &--highlighted > .ds-combobox__option {
+    background: var(--form-dropdown-form-drop-item-hover-color-background);
+    outline: none;
+  }
+
+  &--selected > .ds-combobox__option {
+    background: var(--form-dropdown-form-drop-item-active-color-background);
+    color: var(--form-dropdown-form-drop-item-active-color-text);
+  }
+
+  &--disabled > .ds-combobox__option {
+    pointer-events: none;
+    opacity: 0.5;
+  }
+}
+
+// Ensures selected options are distinguishable when 'focused'.
+.ds-combobox__option-row--selected.ds-combobox__option-row--highlighted > .ds-combobox__option {
+  background: var(--form-dropdown-form-drop-item-hover-color-background);
+  color: var(--form-dropdown-form-drop-item-default-color-text);
+}
+
+// Standalone option (e.g. create row) — full width on the <li>
+li.ds-combobox__option {
+  @include ds-combobox-option-surface;
+
+  list-style: none;
+
+  &--highlighted {
+    background: var(--form-dropdown-form-drop-item-hover-color-background);
+    outline: none;
+  }
+
+  &--selected {
+    background: var(--form-dropdown-form-drop-item-active-color-background);
+    color: var(--form-dropdown-form-drop-item-active-color-text);
+  }
+
+  &--disabled {
+    pointer-events: none;
+    opacity: 0.5;
+  }
+}
+
+.ds-combobox__option--selected.ds-combobox__option--highlighted {
+  background: var(--form-dropdown-form-drop-item-hover-color-background);
+  color: var(--form-dropdown-form-drop-item-default-color-text);
+}
+
+
+.ds-combobox__option-label {
+  flex: 1;
+  min-width: 0;
+}
+
+.ds-combobox__option-match {
+  background: var(--color-semantic-caution-100);
+  color: inherit;
+  font-weight: var(--font-weight-semi-bold);
+  padding: 0;
+}
+
+.ds-combobox__option-check {
+  margin-left: auto;
+  display: flex;
+  align-items: center;
+}
+
+.ds-combobox__option-delete {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: transparent;
+  padding: var(--spacing-xsmall);
+  cursor: pointer;
+  color: var(--form-dropdown-form-drop-item-default-color-text);
+  opacity: 0.75;
+  border-radius: var(--form-dropdown-form-drop-item-radius, 8px);
+  transition: opacity 0.15s;
+}
+
+.ds-combobox__option-delete:hover {
+  opacity: 1;
+  outline: none;
+
+}
+
+.ds-combobox__option-delete:focus-visible {
+  opacity: 1;
+  outline: var(--focus-border) solid var(--form-field-combobox-focus-color-border);
+}
+
+
+// Create row
+.ds-combobox__create-row {
+  font-style: italic;
+}
+
+// Groups
+.ds-combobox__group {
+  list-style: none;
+}
+
+.ds-combobox__group-header {
+  padding: var(--form-dropdown-form-drop-item-spacing-vertical) var(--form-dropdown-form-drop-item-spacing-horizontal);
+  font-weight: var(--font-weight-semi-bold);
+  font-size: var(--font-size-xs);
+  color: var(--search-list-color-header);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.ds-combobox__group-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+// Clear all
+.ds-combobox__clear-all-wrapper {
+  display: flex;
+  justify-content: flex-end;
+  margin-top: var(--spacing-xsmall);
+}
+
+.ds-combobox__clear-all {
+  border: none;
+  background: transparent;
+  color: var(--form-field-combobox-help-text-default-color-text);
+  cursor: pointer;
+  font-size: var(--font-size-sm);
+  text-decoration: underline;
+  padding: 0;
+
+  &:hover {
+    color: var(--form-field-combobox-help-text-hover-color-text);
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+}

package/src/components/combobox/comboboxKeyboardTypes.ts

@@ -0,0 +1,45 @@
+import type { ComboboxOption } from './types';
+
+export type UseComboboxChipKeyboardParams = {
+  inputRef: React.RefObject<HTMLInputElement | null>;
+  clearAll: () => void;
+  clearChipSelection: () => void;
+  exitChipNav: () => void;
+  focusedChipIndex: number | null;
+  removeValue: (optionValue: string) => void;
+  selectedChipValues: string[];
+  selectedValues: string[];
+  setFocusedChipIndex: React.Dispatch<React.SetStateAction<number | null>>;
+};
+
+export type UseComboboxListboxKeyboardParams = {
+  allowCreate: boolean;
+  clearChipSelection: () => void;
+  exitChipNav: () => void;
+  focusDeleteButtonForHighlighted?: () => boolean;
+  listboxOptions: ComboboxOption[];
+  focusedChipIndex: number | null;
+  handleCreate: () => void;
+  highlightIndex: number;
+  isOpen: boolean;
+  mergedOptions: ComboboxOption[];
+  openPopover: () => void;
+  query: string;
+  removeValue: (optionValue: string) => void;
+  scrollHighlightedIntoView: (index: number) => void;
+  selectOption: (optionValue: string) => void;
+  selectedChipValues: string[];
+  selectedValues: string[];
+  setHighlightIndex: React.Dispatch<React.SetStateAction<number>>;
+  setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
+  setQuery: React.Dispatch<React.SetStateAction<string>>;
+  showCreateRow: boolean;
+  showListboxLoading: boolean;
+  totalItems: number;
+};
+
+export type UseComboboxKeyboardParams = UseComboboxChipKeyboardParams
+  & UseComboboxListboxKeyboardParams
+  & {
+    setSelectedChipValues: React.Dispatch<React.SetStateAction<string[]>>;
+  };

package/src/components/combobox/highlightLabel.tsx

@@ -0,0 +1,42 @@
+import type { ComboboxSearchType } from './types';
+
+type HighlightLabelOptions = {
+  label: string;
+  query: string;
+  searchType: ComboboxSearchType;
+  highlightStringMatches: boolean;
+};
+
+export const highlightLabel = ({
+  label,
+  query,
+  searchType,
+  highlightStringMatches,
+}: HighlightLabelOptions): React.ReactNode => {
+  const trimmedQuery = query.trim();
+  if (!highlightStringMatches || !trimmedQuery || typeof searchType === 'function') {
+    return label;
+  }
+
+  const lowerLabel = label.toLowerCase();
+  const lowerQuery = trimmedQuery.toLowerCase();
+  const matchStart
+    = searchType === 'prefix'
+      ? (lowerLabel.startsWith(lowerQuery) ? 0 : -1)
+      : lowerLabel.indexOf(lowerQuery);
+
+  if (matchStart === -1) {
+    return label;
+  }
+
+  const matchEnd = matchStart + trimmedQuery.length;
+  return (
+    <>
+      {matchStart > 0 && label.slice(0, matchStart)}
+      <mark className="ds-combobox__option-match">
+        {label.slice(matchStart, matchEnd)}
+      </mark>
+      {matchEnd < label.length && label.slice(matchEnd)}
+    </>
+  );
+};

package/src/components/combobox/normaliseComboboxQuery.ts

@@ -0,0 +1 @@
+export const normaliseComboboxQuery = (value: string) => value.trim().toLowerCase();

package/src/components/combobox/types.ts

@@ -0,0 +1,53 @@
+import type { IconName } from 'Components/icon/allowedIcons';
+import type React from 'react';
+
+/** Matches DOM / ARIA `aria-invalid` (boolean and grammar/spelling, etc.). */
+export type ComboboxAriaInvalid = React.AriaAttributes['aria-invalid'];
+
+export type ComboboxOption = {
+  value: string;
+  label: string;
+  tagLabel?: string;
+  iconName?: IconName;
+  disabled?: boolean;
+  group?: string;
+};
+
+export type ComboboxCreateResult = string | ComboboxOption | void;
+export type ComboboxSearchFn = (option: ComboboxOption, query: string) => boolean;
+export type ComboboxSearchType = 'prefix' | 'substring' | ComboboxSearchFn;
+
+export type ComboboxProps = {
+  'options': ComboboxOption[];
+  'multiple'?: boolean;
+  'value'?: string[];
+  'defaultValue'?: string[];
+  'onValueChange'?: (values: string[]) => void;
+
+  'onSearch'?: (query: string) => void;
+  'searchType'?: ComboboxSearchType;
+  'highlightStringMatches'?: boolean;
+
+  'allowCreate'?: boolean;
+  'onCreateNew'?: (inputValue: string) => ComboboxCreateResult;
+  'onDeleteCreated'?: (value: string) => void;
+
+  'placeholder'?: string;
+  'disabled'?: boolean;
+  'dropdownOnFocus'?: boolean;
+  'triggerVariant'?: 'input' | 'button';
+  'showDropdownTrigger'?: boolean;
+  'showSelectionCountBadge'?: boolean;
+  'selectionCountA11yLabel'?: string | ((count: number) => string);
+  'loading'?: boolean;
+  'hasError'?: boolean;
+  'showClearAll'?: boolean;
+  'clearAllLabel'?: string;
+  'renderOption'?: (option: ComboboxOption, selected: boolean) => React.ReactNode;
+  'getTagLabel'?: (option: ComboboxOption) => string;
+
+  'id'?: string;
+  'aria-describedby'?: string;
+  'aria-invalid'?: ComboboxAriaInvalid;
+  'aria-label'?: string;
+};

package/src/components/combobox/useChipSelection.ts

@@ -0,0 +1,53 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+export type UseChipSelectionReturn = {
+  selectedChipValues: string[];
+  selectedChipValuesSet: Set<string>;
+  setSelectedChipValues: React.Dispatch<React.SetStateAction<string[]>>;
+  clearChipSelection: () => void;
+  focusedChipIndex: number | null;
+  setFocusedChipIndex: React.Dispatch<React.SetStateAction<number | null>>;
+  exitChipNav: () => void;
+};
+
+export const useChipSelection = (selectedValues: string[]): UseChipSelectionReturn => {
+  const [selectedChipValues, setSelectedChipValues] = useState<string[]>([]);
+  const [focusedChipIndex, setFocusedChipIndex] = useState<number | null>(null);
+
+  const selectedChipValuesSet = useMemo(
+    () => new Set(selectedChipValues),
+    [selectedChipValues],
+  );
+
+  const clearChipSelection = useCallback(() => {
+    setSelectedChipValues([]);
+    setFocusedChipIndex(null);
+  }, []);
+
+  const exitChipNav = useCallback(() => {
+    setFocusedChipIndex(null);
+  }, []);
+
+  useEffect(() => {
+    setSelectedChipValues((prev) => {
+      if (prev.length === 0) return prev;
+      return prev.filter(value => selectedValues.includes(value));
+    });
+  }, [selectedValues]);
+
+  useEffect(() => {
+    if (focusedChipIndex !== null && focusedChipIndex >= selectedValues.length) {
+      setFocusedChipIndex(selectedValues.length > 0 ? selectedValues.length - 1 : null);
+    }
+  }, [selectedValues.length, focusedChipIndex]);
+
+  return {
+    selectedChipValues,
+    selectedChipValuesSet,
+    setSelectedChipValues,
+    clearChipSelection,
+    focusedChipIndex,
+    setFocusedChipIndex,
+    exitChipNav,
+  };
+};