@keboola/design 1.0.0

package/src/blocks/ColorInput/ColorInput.stories.tsx

@@ -0,0 +1,109 @@
+import { useState } from 'react';
+import type { ComponentProps, FormEventHandler } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { action } from 'storybook/actions';
+
+import { Button } from '../../components/Button';
+
+import { ColorInput } from './ColorInput';
+
+type Story = StoryObj<typeof ColorInput>;
+type ColorInputProps = ComponentProps<typeof ColorInput>;
+type State = NonNullable<ColorInputProps['state']>;
+type Variant = NonNullable<ColorInputProps['variant']>;
+type Sizing = NonNullable<ColorInputProps['sizing']>;
+type FocusVariant = NonNullable<ColorInputProps['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'];
+
+/**
+ * Color input with a swatch indicator, hex text entry (RGB or RGBA), and an
+ * OS-native color picker. Works in both controlled and uncontrolled modes.
+ */
+export default {
+  component: ColorInput,
+  args: {
+    placeholder: 'Placeholder',
+    variant: 'primary',
+    state: 'default',
+    sizing: 'default',
+    focusVariant: 'default',
+    allowClear: false,
+    readOnly: false,
+    disabled: false,
+
+    onValueChange: action('onValueChange'),
+    onValueBlur: action('onValueBlur'),
+  },
+  argTypes: {
+    state: {
+      description: 'Set validation state',
+      type: { name: 'enum', value: states },
+    },
+
+    variant: {
+      defaultValue: 'primary',
+      description: 'Set Variant',
+      type: { name: 'enum', value: variants },
+    },
+
+    sizing: {
+      defaultValue: 'default',
+      description: 'Set Sizing',
+      type: { name: 'enum', value: sizings },
+    },
+
+    focusVariant: {
+      defaultValue: 'default',
+      description: 'Set Focus Variant',
+      type: { name: 'enum', value: focusVariants },
+    },
+  },
+} satisfies Meta<typeof ColorInput>;
+
+export const Basic: Story = {};
+
+const ControlledDemo = (props: ComponentProps<typeof ColorInput>) => {
+  const [value, setValue] = useState('');
+  const handleOnValueChange = (value: string) => {
+    action('onValueChange')(value);
+    setValue(value);
+  };
+
+  return <ColorInput {...props} value={value} onValueChange={handleOnValueChange} />;
+};
+
+export const Controlled: Story = {
+  render: ControlledDemo,
+};
+
+const UncontrolledDemo = (props: ComponentProps<typeof ColorInput>) => {
+  const handleSubmit: FormEventHandler<HTMLFormElement> = (event) => {
+    event.preventDefault();
+    const values = new FormData(event.currentTarget);
+    action('onSubmit')(Object.fromEntries(values.entries()));
+  };
+
+  return (
+    <form className="tw-flex tw-gap-2" onSubmit={handleSubmit}>
+      <ColorInput
+        {...props}
+        onValueChange={action('onValueChange')}
+        onValueBlur={action('onValueBlur')}
+      />
+      <Button type="submit">Submit</Button>
+    </form>
+  );
+};
+
+export const Uncontrolled: Story = {
+  render: UncontrolledDemo,
+  args: {
+    defaultValue: '#ff0000',
+    allowClear: true,
+    name: 'uncontrolled-color-input',
+  },
+};

package/src/blocks/ColorInput/ColorInput.test.tsx

@@ -0,0 +1,163 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ColorInput } from './ColorInput';
+
+const getTextInput = () => screen.getByPlaceholderText('color') as HTMLInputElement;
+const getColorPicker = () => document.querySelector<HTMLInputElement>('input[type="color"]')!;
+const queryClearButton = () => screen.queryByLabelText('Clear color');
+
+describe('<ColorInput />', () => {
+  describe('controlled state', () => {
+    it('renders empty when value is null', () => {
+      render(<ColorInput placeholder="color" value={null} />);
+      expect(getTextInput().value).toBe('');
+    });
+
+    it('renders empty when value is undefined and no defaultValue', () => {
+      render(<ColorInput placeholder="color" />);
+      expect(getTextInput().value).toBe('');
+    });
+
+    it('renders the controlled value', () => {
+      render(<ColorInput placeholder="color" value="#abcdef" onValueChange={vi.fn()} />);
+      expect(getTextInput().value).toBe('#abcdef');
+    });
+
+    it('emits raw onValueChange on every keystroke', () => {
+      const onValueChange = vi.fn();
+      render(<ColorInput placeholder="color" value="" onValueChange={onValueChange} />);
+      fireEvent.change(getTextInput(), { target: { value: 'aabbcc' } });
+      expect(onValueChange).toHaveBeenCalledWith('aabbcc');
+    });
+
+    it('emits sanitized value via onValueBlur on blur', () => {
+      const onValueChange = vi.fn();
+      const onValueBlur = vi.fn();
+      render(
+        <ColorInput
+          placeholder="color"
+          value="aabbcc"
+          onValueChange={onValueChange}
+          onValueBlur={onValueBlur}
+        />,
+      );
+      fireEvent.blur(getTextInput());
+      expect(onValueBlur).toHaveBeenCalledWith('#aabbcc');
+      expect(onValueChange).toHaveBeenCalledWith('#aabbcc');
+    });
+
+    it('snaps invalid input to its sanitized prefix on blur', () => {
+      const onValueBlur = vi.fn();
+      render(<ColorInput placeholder="color" value="aabbzz" onValueBlur={onValueBlur} />);
+      fireEvent.blur(getTextInput());
+      expect(onValueBlur).toHaveBeenCalledWith('#aabb');
+    });
+
+    it('clears the value on blur when no valid hex digits remain', () => {
+      const onValueBlur = vi.fn();
+      render(<ColorInput placeholder="color" value="gabc" onValueBlur={onValueBlur} />);
+      fireEvent.blur(getTextInput());
+      expect(onValueBlur).toHaveBeenCalledWith('');
+    });
+  });
+
+  describe('uncontrolled state', () => {
+    it('seeds the input from defaultValue', () => {
+      render(<ColorInput placeholder="color" defaultValue="#abc" />);
+      expect(getTextInput().value).toBe('#abc');
+    });
+
+    it('treats null defaultValue as empty', () => {
+      render(<ColorInput placeholder="color" defaultValue={null} />);
+      expect(getTextInput().value).toBe('');
+    });
+
+    it('keeps raw text in the DOM while typing', () => {
+      const onValueChange = vi.fn();
+      render(<ColorInput placeholder="color" onValueChange={onValueChange} />);
+      const input = getTextInput();
+      fireEvent.change(input, { target: { value: 'aabbcc' } });
+      expect(input.value).toBe('aabbcc');
+      expect(onValueChange).toHaveBeenLastCalledWith('aabbcc');
+    });
+
+    it('sanitizes the visible value on blur', () => {
+      render(<ColorInput placeholder="color" />);
+      const input = getTextInput();
+      fireEvent.change(input, { target: { value: 'aabbcc' } });
+      fireEvent.blur(input);
+      expect(input.value).toBe('#aabbcc');
+    });
+  });
+
+  describe('clear button', () => {
+    it('is hidden when there is no value', () => {
+      render(<ColorInput placeholder="color" allowClear />);
+      expect(queryClearButton()).toBeNull();
+    });
+
+    it('is hidden when disabled', () => {
+      render(<ColorInput placeholder="color" allowClear disabled defaultValue="#abc" />);
+      expect(queryClearButton()).toBeNull();
+    });
+
+    it('is hidden when readOnly', () => {
+      render(<ColorInput placeholder="color" allowClear readOnly defaultValue="#abc" />);
+      expect(queryClearButton()).toBeNull();
+    });
+
+    it('clears the DOM input in uncontrolled mode', () => {
+      const onValueChange = vi.fn();
+      render(
+        <ColorInput
+          placeholder="color"
+          allowClear
+          defaultValue="#abc"
+          onValueChange={onValueChange}
+        />,
+      );
+      const input = getTextInput();
+      expect(input.value).toBe('#abc');
+      fireEvent.click(queryClearButton()!);
+      expect(input.value).toBe('');
+      expect(onValueChange).toHaveBeenCalledWith('');
+    });
+
+    it('emits onValueChange("") in controlled mode without mutating the DOM directly', () => {
+      const onValueChange = vi.fn();
+      render(
+        <ColorInput placeholder="color" allowClear value="#abcdef" onValueChange={onValueChange} />,
+      );
+      fireEvent.click(queryClearButton()!);
+      expect(onValueChange).toHaveBeenCalledWith('');
+    });
+
+    it('synthesizes an onChange event when clearing', () => {
+      const onChange = vi.fn();
+      render(<ColorInput placeholder="color" allowClear defaultValue="#abc" onChange={onChange} />);
+      fireEvent.click(queryClearButton()!);
+      expect(onChange).toHaveBeenCalled();
+      expect(onChange.mock.lastCall?.[0].target.value).toBe('');
+    });
+  });
+
+  describe('color picker', () => {
+    it('applies the picked color to the text input in uncontrolled mode', () => {
+      const onValueChange = vi.fn();
+      render(<ColorInput placeholder="color" onValueChange={onValueChange} />);
+      const picker = getColorPicker();
+      fireEvent.change(picker, { target: { value: '#112233' } });
+      expect(getTextInput().value).toBe('#112233');
+      expect(onValueChange).toHaveBeenCalledWith('#112233');
+    });
+
+    it('emits onValueChange with the picked color in controlled mode', () => {
+      const onValueChange = vi.fn();
+      render(<ColorInput placeholder="color" value="#abcdef" onValueChange={onValueChange} />);
+      const picker = getColorPicker();
+      fireEvent.change(picker, { target: { value: '#112233' } });
+      expect(onValueChange).toHaveBeenCalledWith('#112233');
+    });
+  });
+});

package/src/blocks/ColorInput/ColorInput.tsx

@@ -0,0 +1,169 @@
+import { useRef, useState } from 'react';
+import type {
+  ChangeEventHandler,
+  ComponentProps,
+  ElementRef,
+  FocusEventHandler,
+  MouseEventHandler,
+  Ref,
+} from 'react';
+
+import { InputGroup } from '../../components/InputGroup';
+import { cn, createChangeInputEvent, mergeRefs } from '../../utils';
+
+import { ColorPicker } from './ColorPicker';
+import { coerceHexInputValue, isCompleteHexColor } from './utils';
+
+type InputGroupProps = Pick<
+  ComponentProps<typeof InputGroup>,
+  'variant' | 'focusVariant' | 'state' | 'sizing'
+>;
+
+type InputGroupInputProps = Omit<ComponentProps<typeof InputGroup.Input>, 'value' | 'defaultValue'>;
+
+type Props = InputGroupProps &
+  InputGroupInputProps & {
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (value: string) => void;
+    onValueBlur?: (value: string) => void;
+    allowClear?: boolean;
+  };
+
+export const ColorInput = ({
+  ref,
+
+  // group props
+  state,
+  variant,
+  focusVariant,
+  sizing,
+  className,
+
+  // own props
+  value: valueProp,
+  onValueChange,
+  onValueBlur,
+  onChange,
+  onBlur,
+  defaultValue,
+  allowClear = 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 = (nextValue: string) => {
+    if (!isControlled) setInternalValue(nextValue);
+    onValueChange?.(nextValue);
+  };
+
+  const canClear = allowClear && !!value && !disabled && !readOnly;
+  const swatchColor = coerceHexInputValue(value);
+  const isValidSwatch = isCompleteHexColor(swatchColor);
+
+  // Preserve raw text while the user is typing — sanitise on blur.
+  const handleChange: ChangeEventHandler<HTMLInputElement> = (event) => {
+    setValue(event.target.value);
+    onChange?.(event);
+  };
+
+  const handleBlur: FocusEventHandler<HTMLInputElement> = (event) => {
+    const newValue = event.target.value;
+    const sanitizedNewValue = coerceHexInputValue(newValue);
+
+    if (sanitizedNewValue !== newValue) {
+      // In controlled mode, let the parent decide whether to apply the
+      // sanitised value via `onValueChange` — don't fight its `value` prop.
+      if (!isControlled) event.target.value = sanitizedNewValue;
+      setValue(sanitizedNewValue);
+    }
+
+    onValueBlur?.(sanitizedNewValue);
+    onBlur?.(event);
+  };
+
+  const handlePickerChange: ChangeEventHandler<HTMLInputElement> = (event) => {
+    setValue(coerceHexInputValue(event.target.value));
+    onChange?.(event);
+  };
+
+  const handleClear: MouseEventHandler<HTMLButtonElement> = () => {
+    if (!inputRef.current) return;
+    inputRef.current.value = '';
+    setValue('');
+    onChange?.(createChangeInputEvent(inputRef.current));
+  };
+
+  return (
+    <InputGroup
+      state={state}
+      variant={variant}
+      sizing={sizing}
+      focusVariant={focusVariant}
+      className={className}
+    >
+      <InputGroup.Addon
+        align="inline-start"
+        className={cn(
+          { '-tw-ml-7 tw-opacity-0': !value },
+          'tw-transition-[opacity,margin]',
+          'tw-ease-linear',
+          'tw-duration-200',
+        )}
+      >
+        <div
+          style={isValidSwatch ? { background: swatchColor } : undefined}
+          className={cn(
+            'tw-size-5',
+            'tw-shrink-0',
+            'tw-rounded-sm',
+            'tw-border',
+            'tw-border-solid',
+            'tw-border-neutral-300',
+            {
+              'tw-bg-[linear-gradient(to_top_right,transparent_calc(50%_-_1px),theme(colors.red.300)_calc(50%_-_1px),theme(colors.red.300)_calc(50%_+_1px),transparent_calc(50%_+_1px))]':
+                !isValidSwatch,
+            },
+          )}
+        />
+      </InputGroup.Addon>
+
+      <InputGroup.Input
+        {...restInputProps}
+        type="text"
+        ref={mergeRefs(ref ?? null, inputRef)}
+        value={value}
+        onChange={handleChange}
+        onBlur={handleBlur}
+        disabled={disabled}
+        readOnly={readOnly}
+      />
+
+      <InputGroup.Addon align="inline-end">
+        {canClear && (
+          <InputGroup.Button
+            icon="xmark"
+            // prevents input focus stealing
+            onMouseDown={(event) => event.preventDefault()}
+            onClick={handleClear}
+            aria-label="Clear color"
+          />
+        )}
+        <ColorPicker
+          disabled={disabled}
+          readOnly={readOnly}
+          value={value}
+          onChange={handlePickerChange}
+        />
+      </InputGroup.Addon>
+    </InputGroup>
+  );
+};

package/src/blocks/ColorInput/ColorPicker.tsx

@@ -0,0 +1,39 @@
+import { type ComponentProps, type ElementRef, useRef } from 'react';
+
+import { InputGroup } from '../../components/InputGroup';
+
+import { coerceColorPickerValue, showPicker } from './utils';
+
+type Props = Omit<ComponentProps<'input'>, 'type'>;
+
+export const ColorPicker = ({ value, disabled, readOnly, ...props }: Props) => {
+  const pickerRef = useRef<ElementRef<'input'>>(null);
+
+  const handleOpenPicker = () => {
+    if (!pickerRef.current) return;
+    showPicker(pickerRef.current);
+  };
+
+  return (
+    <div className="tw-relative">
+      <input
+        {...props}
+        ref={pickerRef}
+        type="color"
+        value={coerceColorPickerValue(value)}
+        tabIndex={-1}
+        aria-hidden
+        className="tw-pointer-events-none tw-absolute tw-left-0 tw-top-full tw-size-0 tw-opacity-0"
+        disabled={disabled}
+        readOnly={readOnly}
+      />
+      <InputGroup.Button
+        onMouseDown={(event) => event.preventDefault()}
+        disabled={disabled || readOnly}
+        icon="eye-dropper"
+        onClick={handleOpenPicker}
+        aria-label="Pick color"
+      />
+    </div>
+  );
+};

package/src/blocks/ColorInput/index.ts

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

package/src/blocks/ColorInput/utils.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, it } from 'vitest';
+
+import { coerceColorPickerValue, coerceHexInputValue, isCompleteHexColor } from './utils';
+
+describe('coerceColorPickerValue', () => {
+  describe('valid hex inputs', () => {
+    it('expands 3-char hex with hash', () => {
+      expect(coerceColorPickerValue('#abc')).toBe('#aabbcc');
+    });
+
+    it('expands 3-char hex without hash', () => {
+      expect(coerceColorPickerValue('abc')).toBe('#aabbcc');
+    });
+
+    it('expands 4-char hex and drops the alpha channel', () => {
+      expect(coerceColorPickerValue('#abcd')).toBe('#aabbcc');
+    });
+
+    it('keeps 6-char hex with hash', () => {
+      expect(coerceColorPickerValue('#aabbcc')).toBe('#aabbcc');
+    });
+
+    it('keeps 6-char hex without hash', () => {
+      expect(coerceColorPickerValue('aabbcc')).toBe('#aabbcc');
+    });
+
+    it('drops alpha for 8-char hex', () => {
+      expect(coerceColorPickerValue('#aabbccdd')).toBe('#aabbcc');
+    });
+  });
+
+  describe('normalization', () => {
+    it('lowercases mixed-case hex', () => {
+      expect(coerceColorPickerValue('#AaBbCc')).toBe('#aabbcc');
+    });
+
+    it('lowercases uppercase hex', () => {
+      expect(coerceColorPickerValue('#ABCDEF')).toBe('#abcdef');
+    });
+
+    it('trims surrounding whitespace', () => {
+      expect(coerceColorPickerValue('  #abc  ')).toBe('#aabbcc');
+    });
+
+    it('trims whitespace around hex without hash', () => {
+      expect(coerceColorPickerValue('  aabbcc  ')).toBe('#aabbcc');
+    });
+  });
+
+  describe('invalid inputs fall back to #000000', () => {
+    it('rejects invalid hex characters', () => {
+      expect(coerceColorPickerValue('#xyz')).toBe('#000000');
+    });
+
+    it('rejects mixed valid/invalid characters', () => {
+      expect(coerceColorPickerValue('#aabbzz')).toBe('#000000');
+    });
+
+    it.each([
+      ['1-char', '#a'],
+      ['2-char', '#ab'],
+      ['5-char', '#abcde'],
+      ['7-char', '#abcdefa'],
+      ['9-char', '#abcdef000'],
+    ])('rejects %s hex', (_, input) => {
+      expect(coerceColorPickerValue(input)).toBe('#000000');
+    });
+
+    it('rejects empty string', () => {
+      expect(coerceColorPickerValue('')).toBe('#000000');
+    });
+
+    it('rejects whitespace-only string', () => {
+      expect(coerceColorPickerValue('   ')).toBe('#000000');
+    });
+
+    it('rejects bare hash', () => {
+      expect(coerceColorPickerValue('#')).toBe('#000000');
+    });
+  });
+
+  describe('non-string input types', () => {
+    it('handles null', () => {
+      expect(coerceColorPickerValue(null)).toBe('#000000');
+    });
+
+    it('handles undefined', () => {
+      expect(coerceColorPickerValue(undefined)).toBe('#000000');
+    });
+
+    it('handles number', () => {
+      expect(coerceColorPickerValue(0xaabbcc)).toBe('#000000');
+    });
+
+    it('handles readonly string array', () => {
+      expect(coerceColorPickerValue(['#aabbcc'])).toBe('#000000');
+    });
+  });
+});
+
+describe('coerceHexInputValue', () => {
+  it('returns empty string for null', () => {
+    expect(coerceHexInputValue(null)).toBe('');
+  });
+
+  it('returns empty string for undefined', () => {
+    expect(coerceHexInputValue(undefined)).toBe('');
+  });
+
+  it('returns empty string for empty input', () => {
+    expect(coerceHexInputValue('')).toBe('');
+  });
+
+  it('prepends # when missing', () => {
+    expect(coerceHexInputValue('aabbcc')).toBe('#aabbcc');
+  });
+
+  it('keeps valid 6-char hex with hash', () => {
+    expect(coerceHexInputValue('#aabbcc')).toBe('#aabbcc');
+  });
+
+  it('keeps valid 8-char hex (RGBA)', () => {
+    expect(coerceHexInputValue('#aabbccdd')).toBe('#aabbccdd');
+  });
+
+  it('truncates to 8 hex characters max', () => {
+    expect(coerceHexInputValue('#aabbccddee')).toBe('#aabbccdd');
+  });
+
+  it('strips invalid characters by keeping only the valid prefix', () => {
+    expect(coerceHexInputValue('#aabbzz')).toBe('#aabb');
+  });
+
+  it('returns empty string for bare hash', () => {
+    expect(coerceHexInputValue('#')).toBe('');
+  });
+
+  it('returns empty string when no valid hex digits remain', () => {
+    expect(coerceHexInputValue('zz')).toBe('');
+    expect(coerceHexInputValue('#zz')).toBe('');
+  });
+
+  it('trims surrounding whitespace', () => {
+    expect(coerceHexInputValue('  #abc  ')).toBe('#abc');
+  });
+
+  it('returns empty string for whitespace-only input', () => {
+    expect(coerceHexInputValue('   ')).toBe('');
+  });
+});
+
+describe('isCompleteHexColor', () => {
+  describe('accepts CSS-valid hex lengths', () => {
+    it.each([
+      ['3-digit', '#abc'],
+      ['4-digit (RGBA)', '#abcd'],
+      ['6-digit', '#aabbcc'],
+      ['8-digit (RGBA)', '#aabbccdd'],
+    ])('accepts %s hex', (_, input) => {
+      expect(isCompleteHexColor(input)).toBe(true);
+    });
+
+    it('accepts uppercase hex', () => {
+      expect(isCompleteHexColor('#ABCDEF')).toBe(true);
+    });
+  });
+
+  describe('rejects partial / invalid values', () => {
+    it.each([
+      ['empty', ''],
+      ['bare hash', '#'],
+      ['1-digit', '#a'],
+      ['2-digit', '#ab'],
+      ['5-digit', '#abcde'],
+      ['7-digit', '#abcdefa'],
+      ['9-digit', '#abcdef000'],
+    ])('rejects %s', (_, input) => {
+      expect(isCompleteHexColor(input)).toBe(false);
+    });
+
+    it('rejects hex without leading #', () => {
+      expect(isCompleteHexColor('aabbcc')).toBe(false);
+    });
+
+    it('rejects non-hex characters', () => {
+      expect(isCompleteHexColor('#aabbzz')).toBe(false);
+    });
+  });
+});