@keboola/design 1.3.1 → 2.0.1

package/src/blocks/InputOtp/InputOtp.test.tsx

@@ -0,0 +1,162 @@
+import { useState } from 'react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+
+import { REGEXP_ONLY_DIGITS, useInputOtpContext } from './index';
+import { InputOtp } from './InputOtp';
+
+// `input-otp` uses ResizeObserver to align its hidden input over the slots;
+// jsdom doesn't ship one, so stub a no-op implementation for the suite.
+beforeAll(() => {
+  vi.stubGlobal(
+    'ResizeObserver',
+    class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    },
+  );
+});
+
+const SixDigit = (props: Partial<React.ComponentProps<typeof InputOtp>> = {}) => (
+  <InputOtp aria-label="code" maxLength={6} {...props}>
+    <InputOtp.Group>
+      <InputOtp.Slot index={0} />
+      <InputOtp.Slot index={1} />
+      <InputOtp.Slot index={2} />
+      <InputOtp.Slot index={3} />
+      <InputOtp.Slot index={4} />
+      <InputOtp.Slot index={5} />
+    </InputOtp.Group>
+  </InputOtp>
+);
+
+const getInput = () => screen.getByLabelText('code') as HTMLInputElement;
+
+describe('<InputOtp />', () => {
+  it('renders one slot per maxLength position', () => {
+    render(<SixDigit />);
+    const slots = document.querySelectorAll('[data-slot-index]');
+    expect(slots).toHaveLength(6);
+  });
+
+  it('displays typed characters in their slots', () => {
+    const Controlled = () => {
+      const [value, setValue] = useState('');
+      return <SixDigit value={value} onChange={setValue} />;
+    };
+    render(<Controlled />);
+    fireEvent.change(getInput(), { target: { value: '123' } });
+    const slots = document.querySelectorAll('[data-slot-index]');
+    expect(slots[0]?.textContent).toBe('1');
+    expect(slots[1]?.textContent).toBe('2');
+    expect(slots[2]?.textContent).toBe('3');
+    expect(slots[3]?.textContent).toBe('');
+  });
+
+  it('fires onComplete exactly once when maxLength is reached', () => {
+    const onComplete = vi.fn();
+    render(<SixDigit onComplete={onComplete} />);
+    fireEvent.change(getInput(), { target: { value: '123456' } });
+    expect(onComplete).toHaveBeenCalledTimes(1);
+    expect(onComplete).toHaveBeenCalledWith('123456');
+  });
+
+  it('re-fires onComplete after editing and retyping a completed code', () => {
+    const onComplete = vi.fn();
+    const Controlled = () => {
+      const [value, setValue] = useState('');
+      return <SixDigit value={value} onChange={setValue} onComplete={onComplete} />;
+    };
+    render(<Controlled />);
+    fireEvent.change(getInput(), { target: { value: '123456' } });
+    fireEvent.change(getInput(), { target: { value: '12345' } });
+    fireEvent.change(getInput(), { target: { value: '123459' } });
+    expect(onComplete).toHaveBeenCalledTimes(2);
+    expect(onComplete).toHaveBeenLastCalledWith('123459');
+  });
+
+  it('truncates input beyond maxLength', () => {
+    const onChange = vi.fn();
+    render(<SixDigit onChange={onChange} />);
+    fireEvent.change(getInput(), { target: { value: '1234567890' } });
+    expect(onChange).toHaveBeenLastCalledWith('123456');
+  });
+
+  it('rejects characters that fail the pattern', () => {
+    const onChange = vi.fn();
+    render(<SixDigit pattern={REGEXP_ONLY_DIGITS} onChange={onChange} />);
+    fireEvent.change(getInput(), { target: { value: 'abc' } });
+    expect(onChange).not.toHaveBeenCalled();
+    expect(getInput().value).toBe('');
+  });
+
+  it('marks the input as aria-invalid when state="error"', () => {
+    render(<SixDigit state="error" />);
+    expect(getInput().getAttribute('aria-invalid')).toBe('true');
+  });
+
+  it('does not set aria-invalid in the default state', () => {
+    render(<SixDigit />);
+    expect(getInput().getAttribute('aria-invalid')).toBeNull();
+  });
+
+  it('blocks input when disabled', () => {
+    render(<SixDigit disabled />);
+    expect(getInput().disabled).toBe(true);
+  });
+
+  it('seeds the value from defaultValue', () => {
+    render(<SixDigit defaultValue="42" />);
+    const slots = document.querySelectorAll('[data-slot-index]');
+    expect(slots[0]?.textContent).toBe('4');
+    expect(slots[1]?.textContent).toBe('2');
+  });
+
+  it('exposes the render context to custom children via useInputOtpContext', () => {
+    const FirstSlotChar = () => {
+      const { slots } = useInputOtpContext();
+      return <span data-testid="first-slot-char">{slots[0]?.char ?? ''}</span>;
+    };
+    const Controlled = () => {
+      const [value, setValue] = useState('');
+      return (
+        <InputOtp aria-label="code" maxLength={6} value={value} onChange={setValue}>
+          <FirstSlotChar />
+        </InputOtp>
+      );
+    };
+    render(<Controlled />);
+    fireEvent.change(getInput(), { target: { value: '7' } });
+    expect(screen.getByTestId('first-slot-char').textContent).toBe('7');
+  });
+
+  it('throws if useInputOtpContext is called outside <InputOtp>', () => {
+    const Bare = () => {
+      useInputOtpContext();
+      return null;
+    };
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() => render(<Bare />)).toThrow(/inside <InputOtp>/);
+    consoleError.mockRestore();
+  });
+
+  it('renders a custom separator when provided', () => {
+    render(
+      <InputOtp aria-label="code" maxLength={6}>
+        <InputOtp.Group>
+          <InputOtp.Slot index={0} />
+          <InputOtp.Slot index={1} />
+          <InputOtp.Slot index={2} />
+        </InputOtp.Group>
+        <InputOtp.Separator>·</InputOtp.Separator>
+        <InputOtp.Group>
+          <InputOtp.Slot index={3} />
+          <InputOtp.Slot index={4} />
+          <InputOtp.Slot index={5} />
+        </InputOtp.Group>
+      </InputOtp>,
+    );
+    expect(screen.getByRole('separator')).toHaveTextContent('·');
+  });
+});

package/src/blocks/InputOtp/InputOtp.tsx

@@ -0,0 +1,62 @@
+import type { ComponentProps, ReactNode, Ref } from 'react';
+import { OTPInput, REGEXP_ONLY_DIGITS } from 'input-otp';
+
+import { cn } from '../../utils';
+
+import { type InputOtpSizing, type InputOtpState, InputOtpVariantContext } from './context';
+import { InputOtpGroup } from './InputOtpGroup';
+import { InputOtpSeparator } from './InputOtpSeparator';
+import { InputOtpSlot } from './InputOtpSlot';
+
+// The `OTPInput` props union pairs `render` with `children?: never` (and vice versa).
+// `Extract` picks the children-arm so passing `render` is a compile error.
+type OtpInputProps = ComponentProps<typeof OTPInput>;
+type OtpInputChildrenProps = Omit<
+  Extract<OtpInputProps, { children: ReactNode }>,
+  'containerClassName'
+>;
+
+type RootOwnProps = {
+  /** Visual size of each slot. Defaults to `md`. Matches InputGroup heights (sm/md/lg ≈ 32 / 36 / 40px). */
+  sizing?: InputOtpSizing;
+  /** Drives the error ring/border on each slot and `aria-invalid` on the inner input. */
+  state?: InputOtpState;
+  /** Class for the outer flex container that holds groups + separators. */
+  containerClassName?: string;
+};
+
+type RootProps = OtpInputChildrenProps & RootOwnProps;
+
+const Root = ({
+  ref,
+  sizing = 'md',
+  state = 'default',
+  pattern = REGEXP_ONLY_DIGITS,
+  containerClassName,
+  className,
+  children,
+  ...rest
+}: RootProps & { ref?: Ref<HTMLInputElement> }) => (
+  <InputOtpVariantContext value={{ sizing, state }}>
+    <OTPInput
+      {...rest}
+      ref={ref}
+      pattern={pattern}
+      aria-invalid={state === 'error' || undefined}
+      containerClassName={cn(
+        'tw-flex tw-items-center tw-gap-2 has-[:disabled]:tw-opacity-50',
+        containerClassName,
+      )}
+      className={cn('disabled:tw-cursor-not-allowed', className)}
+    >
+      {children}
+    </OTPInput>
+  </InputOtpVariantContext>
+);
+
+export const InputOtp = Object.assign(Root, {
+  Group: InputOtpGroup,
+  Slot: InputOtpSlot,
+  Separator: InputOtpSeparator,
+});
+export type { RootProps as InputOtpProps };

package/src/blocks/InputOtp/InputOtpGroup.tsx

@@ -0,0 +1,13 @@
+import type { ComponentProps, Ref } from 'react';
+
+import { cn } from '../../utils';
+
+type GroupProps = ComponentProps<'div'>;
+
+export const InputOtpGroup = ({
+  ref,
+  className,
+  ...props
+}: GroupProps & { ref?: Ref<HTMLDivElement> }) => (
+  <div ref={ref} className={cn('tw-flex tw-items-center tw-gap-2', className)} {...props} />
+);

package/src/blocks/InputOtp/InputOtpSeparator.tsx

@@ -0,0 +1,23 @@
+import type { ComponentProps, Ref } from 'react';
+
+import { Minus } from '../../icons';
+import { cn } from '../../utils';
+
+type SeparatorProps = ComponentProps<'div'>;
+
+export const InputOtpSeparator = ({
+  ref,
+  children,
+  className,
+  ...props
+}: SeparatorProps & { ref?: Ref<HTMLDivElement> }) => (
+  <div
+    ref={ref}
+    role="separator"
+    aria-orientation="vertical"
+    className={cn('tw-flex tw-items-center tw-text-muted-foreground', className)}
+    {...props}
+  >
+    {children ?? <Minus className="tw-size-4" />}
+  </div>
+);

package/src/blocks/InputOtp/InputOtpSlot.styles.ts

@@ -0,0 +1,52 @@
+import { cva, type VariantProps } from 'class-variance-authority';
+
+// Slot sizes mirror InputGroup (`small` / `medium` / `default` ≈ 32 / 36 / 40px) so an OTP
+// field can sit next to a regular text input without the row jumping.
+export const slotVariants = cva(
+  [
+    'tw-relative',
+    'tw-flex',
+    'tw-items-center',
+    'tw-justify-center',
+    'tw-border',
+    'tw-border-input',
+    'tw-bg-background',
+    'tw-text-foreground',
+    'tw-font-medium',
+    'tw-tabular-nums',
+    'tw-rounded-lg',
+    'tw-transition',
+    'tw-outline-none',
+    // active slot sits above its neighbours so its ring isn't clipped
+    'data-[active=true]:tw-z-10',
+    'data-[active=true]:tw-border-primary',
+    'data-[active=true]:tw-ring-2',
+    'data-[active=true]:tw-ring-primary/50',
+  ],
+  {
+    defaultVariants: {
+      sizing: 'md',
+      state: 'default',
+    },
+    variants: {
+      sizing: {
+        sm: ['tw-h-8', 'tw-w-8', 'tw-text-sm'],
+        md: ['tw-h-9', 'tw-w-9', 'tw-text-base'],
+        lg: ['tw-h-10', 'tw-w-10', 'tw-text-lg'],
+      },
+      // `!` forces the border colour over the base `tw-border-input` once tailwind-merge dedupes.
+      // Matches the pattern InputGroup uses for its argo error state.
+      state: {
+        default: [],
+        error: [
+          '!tw-border-destructive',
+          'tw-bg-destructive/5',
+          'data-[active=true]:!tw-border-destructive',
+          'data-[active=true]:tw-ring-destructive/40',
+        ],
+      },
+    },
+  },
+);
+
+export type SlotVariants = VariantProps<typeof slotVariants>;

package/src/blocks/InputOtp/InputOtpSlot.tsx

@@ -0,0 +1,44 @@
+import type { ComponentProps, Ref } from 'react';
+
+import { cn } from '../../utils';
+
+import { useInputOtpRenderContext, useInputOtpVariant } from './context';
+import { slotVariants } from './InputOtpSlot.styles';
+
+type SlotProps = Omit<ComponentProps<'div'>, 'children'> & {
+  index: number;
+};
+
+export const InputOtpSlot = ({
+  ref,
+  index,
+  className,
+  ...props
+}: SlotProps & { ref?: Ref<HTMLDivElement> }) => {
+  const { slots } = useInputOtpRenderContext();
+  const { sizing, state } = useInputOtpVariant();
+  const slot = slots[index];
+  const char = slot?.char ?? null;
+  const isActive = slot?.isActive ?? false;
+  const hasFakeCaret = slot?.hasFakeCaret ?? false;
+
+  return (
+    <div
+      ref={ref}
+      data-active={isActive || undefined}
+      data-slot-index={index}
+      className={cn(slotVariants({ sizing, state }), className)}
+      {...props}
+    >
+      {char}
+      {hasFakeCaret && (
+        <div
+          aria-hidden="true"
+          className="tw-pointer-events-none tw-absolute tw-inset-0 tw-flex tw-items-center tw-justify-center"
+        >
+          <div className="tw-h-1/2 tw-w-px tw-animate-caret-blink tw-bg-foreground" />
+        </div>
+      )}
+    </div>
+  );
+};

package/src/blocks/InputOtp/context.ts

@@ -0,0 +1,23 @@
+import { createContext, use } from 'react';
+import { OTPInputContext } from 'input-otp';
+
+import { type SlotVariants } from './InputOtpSlot.styles';
+
+type Sizing = NonNullable<SlotVariants['sizing']>;
+type State = NonNullable<SlotVariants['state']>;
+
+type InputOtpVariantContextValue = {
+  sizing: Sizing;
+  state: State;
+};
+
+export const InputOtpVariantContext = createContext<InputOtpVariantContextValue>({
+  sizing: 'md',
+  state: 'default',
+});
+
+export const useInputOtpVariant = () => use(InputOtpVariantContext);
+
+export const useInputOtpRenderContext = () => use(OTPInputContext);
+
+export type { Sizing as InputOtpSizing, State as InputOtpState };

package/src/blocks/InputOtp/index.ts

@@ -0,0 +1,23 @@
+import { use } from 'react';
+import { OTPInputContext, type RenderProps } from 'input-otp';
+
+export {
+  REGEXP_ONLY_CHARS,
+  REGEXP_ONLY_DIGITS,
+  REGEXP_ONLY_DIGITS_AND_CHARS,
+  type SlotProps as InputOtpRenderSlotProps,
+} from 'input-otp';
+
+/**
+ * Access the `input-otp` render context (slots, focus, hover) — use this inside a custom
+ * child of `<InputOtp>` to render slots yourself. Throws if called outside `<InputOtp>`.
+ */
+export const useInputOtpContext = (): RenderProps => {
+  const ctx = use(OTPInputContext);
+  if (!ctx.slots) {
+    throw new Error('useInputOtpContext must be used inside <InputOtp>.');
+  }
+  return ctx;
+};
+
+export * from './InputOtp';

package/src/blocks/PageHeader/AGENTS.md

@@ -48,7 +48,7 @@ either variant.
 ## Rules from the patterns
 
 - **Index**: no breadcrumbs, no overflow menu, no search/filter/sort. Search
-  belongs in `PageLayout.Toolbar`.
+  belongs in `PageToolbar`.
 - **Detail**: breadcrumbs are required (use real entity names; last item is
   not a link). Overflow menu lives on the breadcrumbs row, never in the title
   row.

package/src/blocks/PageHeader/PageHeader.stories.tsx

@@ -18,6 +18,7 @@ import { DropdownMenu } from '../../components/DropdownMenu';
 import { MarkdownEditor } from '../../components/MarkdownEditor';
 import { Tabs, TabsContent } from '../../components/Tabs';
 import { PageLayout } from '../PageLayout';
+import { PageToolbar } from '../PageToolbar';
 import { SplitButton } from '../SplitButton';
 
 import { PageHeader } from './PageHeader';
@@ -69,9 +70,11 @@ export const IndexFlows: Story = {
           </>
         }
       />
-      <PageLayout.Toolbar>
-        <Placeholder label="Search input + filter pills" height="tw-h-10" />
-      </PageLayout.Toolbar>
+      <PageToolbar>
+        <PageToolbar.Search>
+          <Placeholder label="Search input + filter pills" height="tw-h-10" />
+        </PageToolbar.Search>
+      </PageToolbar>
       <PageLayout.Content>
         <Placeholder label="EntityList" height="tw-h-96" />
       </PageLayout.Content>

package/src/blocks/PageHeader/PageHeaderIndex.tsx

@@ -11,7 +11,7 @@ import { descriptionClass, titleClass, titleRowClass } from './styles';
 //   - At most one primary `action`; pair with the `documentation` icon button.
 /**
  * Props for `PageHeader.Index`. Index pages have no breadcrumbs and no overflow menu — search and filters
- * belong in `PageLayout.Toolbar`, not here.
+ * belong in `PageToolbar`, not here.
  */
 type PageHeaderIndexProps = Omit<ComponentPropsWithoutRef<'header'>, 'title'> & {
   title: ReactNode;
@@ -35,7 +35,7 @@ type PageHeaderIndexProps = Omit<ComponentPropsWithoutRef<'header'>, 'title'> &
  * **When NOT to use:** for single-entity detail pages use `PageHeader.Detail`; for layouts that don't fit
  * either pattern host custom JSX in `PageLayout.Header` directly.
  * **Composition:** nest inside `PageLayout.Header`. Always pass `Button argo` into `action` and
- * `documentation`. Search and filter chips belong in `PageLayout.Toolbar`, not here.
+ * `documentation`. Search and filter chips belong in `PageToolbar`, not here.
  */
 export const PageHeaderIndex = ({
   ref,

package/src/blocks/PageLayout/AGENTS.md

@@ -24,7 +24,7 @@ PageLayout (Root)            ← max-width container, vertical rhythm (gap-4)
 ├── PageLayout.Breadcrumbs   ← Detail pattern only; usually composed by PageHeader.Detail
 ├── PageLayout.Header        ← host PageHeader.Index / PageHeader.Detail (or custom JSX)
 ├── PageLayout.Tabs          ← escape hatch for routing-based tab rows
-├── PageLayout.Toolbar       ← search / filter pills (NEVER in header)
+├── PageToolbar              ← search / filter pills (NEVER in header) — separate block
 ├── PageLayout.Content       ← main slot
 └── PageLayout.Footer        ← bottom action bar (form submit, `sticky` variant)
 ```
@@ -42,7 +42,7 @@ All slots take any `ReactNode` — no structured props live on the slot itself.
   <PageLayout.Header>
     <PageHeader.Index title="Storage" metadata="3 buckets and 39 tables" … />
   </PageLayout.Header>
-  <PageLayout.Toolbar>{searchAndFilters}</PageLayout.Toolbar>
+  <PageToolbar>{searchAndFilters}</PageToolbar>
   <PageLayout.Content>{list}</PageLayout.Content>
 </PageLayout>
 
@@ -73,7 +73,7 @@ provides the chrome.
 - **Index pages do not show breadcrumbs.** Skip `PageLayout.Breadcrumbs`
   entirely on top-level list pages.
 - **No search / filters / sorting in the header** — those belong in
-  `PageLayout.Toolbar`.
+  `PageToolbar`.
 
 ## Component rules
 

package/src/blocks/PageLayout/PageLayout.stories.tsx

@@ -3,6 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Breadcrumb } from '../../components/Breadcrumb';
 import { Button } from '../../components/Button';
 import { Tabs, TabsContent } from '../../components/Tabs';
+import { PageToolbar } from '../PageToolbar';
 
 import { PageLayout } from './PageLayout';
 
@@ -15,7 +16,7 @@ export default {
     docs: {
       description: {
         component:
-          'Compound block that gives every kbc-ui page the same shape — max-width container, vertical rhythm, and slots for `Breadcrumbs`, `Header`, `Tabs`, `Toolbar`, `Content`, `Footer`. The slots are intentionally thin — for the structured Index / Detail page-header patterns reach for the `PageHeader` block. The page-navigation `Sidebar` lives **outside** `PageLayout` in the app shell.',
+          'Compound block that gives every kbc-ui page the same shape — max-width container, vertical rhythm, and slots for `Breadcrumbs`, `Header`, `Tabs`, `Content`, `Footer`. The slots are intentionally thin — for the structured Index / Detail page-header patterns reach for the `PageHeader` block, and for the search / filter row reach for the `PageToolbar` block. The page-navigation `Sidebar` lives **outside** `PageLayout` in the app shell.',
       },
     },
   },
@@ -53,9 +54,11 @@ export const Anatomy: Story = {
         <Placeholder label="PageHeader.Index / PageHeader.Detail goes here" height="tw-h-24" />
       </PageLayout.Header>
 
-      <PageLayout.Toolbar>
-        <Placeholder label="Search input + filter pills" height="tw-h-10" />
-      </PageLayout.Toolbar>
+      <PageToolbar>
+        <PageToolbar.Search>
+          <Placeholder label="Search input + filter pills" height="tw-h-10" />
+        </PageToolbar.Search>
+      </PageToolbar>
 
       <PageLayout.Content>
         <Placeholder label="EntityList / Table" height="tw-h-96" />

package/src/blocks/PageLayout/PageLayout.tsx

@@ -75,21 +75,6 @@ const Tabs = ({
   </div>
 );
 
-const Toolbar = ({
-  ref,
-  className,
-  children,
-  ...props
-}: ComponentPropsWithoutRef<'div'> & { ref?: Ref<ElementRef<'div'>> }) => (
-  <div
-    ref={ref}
-    className={cn('tw-flex tw-w-full tw-flex-wrap tw-items-center tw-gap-3', className)}
-    {...props}
-  >
-    {children}
-  </div>
-);
-
 const Content = ({
   ref,
   className,
@@ -135,7 +120,7 @@ const Footer = ({
  * **When NOT to use:** the left-rail `Sidebar` lives in the app shell outside `PageLayout`. For embedded
  * widgets or modal bodies the layout chrome is the modal / card itself, not `PageLayout`.
  * **Composition:** `PageLayout` is opinionated about chrome only — slots accept any `ReactNode`. Put
- * search / filter pills in `PageLayout.Toolbar`, never in the header. Form submit bars go in
+ * search / filter pills in `PageToolbar`, never in the header. Form submit bars go in
  * `PageLayout.Footer sticky`.
  *
  * @see RECIPES.md#list-detail — for the index → detail page pattern
@@ -147,8 +132,6 @@ export const PageLayout = Object.assign(Root, {
   Header,
   /** Escape hatch for routing-based tab rows. Use `Tabs` / `TabsContent` core components inside, never a raw `<button>`. */
   Tabs,
-  /** Search / filter pill row. Belongs here, NOT in the header per the page-header patterns. */
-  Toolbar,
   /** Main content slot. Lists, cards, tables. */
   Content,
   /** Bottom action bar — form submit + cancel. Pass `sticky` for a footer that pins to the viewport. */