Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
12.2 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file TransferListSelector.tsx
 * @input Controlled option data, uncontrolled ComplexSelector state, action
 *   controls and the core i18n catalog. Also TransferList with the owner's
 *   reorderable object, adapted through Core's internal reorder entry and
 *   aimed at the draft when staged
 * @output Exports the immediate-or-staged TransferListSelector composition with draft cleanup after dismissal
 * @position Lab collection input shell; consumed by the TransferList entry point, docs, and tests
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/lab/src/TransferList/TransferListSelector.test.tsx
 * - /packages/lab/src/TransferList/TransferList.doc.mjs
 * - /packages/lab/src/TransferList/index.ts
 */

import {useCallback, useEffect, useRef, useState, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {Button} from '@astryxdesign/core/Button';
import {
  ComplexSelector,
  type ComplexSelectorProps,
} from '@astryxdesign/core/ComplexSelector';
import {useTranslator} from '@astryxdesign/core/i18n';
import {HStack} from '@astryxdesign/core/Stack';
import {borderVars, colorVars} from '@astryxdesign/core/theme/tokens.stylex';
import type {Reorderable} from '@astryxdesign/core';
import {
  adaptReorderable,
  reorderableOptions,
} from '@astryxdesign/core/internal/reorder';
import {TransferList, type TransferListProps} from './TransferList';

const DEFAULT_SELECTOR_WIDTH = 'min(41rem, calc(100vw - 32px))';

const styles = stylex.create({
  // Width tracks the `width` prop, so the field and its popup are one
  // measurement rather than two that can disagree.
  content: (width: string) => ({
    width,
    maxWidth: width,
    maxHeight: 'calc(100vh - 32px)',
    padding: 0,
    overflow: 'hidden',
    borderRadius: 'inherit',
  }),
  surface: {
    display: 'flex',
    flexDirection: 'column',
    minWidth: 0,
    minHeight: 0,
    maxHeight: 'inherit',
  },
  fieldset: {
    flexGrow: 1,
    flexShrink: 1,
    flexBasis: 'auto',
    minWidth: 0,
    minHeight: 0,
    margin: 0,
    padding: 0,
    borderWidth: 0,
    borderStyle: 'none',
    overflowY: 'auto',
    overscrollBehavior: 'contain',
  },
  // Busy is not disabled: `disabled` on this fieldset would blur the Add or
  // Remove button the user just activated, dropping focus to <body>. The
  // pending state is carried by aria-busy plus the trigger's spinner, so this
  // only has to read as unavailable to the pointer.
  fieldsetBusy: {
    cursor: {
      default: 'progress',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
  },
  footer: {
    flexShrink: 0,
    borderBlockStartWidth: borderVars['--border-width'],
    borderBlockStartStyle: 'solid',
    borderBlockStartColor: colorVars['--color-border'],
    backgroundColor: colorVars['--color-background-surface'],
  },
});

type TransferListSelectorShellProp =
  | 'label'
  | 'triggerLabel'
  | 'isLabelHidden'
  | 'description'
  | 'isOptional'
  | 'isRequired'
  | 'isDisabled'
  | 'isLoading'
  | 'status'
  | 'statusVariant'
  | 'labelTooltip'
  | 'size'
  | 'width'
  | 'placement'
  | 'controlXstyle'
  | 'controlClassName'
  | 'controlStyle'
  | 'data-testid';

type TransferListContentProp =
  | 'options'
  | 'selectedLabel'
  | 'availableLabel'
  | 'hasSearch'
  | 'searchLabel'
  | 'searchPlaceholder'
  | 'hasSelectAll'
  | 'hasClear'
  | 'renderOption'
  | 'selectedEmptyText'
  | 'availableEmptyText'
  | 'noResultsText';

export type TransferListSelectorCommitBehavior = 'immediate' | 'staged';

export type TransferListSelectorProps<T extends string = string> = Pick<
  ComplexSelectorProps<readonly T[]>,
  TransferListSelectorShellProp
> &
  Pick<TransferListProps<T>, TransferListContentProp> & {
    /** Ordered values applied outside the selector. */
    value: readonly T[];
    /** Called whenever a value is committed. */
    onChange: (value: readonly T[]) => void;
    /** Optional async action after a changed value is applied. */
    changeAction?: (value: readonly T[]) => void | Promise<void>;
    /**
     * Controls when changes are committed. Immediate commits each list edit and
     * staged waits for Apply. @default 'immediate'
     */
    commitBehavior?: TransferListSelectorCommitBehavior;
    /** Label for the staged commit action. Only used in staged behavior. @default 'Apply' */
    applyLabel?: string;
    /** Label for the staged discard action. Only used in staged behavior. @default 'Cancel' */
    cancelLabel?: string;
    /**
     * Makes the selected options reorderable: pass the object
     * `createReorderable` makes. Its `isReorderable(value)` says which values
     * move. An immediate selector hands each move to its `onReorder`. A
     * staged one moves its draft instead, so Cancel drops the move with the
     * draft, and Apply commits it through `onChange`. Without it, the
     * selected options keep their order.
     */
    reorderable?: Reorderable<T>;
  };

/** `value` with `key` moved to index `to`. */
function moveValue<T>(value: readonly T[], key: T, to: number): readonly T[] {
  const next = value.filter(item => item !== key);
  next.splice(to, 0, key);
  return next;
}

function areOrderedValuesEqual<T>(
  first: readonly T[],
  second: readonly T[],
): boolean {
  return (
    first.length === second.length &&
    first.every((item, index) => item === second[index])
  );
}

function ResetDraftAfterClose({
  isOpen,
  resetDraft,
}: {
  isOpen: boolean;
  resetDraft: () => void;
}): null {
  const wasOpenRef = useRef(isOpen);

  useEffect(() => {
    if (wasOpenRef.current && !isOpen) {
      resetDraft();
    }
    wasOpenRef.current = isOpen;
  }, [isOpen, resetDraft]);

  return null;
}

/**
 * A transfer-list field that opens in a selector popover.
 *
 * The field label, description, and trigger remain outside the popup. Changes
 * commit immediately by default. Set commitBehavior="staged" when the workflow
 * needs explicit Apply and Cancel actions.
 *
 * @example
 * ```
 * <TransferListSelector
 *   label="Visible fields"
 *   options={columnOptions}
 *   value={visibleColumns}
 *   onChange={setVisibleColumns}
 * />
 * ```
 */
export function TransferListSelector<T extends string = string>({
  label,
  description,
  options,
  value,
  onChange,
  changeAction,
  commitBehavior = 'immediate',
  triggerLabel,
  isDisabled,
  isLoading,
  width,
  applyLabel: applyLabelFromProps,
  cancelLabel: cancelLabelFromProps,
  selectedLabel,
  availableLabel,
  hasSearch,
  searchLabel,
  searchPlaceholder,
  reorderable: ownerReorderable,
  hasSelectAll,
  hasClear,
  renderOption,
  selectedEmptyText,
  availableEmptyText,
  noResultsText,
  ...selectorProps
}: TransferListSelectorProps<T>): ReactNode {
  const t = useTranslator();
  const applyLabel =
    applyLabelFromProps ?? t('@astryx.transferListSelector.apply');
  const cancelLabel =
    cancelLabelFromProps ?? t('@astryx.transferListSelector.cancel');
  const [draftValue, setDraftValue] = useState<readonly T[]>(value);

  const resetDraft = useCallback(() => {
    setDraftValue([...value]);
  }, [value]);

  // A changed applied value or commit behavior discards the staged draft.
  // Adjusted during render, so no commit paints the discarded draft.
  const [draftSource, setDraftSource] = useState(() => ({
    value: [...value],
    commitBehavior,
  }));
  if (
    !areOrderedValuesEqual(draftSource.value, value) ||
    !Object.is(draftSource.commitBehavior, commitBehavior)
  ) {
    setDraftSource({value: [...value], commitBehavior});
    setDraftValue([...value]);
  }

  const resolvedWidth =
    typeof width === 'number'
      ? `${width}px`
      : (width ?? DEFAULT_SELECTOR_WIDTH);

  return (
    <ComplexSelector
      {...selectorProps}
      label={label}
      description={description}
      value={value}
      onChange={onChange}
      changeAction={changeAction}
      triggerLabel={
        triggerLabel ??
        t('@astryx.transferListSelector.triggerLabel', {count: value.length})
      }
      isDisabled={isDisabled}
      isLoading={isLoading}
      width={resolvedWidth}
      contentXstyle={styles.content(resolvedWidth)}>
      {(appliedValue, commit, close, state) => {
        const isStaged = commitBehavior === 'staged';
        const transferListValue = isStaged ? draftValue : appliedValue;
        // The owner's reorder, aimed at the draft when staged and handed to
        // the owner when immediate, with the owner's `isReorderable`. Made
        // each render, so a move reads this render's value (the object may
        // be made anew).
        const owner =
          ownerReorderable == null
            ? undefined
            : reorderableOptions(ownerReorderable);
        // Adapted, so the engine is the owner's: nothing here loads the
        // reorder, and the owner's `start` finds the list.
        const reorderable =
          owner == null || ownerReorderable == null
            ? undefined
            : adaptReorderable(ownerReorderable, {
                onReorder: move => {
                  if (state.isBusy) {
                    return;
                  }
                  if (isStaged) {
                    setDraftValue(current =>
                      moveValue(current, move.key, move.to),
                    );
                  } else {
                    owner.onReorder(move);
                  }
                },
                isReorderable: owner.isReorderable,
              });

        return (
          <div
            aria-busy={state.isBusy || undefined}
            {...stylex.props(styles.surface)}>
            {isStaged && (
              <ResetDraftAfterClose
                isOpen={state.isOpen}
                resetDraft={resetDraft}
              />
            )}
            <fieldset
              aria-disabled={isDisabled || undefined}
              {...stylex.props(
                styles.fieldset,
                state.isBusy && styles.fieldsetBusy,
              )}>
              <TransferList
                label={label}
                isLabelHidden
                options={options}
                isDisabled={isDisabled}
                value={transferListValue}
                onChange={nextValue => {
                  if (isDisabled) {
                    return;
                  }
                  // Now that busy no longer disables the fieldset, the controls
                  // stay live while a change is in flight; ignore transfers
                  // until it settles so one pending action cannot be stacked.
                  if (state.isBusy) {
                    return;
                  }
                  if (isStaged) {
                    setDraftValue(nextValue);
                  } else {
                    commit([...nextValue]);
                  }
                }}
                selectedLabel={selectedLabel}
                availableLabel={availableLabel}
                hasSearch={hasSearch}
                searchLabel={searchLabel}
                searchPlaceholder={searchPlaceholder}
                reorderable={reorderable}
                hasSelectAll={hasSelectAll}
                hasClear={hasClear}
                renderOption={renderOption}
                selectedEmptyText={selectedEmptyText}
                availableEmptyText={availableEmptyText}
                noResultsText={noResultsText}
              />
            </fieldset>
            {isStaged && (
              <HStack gap={2} hAlign="end" padding={3} xstyle={styles.footer}>
                <Button
                  label={cancelLabel}
                  variant="ghost"
                  size="sm"
                  onClick={() => {
                    resetDraft();
                    close();
                  }}
                />
                <Button
                  label={applyLabel}
                  variant="primary"
                  size="sm"
                  isDisabled={isDisabled || state.isBusy}
                  isLoading={state.isBusy}
                  onClick={() => {
                    if (!areOrderedValuesEqual(draftValue, value)) {
                      commit([...draftValue]);
                    }
                    close();
                  }}
                />
              </HStack>
            )}
          </div>
        );
      }}
    </ComplexSelector>
  );
}

TransferListSelector.displayName = 'TransferListSelector';