fss-link 1.0.40 → 1.0.45

package/dist/ui/components/shared/RadioButtonSelect.test.tsx

@@ -0,0 +1,181 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { renderWithProviders } from '../../../test-utils/render.js';
+import { waitFor } from '@testing-library/react';
+import {
+  RadioButtonSelect,
+  type RadioSelectItem,
+} from './RadioButtonSelect.js';
+import { describe, it, expect, vi } from 'vitest';
+
+const ITEMS: Array<RadioSelectItem<string>> = [
+  { label: 'Option 1', value: 'one' },
+  { label: 'Option 2', value: 'two' },
+  { label: 'Option 3', value: 'three', disabled: true },
+];
+
+describe('<RadioButtonSelect />', () => {
+  it('renders a list of items and matches snapshot', () => {
+    const { lastFrame } = renderWithProviders(
+      <RadioButtonSelect items={ITEMS} onSelect={() => {}} isFocused={true} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders with the second item selected and matches snapshot', () => {
+    const { lastFrame } = renderWithProviders(
+      <RadioButtonSelect items={ITEMS} initialIndex={1} onSelect={() => {}} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders with numbers hidden and matches snapshot', () => {
+    const { lastFrame } = renderWithProviders(
+      <RadioButtonSelect
+        items={ITEMS}
+        onSelect={() => {}}
+        showNumbers={false}
+      />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders with scroll arrows and matches snapshot', () => {
+    const manyItems = Array.from({ length: 20 }, (_, i) => ({
+      label: `Item ${i + 1}`,
+      value: `item-${i + 1}`,
+    }));
+    const { lastFrame } = renderWithProviders(
+      <RadioButtonSelect
+        items={manyItems}
+        onSelect={() => {}}
+        showScrollArrows={true}
+        maxItemsToShow={5}
+      />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders with special theme display and matches snapshot', () => {
+    const themeItems: Array<RadioSelectItem<string>> = [
+      {
+        label: 'Theme A (Light)',
+        value: 'a-light',
+        themeNameDisplay: 'Theme A',
+        themeTypeDisplay: '(Light)',
+      },
+      {
+        label: 'Theme B (Dark)',
+        value: 'b-dark',
+        themeNameDisplay: 'Theme B',
+        themeTypeDisplay: '(Dark)',
+      },
+    ];
+    const { lastFrame } = renderWithProviders(
+      <RadioButtonSelect items={themeItems} onSelect={() => {}} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders a list with >10 items and matches snapshot', () => {
+    const manyItems = Array.from({ length: 12 }, (_, i) => ({
+      label: `Item ${i + 1}`,
+      value: `item-${i + 1}`,
+    }));
+    const { lastFrame } = renderWithProviders(
+      <RadioButtonSelect items={manyItems} onSelect={() => {}} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders nothing when no items are provided', () => {
+    const { lastFrame } = renderWithProviders(
+      <RadioButtonSelect items={[]} onSelect={() => {}} isFocused={true} />,
+    );
+    expect(lastFrame()).toBe('');
+  });
+});
+
+describe('keyboard navigation', () => {
+  it('should call onSelect when "enter" is pressed', () => {
+    const onSelect = vi.fn();
+    const { stdin } = renderWithProviders(
+      <RadioButtonSelect items={ITEMS} onSelect={onSelect} />,
+    );
+
+    stdin.write('\r');
+
+    expect(onSelect).toHaveBeenCalledWith('one');
+  });
+
+  describe('when isFocused is false', () => {
+    it('should not handle any keyboard input', () => {
+      const onSelect = vi.fn();
+      const { stdin } = renderWithProviders(
+        <RadioButtonSelect
+          items={ITEMS}
+          onSelect={onSelect}
+          isFocused={false}
+        />,
+      );
+
+      stdin.write('\u001B[B'); // Down arrow
+      stdin.write('\u001B[A'); // Up arrow
+      stdin.write('\r'); // Enter
+
+      expect(onSelect).not.toHaveBeenCalled();
+    });
+  });
+
+  describe.each([
+    { description: 'when isFocused is true', isFocused: true },
+    { description: 'when isFocused is omitted', isFocused: undefined },
+  ])('$description', ({ isFocused }) => {
+    it('should navigate down with arrow key and select with enter', async () => {
+      const onSelect = vi.fn();
+      const { stdin, lastFrame } = renderWithProviders(
+        <RadioButtonSelect
+          items={ITEMS}
+          onSelect={onSelect}
+          isFocused={isFocused}
+        />,
+      );
+
+      stdin.write('\u001B[B'); // Down arrow
+
+      await waitFor(() => {
+        expect(lastFrame()).toContain('● 2. Option 2');
+      });
+
+      stdin.write('\r');
+
+      expect(onSelect).toHaveBeenCalledWith('two');
+    });
+
+    it('should navigate up with arrow key and select with enter', async () => {
+      const onSelect = vi.fn();
+      const { stdin, lastFrame } = renderWithProviders(
+        <RadioButtonSelect
+          items={ITEMS}
+          onSelect={onSelect}
+          initialIndex={1}
+          isFocused={isFocused}
+        />,
+      );
+
+      stdin.write('\u001B[A'); // Up arrow
+
+      await waitFor(() => {
+        expect(lastFrame()).toContain('● 1. Option 1');
+      });
+
+      stdin.write('\r');
+
+      expect(onSelect).toHaveBeenCalledWith('one');
+    });
+  });
+});

package/dist/ui/components/shared/RadioButtonSelect.tsx

@@ -0,0 +1,234 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React, { useEffect, useState, useRef } from 'react';
+import { Text, Box } from 'ink';
+import { Colors } from '../../colors.js';
+import { useKeypress } from '../../hooks/useKeypress.js';
+
+/**
+ * Represents a single option for the RadioButtonSelect.
+ * Requires a label for display and a value to be returned on selection.
+ */
+export interface RadioSelectItem<T> {
+  label: string;
+  value: T;
+  disabled?: boolean;
+  themeNameDisplay?: string;
+  themeTypeDisplay?: string;
+}
+
+/**
+ * Props for the RadioButtonSelect component.
+ * @template T The type of the value associated with each radio item.
+ */
+export interface RadioButtonSelectProps<T> {
+  /** An array of items to display as radio options. */
+  items: Array<RadioSelectItem<T>>;
+  /** The initial index selected */
+  initialIndex?: number;
+  /** Function called when an item is selected. Receives the `value` of the selected item. */
+  onSelect: (value: T) => void;
+  /** Function called when an item is highlighted. Receives the `value` of the selected item. */
+  onHighlight?: (value: T) => void;
+  /** Whether this select input is currently focused and should respond to input. */
+  isFocused?: boolean;
+  /** Whether to show the scroll arrows. */
+  showScrollArrows?: boolean;
+  /** The maximum number of items to show at once. */
+  maxItemsToShow?: number;
+  /** Whether to show numbers next to items. */
+  showNumbers?: boolean;
+}
+
+/**
+ * A custom component that displays a list of items with radio buttons,
+ * supporting scrolling and keyboard navigation.
+ *
+ * @template T The type of the value associated with each radio item.
+ */
+export function RadioButtonSelect<T>({
+  items,
+  initialIndex = 0,
+  onSelect,
+  onHighlight,
+  isFocused = true,
+  showScrollArrows = false,
+  maxItemsToShow = 10,
+  showNumbers = true,
+}: RadioButtonSelectProps<T>): React.JSX.Element {
+  const [activeIndex, setActiveIndex] = useState(initialIndex);
+  const [scrollOffset, setScrollOffset] = useState(0);
+  const [numberInput, setNumberInput] = useState('');
+  const numberInputTimer = useRef<NodeJS.Timeout | null>(null);
+
+  useEffect(() => {
+    const newScrollOffset = Math.max(
+      0,
+      Math.min(activeIndex - maxItemsToShow + 1, items.length - maxItemsToShow),
+    );
+    if (activeIndex < scrollOffset) {
+      setScrollOffset(activeIndex);
+    } else if (activeIndex >= scrollOffset + maxItemsToShow) {
+      setScrollOffset(newScrollOffset);
+    }
+  }, [activeIndex, items.length, scrollOffset, maxItemsToShow]);
+
+  useEffect(
+    () => () => {
+      if (numberInputTimer.current) {
+        clearTimeout(numberInputTimer.current);
+      }
+    },
+    [],
+  );
+
+  useKeypress(
+    (key) => {
+      const { sequence, name } = key;
+      const isNumeric = showNumbers && /^[0-9]$/.test(sequence);
+
+      // Any key press that is not a digit should clear the number input buffer.
+      if (!isNumeric && numberInputTimer.current) {
+        clearTimeout(numberInputTimer.current);
+        setNumberInput('');
+      }
+
+      if (name === 'k' || name === 'up') {
+        const newIndex = activeIndex > 0 ? activeIndex - 1 : items.length - 1;
+        setActiveIndex(newIndex);
+        onHighlight?.(items[newIndex]!.value);
+        return;
+      }
+
+      if (name === 'j' || name === 'down') {
+        const newIndex = activeIndex < items.length - 1 ? activeIndex + 1 : 0;
+        setActiveIndex(newIndex);
+        onHighlight?.(items[newIndex]!.value);
+        return;
+      }
+
+      if (name === 'return') {
+        onSelect(items[activeIndex]!.value);
+        return;
+      }
+
+      // Handle numeric input for selection.
+      if (isNumeric) {
+        if (numberInputTimer.current) {
+          clearTimeout(numberInputTimer.current);
+        }
+
+        const newNumberInput = numberInput + sequence;
+        setNumberInput(newNumberInput);
+
+        const targetIndex = Number.parseInt(newNumberInput, 10) - 1;
+
+        // A single '0' is not a valid selection since items are 1-indexed.
+        if (newNumberInput === '0') {
+          numberInputTimer.current = setTimeout(() => setNumberInput(''), 350);
+          return;
+        }
+
+        if (targetIndex >= 0 && targetIndex < items.length) {
+          const targetItem = items[targetIndex]!;
+          setActiveIndex(targetIndex);
+          onHighlight?.(targetItem.value);
+
+          // If the typed number can't be a prefix for another valid number,
+          // select it immediately. Otherwise, wait for more input.
+          const potentialNextNumber = Number.parseInt(newNumberInput + '0', 10);
+          if (potentialNextNumber > items.length) {
+            onSelect(targetItem.value);
+            setNumberInput('');
+          } else {
+            numberInputTimer.current = setTimeout(() => {
+              onSelect(targetItem.value);
+              setNumberInput('');
+            }, 350); // Debounce time for multi-digit input.
+          }
+        } else {
+          // The typed number is out of bounds, clear the buffer
+          setNumberInput('');
+        }
+      }
+    },
+    { isActive: !!(isFocused && items.length > 0) },
+  );
+
+  const visibleItems = items.slice(scrollOffset, scrollOffset + maxItemsToShow);
+
+  return (
+    <Box flexDirection="column">
+      {showScrollArrows && (
+        <Text color={scrollOffset > 0 ? Colors.Foreground : Colors.Gray}>
+          ▲
+        </Text>
+      )}
+      {visibleItems.map((item, index) => {
+        const itemIndex = scrollOffset + index;
+        const isSelected = activeIndex === itemIndex;
+
+        let textColor = Colors.Foreground;
+        let numberColor = Colors.Foreground;
+        if (isSelected) {
+          textColor = Colors.AccentGreen;
+          numberColor = Colors.AccentGreen;
+        } else if (item.disabled) {
+          textColor = Colors.Gray;
+          numberColor = Colors.Gray;
+        }
+
+        if (!showNumbers) {
+          numberColor = Colors.Gray;
+        }
+
+        const numberColumnWidth = String(items.length).length;
+        const itemNumberText = `${String(itemIndex + 1).padStart(
+          numberColumnWidth,
+        )}.`;
+
+        return (
+          <Box key={item.label} alignItems="center">
+            <Box minWidth={2} flexShrink={0}>
+              <Text color={isSelected ? Colors.AccentGreen : Colors.Foreground}>
+                {isSelected ? '●' : ' '}
+              </Text>
+            </Box>
+            <Box
+              marginRight={1}
+              flexShrink={0}
+              minWidth={itemNumberText.length}
+            >
+              <Text color={numberColor}>{itemNumberText}</Text>
+            </Box>
+            {item.themeNameDisplay && item.themeTypeDisplay ? (
+              <Text color={textColor} wrap="truncate">
+                {item.themeNameDisplay}{' '}
+                <Text color={Colors.Gray}>{item.themeTypeDisplay}</Text>
+              </Text>
+            ) : (
+              <Text color={textColor} wrap="truncate">
+                {item.label}
+              </Text>
+            )}
+          </Box>
+        );
+      })}
+      {showScrollArrows && (
+        <Text
+          color={
+            scrollOffset + maxItemsToShow < items.length
+              ? Colors.Foreground
+              : Colors.Gray
+          }
+        >
+          ▼
+        </Text>
+      )}
+    </Box>
+  );
+}

package/dist/ui/components/shared/__snapshots__/RadioButtonSelect.test.tsx.snap

@@ -0,0 +1,47 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`<RadioButtonSelect /> > renders a list of items and matches snapshot 1`] = `
+"● 1. Option 1
+  2. Option 2
+  3. Option 3"
+`;
+
+exports[`<RadioButtonSelect /> > renders a list with >10 items and matches snapshot 1`] = `
+"●  1. Item 1
+   2. Item 2
+   3. Item 3
+   4. Item 4
+   5. Item 5
+   6. Item 6
+   7. Item 7
+   8. Item 8
+   9. Item 9
+  10. Item 10"
+`;
+
+exports[`<RadioButtonSelect /> > renders with numbers hidden and matches snapshot 1`] = `
+"● 1. Option 1
+  2. Option 2
+  3. Option 3"
+`;
+
+exports[`<RadioButtonSelect /> > renders with scroll arrows and matches snapshot 1`] = `
+"▲
+●  1. Item 1
+   2. Item 2
+   3. Item 3
+   4. Item 4
+   5. Item 5
+▼"
+`;
+
+exports[`<RadioButtonSelect /> > renders with special theme display and matches snapshot 1`] = `
+"● 1. Theme A (Light)
+  2. Theme B (Dark)"
+`;
+
+exports[`<RadioButtonSelect /> > renders with the second item selected and matches snapshot 1`] = `
+"  1. Option 1
+● 2. Option 2
+  3. Option 3"
+`;