@keboola/design 1.0.0

package/src/blocks/PasswordInput/PasswordInput.test.tsx

@@ -0,0 +1,219 @@
+import type { ReactElement } from 'react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { PasswordInput } from './PasswordInput';
+
+const renderInput = (ui: ReactElement) => render(ui);
+
+const getInput = () => screen.getByPlaceholderText('Password') as HTMLInputElement;
+const queryClearButton = () => screen.queryByLabelText('Clear password');
+const queryShowButton = () => screen.queryByLabelText('Show password');
+const queryHideButton = () => screen.queryByLabelText('Hide password');
+const queryCapsLockIcon = () => screen.queryByTitle('Caps Lock is on');
+
+describe('<PasswordInput />', () => {
+  describe('controlled state', () => {
+    it('renders empty when value is null', () => {
+      renderInput(<PasswordInput placeholder="Password" value={null} />);
+      expect(getInput().value).toBe('');
+    });
+
+    it('renders empty when value is undefined and no defaultValue', () => {
+      renderInput(<PasswordInput placeholder="Password" />);
+      expect(getInput().value).toBe('');
+    });
+
+    it('renders the controlled value', () => {
+      renderInput(<PasswordInput placeholder="Password" value="hunter2" onValueChange={vi.fn()} />);
+      expect(getInput().value).toBe('hunter2');
+    });
+
+    it('emits raw onValueChange on every keystroke', () => {
+      const onValueChange = vi.fn();
+      renderInput(<PasswordInput placeholder="Password" value="" onValueChange={onValueChange} />);
+      fireEvent.change(getInput(), { target: { value: 'abc' } });
+      expect(onValueChange).toHaveBeenCalledWith('abc');
+    });
+
+    it('emits the value verbatim via onValueBlur (no trimming)', () => {
+      const onValueBlur = vi.fn();
+      renderInput(
+        <PasswordInput placeholder="Password" value="  spaces  " onValueBlur={onValueBlur} />,
+      );
+      fireEvent.blur(getInput());
+      expect(onValueBlur).toHaveBeenCalledWith('  spaces  ');
+    });
+  });
+
+  describe('uncontrolled state', () => {
+    it('seeds the input from defaultValue', () => {
+      renderInput(<PasswordInput placeholder="Password" defaultValue="seed" />);
+      expect(getInput().value).toBe('seed');
+    });
+
+    it('treats null defaultValue as empty', () => {
+      renderInput(<PasswordInput placeholder="Password" defaultValue={null} />);
+      expect(getInput().value).toBe('');
+    });
+
+    it('keeps raw text in the DOM while typing', () => {
+      const onValueChange = vi.fn();
+      renderInput(<PasswordInput placeholder="Password" onValueChange={onValueChange} />);
+      const input = getInput();
+      fireEvent.change(input, { target: { value: 'p4ss' } });
+      expect(input.value).toBe('p4ss');
+      expect(onValueChange).toHaveBeenLastCalledWith('p4ss');
+    });
+  });
+
+  describe('clear button', () => {
+    it('is hidden when allowClear is false', () => {
+      renderInput(<PasswordInput placeholder="Password" defaultValue="abc" />);
+      expect(queryClearButton()).toBeNull();
+    });
+
+    it('is hidden when there is no value', () => {
+      renderInput(<PasswordInput placeholder="Password" allowClear />);
+      expect(queryClearButton()).toBeNull();
+    });
+
+    it('is hidden when disabled', () => {
+      renderInput(<PasswordInput placeholder="Password" allowClear disabled defaultValue="abc" />);
+      expect(queryClearButton()).toBeNull();
+    });
+
+    it('is hidden when readOnly', () => {
+      renderInput(<PasswordInput placeholder="Password" allowClear readOnly defaultValue="abc" />);
+      expect(queryClearButton()).toBeNull();
+    });
+
+    it('clears the DOM input in uncontrolled mode and emits onValueChange("")', () => {
+      const onValueChange = vi.fn();
+      renderInput(
+        <PasswordInput
+          placeholder="Password"
+          allowClear
+          defaultValue="abc"
+          onValueChange={onValueChange}
+        />,
+      );
+      fireEvent.click(queryClearButton()!);
+      expect(getInput().value).toBe('');
+      expect(onValueChange).toHaveBeenCalledWith('');
+    });
+
+    it('emits onValueChange("") in controlled mode', () => {
+      const onValueChange = vi.fn();
+      renderInput(
+        <PasswordInput
+          placeholder="Password"
+          allowClear
+          value="abc"
+          onValueChange={onValueChange}
+        />,
+      );
+      fireEvent.click(queryClearButton()!);
+      expect(onValueChange).toHaveBeenCalledWith('');
+    });
+
+    it('synthesizes an onChange event when clearing', () => {
+      const onChange = vi.fn();
+      renderInput(
+        <PasswordInput placeholder="Password" allowClear defaultValue="abc" onChange={onChange} />,
+      );
+      fireEvent.click(queryClearButton()!);
+      expect(onChange).toHaveBeenCalled();
+      expect(onChange.mock.lastCall?.[0].target.value).toBe('');
+    });
+  });
+
+  describe('password visibility toggle', () => {
+    it('does not render the toggle when allowPasswordToggle is false', () => {
+      renderInput(<PasswordInput placeholder="Password" />);
+      expect(queryShowButton()).toBeNull();
+      expect(queryHideButton()).toBeNull();
+    });
+
+    it('starts hidden by default and toggles to visible', () => {
+      renderInput(<PasswordInput placeholder="Password" allowPasswordToggle />);
+      const input = getInput();
+      expect(input.type).toBe('password');
+      fireEvent.click(queryShowButton()!);
+      expect(input.type).toBe('text');
+      fireEvent.click(queryHideButton()!);
+      expect(input.type).toBe('password');
+    });
+
+    it('honors defaultPasswordVisibility', () => {
+      renderInput(
+        <PasswordInput placeholder="Password" allowPasswordToggle defaultPasswordVisibility />,
+      );
+      expect(getInput().type).toBe('text');
+      expect(queryHideButton()).not.toBeNull();
+    });
+  });
+
+  describe('Caps Lock indicator', () => {
+    // jsdom's getModifierState always returns false; mock it on both KeyboardEvent
+    // and MouseEvent (separate prototype methods). Call again to flip state.
+    const mockCapsLock = (on: boolean) => {
+      const impl = (key: string) => key === 'CapsLock' && on;
+      vi.spyOn(KeyboardEvent.prototype, 'getModifierState').mockImplementation(impl);
+      vi.spyOn(MouseEvent.prototype, 'getModifierState').mockImplementation(impl);
+    };
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('is not rendered by default', () => {
+      renderInput(<PasswordInput placeholder="Password" />);
+      expect(queryCapsLockIcon()).toBeNull();
+    });
+
+    it('does not appear when Caps Lock is off and a key is pressed', () => {
+      mockCapsLock(false);
+      renderInput(<PasswordInput placeholder="Password" />);
+      fireEvent.keyDown(getInput(), { key: 'a' });
+      expect(queryCapsLockIcon()).toBeNull();
+    });
+
+    it('appears when Caps Lock is on and a key is pressed', () => {
+      mockCapsLock(true);
+      renderInput(<PasswordInput placeholder="Password" />);
+      fireEvent.keyDown(getInput(), { key: 'A' });
+      expect(queryCapsLockIcon()).not.toBeNull();
+    });
+
+    it('disappears immediately when Caps Lock is toggled off via keyUp', () => {
+      mockCapsLock(true);
+      renderInput(<PasswordInput placeholder="Password" />);
+      const input = getInput();
+      fireEvent.keyDown(input, { key: 'A' });
+      expect(queryCapsLockIcon()).not.toBeNull();
+
+      // User presses Caps Lock to turn it off — getModifierState now returns false on keyUp.
+      mockCapsLock(false);
+      fireEvent.keyUp(input, { key: 'CapsLock' });
+      expect(queryCapsLockIcon()).toBeNull();
+    });
+
+    it('appears on mouseDown when clicking into the field with Caps Lock on', () => {
+      mockCapsLock(true);
+      renderInput(<PasswordInput placeholder="Password" />);
+      fireEvent.mouseDown(getInput());
+      expect(queryCapsLockIcon()).not.toBeNull();
+    });
+
+    it('disappears on blur', () => {
+      mockCapsLock(true);
+      renderInput(<PasswordInput placeholder="Password" />);
+      const input = getInput();
+      fireEvent.keyDown(input, { key: 'A' });
+      expect(queryCapsLockIcon()).not.toBeNull();
+      fireEvent.blur(input);
+      expect(queryCapsLockIcon()).toBeNull();
+    });
+  });
+});

package/src/blocks/PasswordInput/PasswordInput.tsx

@@ -0,0 +1,180 @@
+import { useRef, useState } from 'react';
+import type {
+  ChangeEventHandler,
+  ComponentProps,
+  ElementRef,
+  FocusEventHandler,
+  KeyboardEventHandler,
+  MouseEventHandler,
+  Ref,
+} from 'react';
+
+import { Icon } from '../../components/Icon';
+import { InputGroup } from '../../components/InputGroup';
+import { createChangeInputEvent, mergeRefs } from '../../utils';
+
+type InputGroupProps = Pick<
+  ComponentProps<typeof InputGroup>,
+  'variant' | 'focusVariant' | 'state' | 'sizing'
+>;
+
+type InputGroupInputProps = Omit<
+  ComponentProps<typeof InputGroup.Input>,
+  'value' | 'defaultValue' | 'type' | 'autoComplete'
+>;
+
+type Props = InputGroupProps &
+  InputGroupInputProps & {
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (value: string) => void;
+    onValueBlur?: (value: string) => void;
+    allowClear?: boolean;
+    allowPasswordToggle?: boolean;
+    autoComplete?: 'new-password' | 'current-password' | 'off';
+    defaultPasswordVisibility?: boolean;
+  };
+
+export const PasswordInput = ({
+  ref,
+
+  // group props
+  state,
+  variant,
+  focusVariant,
+  sizing,
+  className,
+
+  // own props
+  value: valueProp,
+  defaultValue,
+  onValueChange,
+  onValueBlur,
+  onChange,
+  onBlur,
+  onKeyDown,
+  onKeyUp,
+  onMouseDown,
+  allowClear = false,
+  allowPasswordToggle = false,
+  autoComplete = 'new-password',
+  defaultPasswordVisibility = false,
+
+  // input props
+  disabled,
+  readOnly,
+  ...restInputProps
+}: Props & { ref?: Ref<ElementRef<'input'>> }) => {
+  const inputRef = useRef<ElementRef<'input'>>(null);
+
+  const [internalValue, setInternalValue] = useState(defaultValue ?? '');
+  const isControlled = valueProp !== undefined;
+  const value = isControlled ? (valueProp ?? '') : internalValue;
+  const setValue = (next: string) => {
+    if (!isControlled) setInternalValue(next);
+    onValueChange?.(next);
+  };
+
+  const [capsLock, setCapsLock] = useState(false);
+  const [isPasswordVisible, setIsPasswordVisible] = useState(defaultPasswordVisibility);
+
+  const canClear = allowClear && !!value && !disabled && !readOnly;
+
+  const handleChange: ChangeEventHandler<HTMLInputElement> = (event) => {
+    setValue(event.target.value);
+    onChange?.(event);
+  };
+
+  const handleBlur: FocusEventHandler<HTMLInputElement> = (event) => {
+    if (capsLock) setCapsLock(false);
+    onValueBlur?.(event.target.value);
+    onBlur?.(event);
+  };
+
+  // Both keyDown and keyUp are needed: pressing the Caps Lock key itself
+  // reports the *old* state on keyDown and the *new* state on keyUp, so
+  // toggling Caps Lock off mid-typing is only caught on keyUp.
+  const handleKeyDown: KeyboardEventHandler<HTMLInputElement> = (event) => {
+    const isOn = event.getModifierState('CapsLock');
+    if (isOn !== capsLock) setCapsLock(isOn);
+    onKeyDown?.(event);
+  };
+
+  const handleKeyUp: KeyboardEventHandler<HTMLInputElement> = (event) => {
+    const isOn = event.getModifierState('CapsLock');
+    if (isOn !== capsLock) setCapsLock(isOn);
+    onKeyUp?.(event);
+  };
+
+  // Catches the case where the user clicks into the field with Caps Lock
+  // already on. Tab-focus / autofocus have no API to query modifier state.
+  const handleMouseDown: MouseEventHandler<HTMLInputElement> = (event) => {
+    const isOn = event.getModifierState('CapsLock');
+    if (isOn !== capsLock) setCapsLock(isOn);
+    onMouseDown?.(event);
+  };
+
+  const handleClear: MouseEventHandler<HTMLButtonElement> = () => {
+    if (!inputRef.current) return;
+    inputRef.current.value = '';
+    setValue('');
+    onChange?.(createChangeInputEvent(inputRef.current));
+  };
+
+  const handleTogglePasswordVisibility = () => {
+    setIsPasswordVisible((prev) => !prev);
+  };
+
+  return (
+    <InputGroup
+      state={state}
+      variant={variant}
+      sizing={sizing}
+      focusVariant={focusVariant}
+      className={className}
+    >
+      <InputGroup.Input
+        {...restInputProps}
+        ref={mergeRefs(ref ?? null, inputRef)}
+        type={isPasswordVisible ? 'text' : 'password'}
+        autoComplete={autoComplete}
+        value={value}
+        onChange={handleChange}
+        onBlur={handleBlur}
+        onKeyDown={handleKeyDown}
+        onKeyUp={handleKeyUp}
+        onMouseDown={handleMouseDown}
+        disabled={disabled}
+        readOnly={readOnly}
+      />
+
+      {(capsLock || canClear || allowPasswordToggle) && (
+        <InputGroup.Addon align="inline-end">
+          {capsLock && (
+            <Icon
+              icon="up-from-line"
+              title="Caps Lock is on"
+              className="tw-size-4 tw-text-primary"
+            />
+          )}
+          {canClear && (
+            <InputGroup.Button
+              icon="xmark"
+              aria-label="Clear password"
+              onMouseDown={(event) => event.preventDefault()}
+              onClick={handleClear}
+            />
+          )}
+          {allowPasswordToggle && (
+            <InputGroup.Button
+              icon={isPasswordVisible ? 'eye-slash' : 'eye'}
+              aria-label={isPasswordVisible ? 'Hide password' : 'Show password'}
+              onMouseDown={(event) => event.preventDefault()}
+              onClick={handleTogglePasswordVisibility}
+            />
+          )}
+        </InputGroup.Addon>
+      )}
+    </InputGroup>
+  );
+};

package/src/blocks/PasswordInput/index.ts

@@ -0,0 +1 @@
+export * from './PasswordInput';

package/src/blocks/SearchInput/SearchInput.stories.tsx

@@ -0,0 +1,127 @@
+import { useState } from 'react';
+import type { ComponentProps } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { action } from 'storybook/actions';
+
+import { SearchInput } from './SearchInput';
+
+type Story = StoryObj<typeof SearchInput>;
+type SearchInputProps = ComponentProps<typeof SearchInput>;
+type State = NonNullable<SearchInputProps['state']>;
+type Variant = NonNullable<SearchInputProps['variant']>;
+type Sizing = NonNullable<SearchInputProps['sizing']>;
+type FocusVariant = NonNullable<SearchInputProps['focusVariant']>;
+
+const states: State[] = ['default', 'error', 'warning'];
+const variants: Variant[] = ['primary', 'secondary', 'argo'];
+const sizings: Sizing[] = ['small', 'default', 'medium'];
+const focusVariants: FocusVariant[] = ['default', 'on', 'off'];
+
+/**
+ * A debounced search input built on `InputGroup`.
+ *
+ * ### Key features
+ *
+ * **Debounced `onValueChange`** — by default the callback fires 300 ms after
+ * the user stops typing, preventing excessive re-renders or network requests
+ * on every keystroke. Tune via `debounceDelay` or disable entirely with
+ * `disableDebounce`.
+ *
+ * **Search icon prefix** — a magnifying-glass icon is always rendered as the
+ * inline-start prefix. It is part of the component and cannot be removed;
+ * that is by design — if you need a generic text input without the icon, use
+ * `TextInput` instead.
+ *
+ * **Optional clear button** — pass `allowClear` to show an ✕ button whenever
+ * the field has a value. Clicking it fires `onValueChange('')` immediately
+ * (not debounced) and calls the optional `onClear` callback.
+ *
+ * ### Controlled vs uncontrolled
+ *
+ * Works in both modes. In controlled mode the internal display value updates
+ * on every keystroke while the debounced `onValueChange` fires after the
+ * delay, so the input never feels laggy even when the parent re-renders only
+ * after the debounced call.
+ */
+export default {
+  component: SearchInput,
+  args: {
+    placeholder: 'Search',
+    variant: 'primary',
+    state: 'default',
+    sizing: 'default',
+    focusVariant: 'default',
+    allowClear: false,
+    disableDebounce: false,
+    debounceDelay: 300,
+    readOnly: false,
+    disabled: false,
+    onValueChange: action('onValueChange'),
+    onValueBlur: action('onValueBlur'),
+    onClear: action('onClear'),
+  },
+  argTypes: {
+    state: {
+      description: 'Validation state passed to the InputGroup wrapper.',
+      type: { name: 'enum', value: states },
+    },
+    variant: {
+      description: 'Visual variant of the InputGroup wrapper.',
+      type: { name: 'enum', value: variants },
+    },
+    sizing: {
+      description: 'Size of the InputGroup wrapper.',
+      type: { name: 'enum', value: sizings },
+    },
+    focusVariant: {
+      description: 'Focus ring style.',
+      type: { name: 'enum', value: focusVariants },
+    },
+    allowClear: {
+      description: 'Show a clear button when the field has a value.',
+    },
+    disableDebounce: {
+      description: 'Fire `onValueChange` on every keystroke instead of debouncing.',
+    },
+    debounceDelay: {
+      description: 'Debounce delay in milliseconds (ignored when `disableDebounce` is true).',
+    },
+  },
+} satisfies Meta<typeof SearchInput>;
+
+export const Basic: Story = {};
+
+export const WithClear: Story = {
+  args: {
+    defaultValue: 'hello world',
+    allowClear: true,
+  },
+};
+
+export const Argo: Story = {
+  args: {
+    variant: 'argo',
+    sizing: 'medium',
+    placeholder: 'Search workspaces',
+    allowClear: true,
+  },
+};
+
+const ControlledDemo = (props: SearchInputProps) => {
+  const [value, setValue] = useState('');
+  return (
+    <SearchInput
+      {...props}
+      value={value}
+      onValueChange={(next) => {
+        action('onValueChange')(next);
+        setValue(next);
+      }}
+    />
+  );
+};
+
+export const Controlled: Story = {
+  render: ControlledDemo,
+  args: { allowClear: true },
+};

package/src/blocks/SearchInput/SearchInput.test.tsx

@@ -0,0 +1,162 @@
+import type { ComponentProps } from 'react';
+import { act, render, screen } from '@testing-library/react';
+import { userEvent } from 'storybook/test';
+import { vi } from 'vitest';
+
+import { SearchInput } from './SearchInput';
+
+type Props = ComponentProps<typeof SearchInput>;
+
+const onValueChange = vi.fn();
+const onBlur = vi.fn();
+const onClear = vi.fn();
+
+const getInput = () => screen.getByRole<HTMLInputElement>('textbox');
+const getClearButton = () =>
+  screen.queryByRole<HTMLButtonElement>('button', { name: 'Clear search' });
+
+const Wrapped = (props: Partial<Props>) => (
+  <SearchInput onValueChange={onValueChange} onValueBlur={onBlur} {...props} />
+);
+
+describe('<SearchInput />', () => {
+  beforeEach(() => {
+    onValueChange.mockClear();
+    onBlur.mockClear();
+    onClear.mockClear();
+  });
+
+  it('renders with null value as empty string', () => {
+    render(<Wrapped value={null} />);
+    expect(getInput().value).toBe('');
+  });
+
+  it('renders with null defaultValue as empty string', () => {
+    render(<Wrapped defaultValue={null} />);
+    expect(getInput().value).toBe('');
+  });
+
+  it('works in uncontrolled mode', async () => {
+    render(<Wrapped disableDebounce defaultValue="hello" />);
+    const el = getInput();
+    expect(el.value).toBe('hello');
+
+    await act(async () => {
+      await userEvent.type(el, ' world');
+    });
+
+    expect(onValueChange).toHaveBeenCalledTimes(6);
+    expect(onValueChange).toHaveBeenLastCalledWith('hello world');
+    expect(el.value).toBe('hello world');
+  });
+
+  it('works in controlled mode without debounce', async () => {
+    const { rerender } = render(<Wrapped disableDebounce value="hello" />);
+    const el = getInput();
+    expect(el.value).toBe('hello');
+
+    rerender(<Wrapped disableDebounce value="new value" />);
+    expect(el.value).toBe('new value');
+
+    await act(async () => {
+      await userEvent.type(el, ' test');
+    });
+
+    expect(onValueChange).toHaveBeenLastCalledWith('new value test');
+    expect(el.value).toBe('new value test');
+
+    rerender(<Wrapped disableDebounce value="reset" />);
+    expect(el.value).toBe('reset');
+  });
+
+  describe('allowClear', () => {
+    it('does not render clear button when allowClear is false', () => {
+      render(<Wrapped defaultValue="hello" allowClear={false} />);
+      expect(getClearButton()).toBeNull();
+    });
+
+    it('renders clear button when allowClear is true and input has value', () => {
+      render(<Wrapped defaultValue="hello" allowClear />);
+      expect(getClearButton()).not.toBeNull();
+    });
+
+    it('does not render clear button when disabled', () => {
+      render(<Wrapped defaultValue="hello" allowClear disabled />);
+      expect(getClearButton()).toBeNull();
+    });
+
+    it('does not render clear button when readOnly', () => {
+      render(<Wrapped defaultValue="hello" allowClear readOnly />);
+      expect(getClearButton()).toBeNull();
+    });
+
+    it('clears value and calls onValueChange and onClear', async () => {
+      render(<Wrapped defaultValue="hello" allowClear onClear={onClear} />);
+      const clearBtn = getClearButton()!;
+
+      await act(async () => {
+        await userEvent.click(clearBtn);
+      });
+
+      expect(getInput().value).toBe('');
+      expect(onValueChange).toHaveBeenCalledWith('');
+      expect(onClear).toHaveBeenCalledTimes(1);
+      expect(getClearButton()).toBeNull();
+    });
+  });
+
+  describe('debounce', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+      onValueChange.mockClear();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+      vi.clearAllTimers();
+      vi.resetAllMocks();
+    });
+
+    it('debounces onValueChange by 300 ms', async () => {
+      const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime, delay: 10 });
+      render(<Wrapped debounceDelay={300} />);
+      const el = getInput();
+
+      await act(async () => {
+        await user.type(el, 'test');
+      });
+
+      expect(onValueChange).not.toHaveBeenCalled();
+
+      vi.advanceTimersByTime(300);
+      expect(onValueChange).toHaveBeenCalledTimes(1);
+      expect(onValueChange).toHaveBeenCalledWith('test');
+    });
+
+    it('cancels pending debounce when clear is clicked', async () => {
+      const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime, delay: 10 });
+      render(<Wrapped debounceDelay={300} defaultValue="hello" allowClear />);
+      const el = getInput();
+
+      // type — debounce starts
+      await act(async () => {
+        await user.type(el, ' world');
+      });
+
+      expect(onValueChange).not.toHaveBeenCalled();
+
+      // clear before debounce fires
+      await act(async () => {
+        await user.click(getClearButton()!);
+      });
+
+      // clear fires onValueChange('') immediately
+      expect(onValueChange).toHaveBeenCalledTimes(1);
+      expect(onValueChange).toHaveBeenCalledWith('');
+
+      // advancing timer must NOT fire the stale debounced call
+      vi.advanceTimersByTime(300);
+      expect(onValueChange).toHaveBeenCalledTimes(1);
+    });
+  });
+});