@keboola/design 1.0.0

package/src/blocks/NumberInput/NumberInput.test.tsx

@@ -0,0 +1,148 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { NumberInput } from './NumberInput';
+
+const getInput = () => screen.getByPlaceholderText('number') as HTMLInputElement;
+
+describe('<NumberInput />', () => {
+  describe('controlled state', () => {
+    it('renders empty when value is null', () => {
+      render(<NumberInput placeholder="number" value={null} />);
+      expect(getInput().value).toBe('');
+    });
+
+    it('renders empty when value is undefined and no defaultValue', () => {
+      render(<NumberInput placeholder="number" />);
+      expect(getInput().value).toBe('');
+    });
+
+    it('renders the controlled value', () => {
+      render(<NumberInput placeholder="number" value={42} onValueChange={vi.fn()} />);
+      expect(getInput().value).toBe('42');
+    });
+
+    it('emits onValueChange with parsed number on input', () => {
+      const onValueChange = vi.fn();
+      render(<NumberInput placeholder="number" value={null} onValueChange={onValueChange} />);
+      fireEvent.change(getInput(), { target: { value: '7' } });
+      expect(onValueChange).toHaveBeenCalledWith(7);
+    });
+
+    it('emits onValueChange(null) when input is cleared', () => {
+      const onValueChange = vi.fn();
+      render(<NumberInput placeholder="number" value={5} onValueChange={onValueChange} />);
+      fireEvent.change(getInput(), { target: { value: '' } });
+      expect(onValueChange).toHaveBeenCalledWith(null);
+    });
+
+    it('emits onValueBlur with the current numeric value', () => {
+      const onValueBlur = vi.fn();
+      render(<NumberInput placeholder="number" value={3} onValueBlur={onValueBlur} />);
+      fireEvent.blur(getInput());
+      expect(onValueBlur).toHaveBeenCalledWith(3);
+    });
+
+    it('emits onValueBlur(null) when blurring an empty input', () => {
+      const onValueBlur = vi.fn();
+      render(<NumberInput placeholder="number" value={null} onValueBlur={onValueBlur} />);
+      fireEvent.blur(getInput());
+      expect(onValueBlur).toHaveBeenCalledWith(null);
+    });
+  });
+
+  describe('uncontrolled state', () => {
+    it('seeds the input from defaultValue', () => {
+      render(<NumberInput placeholder="number" defaultValue={5} />);
+      expect(getInput().value).toBe('5');
+    });
+
+    it('treats null defaultValue as empty', () => {
+      render(<NumberInput placeholder="number" defaultValue={null} />);
+      expect(getInput().value).toBe('');
+    });
+
+    it('propagates user typing through onValueChange', () => {
+      const onValueChange = vi.fn();
+      render(<NumberInput placeholder="number" onValueChange={onValueChange} />);
+      const input = getInput();
+      fireEvent.change(input, { target: { value: '12' } });
+      expect(input.value).toBe('12');
+      expect(onValueChange).toHaveBeenLastCalledWith(12);
+    });
+  });
+
+  describe('NaN handling', () => {
+    it('emits null (never NaN) when the input has no parseable value', () => {
+      const onValueChange = vi.fn();
+      render(<NumberInput placeholder="number" defaultValue={5} onValueChange={onValueChange} />);
+      fireEvent.change(getInput(), { target: { value: '' } });
+      expect(onValueChange).toHaveBeenCalledWith(null);
+      expect(onValueChange).not.toHaveBeenCalledWith(Number.NaN);
+    });
+  });
+
+  describe('pass-through', () => {
+    it('forwards min / max / step / disabled / readOnly / id / name to the underlying input', () => {
+      render(
+        <NumberInput
+          placeholder="number"
+          id="qty"
+          name="quantity"
+          min={1}
+          max={10}
+          step={2}
+          disabled
+          readOnly
+        />,
+      );
+      const input = getInput();
+      expect(input.id).toBe('qty');
+      expect(input.name).toBe('quantity');
+      expect(input.min).toBe('1');
+      expect(input.max).toBe('10');
+      expect(input.step).toBe('2');
+      expect(input.disabled).toBe(true);
+      expect(input.readOnly).toBe(true);
+      expect(input.type).toBe('number');
+    });
+  });
+
+  describe('forwardRef', () => {
+    it('forwards ref to the <input type="number"> element', () => {
+      let captured: HTMLInputElement | null = null;
+      render(
+        <NumberInput
+          placeholder="number"
+          ref={(node) => {
+            captured = node;
+          }}
+        />,
+      );
+      expect(captured).toBe(getInput());
+      expect(captured!.type).toBe('number');
+    });
+  });
+
+  describe('external onChange / onBlur', () => {
+    it('fires onChange alongside onValueChange', () => {
+      const onChange = vi.fn();
+      const onValueChange = vi.fn();
+      render(
+        <NumberInput placeholder="number" onChange={onChange} onValueChange={onValueChange} />,
+      );
+      fireEvent.change(getInput(), { target: { value: '9' } });
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onValueChange).toHaveBeenCalledWith(9);
+    });
+
+    it('fires onBlur alongside onValueBlur', () => {
+      const onBlur = vi.fn();
+      const onValueBlur = vi.fn();
+      render(<NumberInput placeholder="number" onBlur={onBlur} onValueBlur={onValueBlur} />);
+      fireEvent.blur(getInput());
+      expect(onBlur).toHaveBeenCalledTimes(1);
+      expect(onValueBlur).toHaveBeenCalled();
+    });
+  });
+});

package/src/blocks/NumberInput/NumberInput.tsx

@@ -0,0 +1,89 @@
+import type {
+  ChangeEvent,
+  ChangeEventHandler,
+  ComponentProps,
+  ElementRef,
+  FocusEventHandler,
+  ReactNode,
+  Ref,
+} from 'react';
+
+import { InputGroup } from '../../components/InputGroup';
+
+type InputGroupProps = Pick<
+  ComponentProps<typeof InputGroup>,
+  'variant' | 'focusVariant' | 'state' | 'sizing'
+>;
+
+type InputGroupInputProps = Omit<
+  ComponentProps<typeof InputGroup.Input>,
+  'value' | 'defaultValue' | 'type' | 'prefix'
+>;
+
+type Props = InputGroupProps &
+  InputGroupInputProps & {
+    value?: number | null;
+    defaultValue?: number | null;
+    onValueChange?: (value: number | null) => void;
+    onValueBlur?: (value: number | null) => void;
+    prefix?: ReactNode;
+    suffix?: ReactNode;
+  };
+
+const toNumberOrNull = (event: ChangeEvent<HTMLInputElement>) =>
+  Number.isNaN(event.target.valueAsNumber) ? null : event.target.valueAsNumber;
+
+export const NumberInput = ({
+  ref,
+  state,
+  variant,
+  focusVariant,
+  sizing,
+  className,
+
+  value,
+  defaultValue,
+  onValueChange,
+  onValueBlur,
+  onChange,
+  onBlur,
+
+  prefix,
+  suffix,
+
+  ...inputProps
+}: Props & { ref?: Ref<ElementRef<'input'>> }) => {
+  const handleChange: ChangeEventHandler<HTMLInputElement> = (event) => {
+    onValueChange?.(toNumberOrNull(event));
+    onChange?.(event);
+  };
+
+  const handleBlur: FocusEventHandler<HTMLInputElement> = (event) => {
+    onValueBlur?.(toNumberOrNull(event));
+    onBlur?.(event);
+  };
+
+  const isControlled = value !== undefined;
+  const valueProp = isControlled ? { value: value ?? '' } : { defaultValue: defaultValue ?? '' };
+
+  return (
+    <InputGroup
+      state={state}
+      variant={variant}
+      sizing={sizing}
+      focusVariant={focusVariant}
+      className={className}
+    >
+      {prefix && <InputGroup.Addon align="inline-start">{prefix}</InputGroup.Addon>}
+      <InputGroup.Input
+        {...inputProps}
+        {...valueProp}
+        ref={ref}
+        type="number"
+        onChange={handleChange}
+        onBlur={handleBlur}
+      />
+      {suffix && <InputGroup.Addon align="inline-end">{suffix}</InputGroup.Addon>}
+    </InputGroup>
+  );
+};

package/src/blocks/NumberInput/index.ts

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

package/src/blocks/PageHeader/AGENTS.md

@@ -0,0 +1,77 @@
+# PageHeader
+
+Structured page-header block that encodes the
+[evviku page-header patterns](https://github.com/evviku/design-system-docs/tree/main/docs/patterns/page-header)
+1:1 at the type level. Two discriminated variants:
+
+- `PageHeader.Index` — top-level list/collection pages.
+- `PageHeader.Detail` — single-entity pages.
+
+The variant choice enforces the pattern constraints (e.g. you cannot pass an
+overflow menu to `Index`, or `metadata` to `Detail`). Reach for
+`PageLayout.Header` / `PageLayout.Breadcrumbs` only for layouts that don't fit
+either variant.
+
+## When to use which
+
+| Use `PageHeader.Index` when                            | Use `PageHeader.Detail` when                               |
+| ------------------------------------------------------ | ---------------------------------------------------------- |
+| The page is a top-level list (Flows, Storage, Jobs, …) | The page shows one entity (a bucket, flow, data app, …)    |
+| There is no parent in the same section                 | The entity has a parent hierarchy worth breadcrumbing      |
+| The primary action is "create / add a new X"           | The primary action is "edit / deploy / run on this entity" |
+
+## API at a glance
+
+```tsx
+// Index — no breadcrumbs, metadata > description, optional headerNav.
+<PageHeader.Index
+  title="Storage"
+  metadata="3 buckets and 39 tables"  // or `description` (mutually exclusive)
+  documentation={<Button argo variant="invisible" icon="book-blank" />}
+  action={<Button argo>New bucket</Button>}
+  headerNav={<Tabs ... />}
+/>
+
+// Detail — mandatory breadcrumbs, overflow row, ≤2 visible actions.
+<PageHeader.Detail
+  breadcrumbs={<Breadcrumb>...</Breadcrumb>}
+  overflowActions={<DropdownMenu>...</DropdownMenu>}
+  title="Marketing bucket"
+  badges={<><Badge>Active</Badge></>}
+  description="..."
+  secondaryAction={<Button argo variant="secondary">Open editor</Button>}
+  primaryAction={<Button argo>Deploy</Button>}
+  headerNav={<Tabs ... />}
+/>
+```
+
+## Rules from the patterns
+
+- **Index**: no breadcrumbs, no overflow menu, no search/filter/sort. Search
+  belongs in `PageLayout.Toolbar`.
+- **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.
+- **Max 2 visible actions on Detail** (`primaryAction` + optional
+  `secondaryAction`). Everything else goes in `overflowActions`.
+- **`metadata` wins over `description`** on Index. Pass `metadata` for count
+  / system summaries; reserve `description` for prose.
+- **`headerNav` only when there is >1 dataset / section** worth navigating to.
+
+## Component rules
+
+- **Always opt into the `argo` variant** on the Buttons you pass into the
+  slots (`Button argo …`).
+- **Compose** existing `Breadcrumb`, `Badge`, `DropdownMenu`, `Tabs` from
+  `@keboola/design` — slots take any `ReactNode`, but use the design-system
+  pieces.
+- Title and description can be any `ReactNode`; pass an
+  `InlineEditableText` (when it lands) for editable titles per the Detail
+  pattern.
+
+## Stories
+
+- `IndexFlows` — description + secondary/primary actions, no header nav.
+- `IndexStorage` — `metadata` count summary + 5-tab `headerNav`.
+- `DetailBucket` — breadcrumbs + overflow + badges + primary action.
+- `DetailDataApp` — primary + secondary actions + 3-tab `headerNav`.

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

@@ -0,0 +1,272 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Badge } from '../../components/Badge';
+import { Breadcrumb } from '../../components/Breadcrumb';
+import { Button } from '../../components/Button';
+import { DropdownMenu } from '../../components/DropdownMenu';
+import { Tabs, TabsContent } from '../../components/Tabs';
+import { PageLayout } from '../PageLayout';
+import { SplitButton } from '../SplitButton';
+
+import { PageHeader } from './PageHeader';
+
+type Story = StoryObj<typeof PageHeader.Index>;
+
+export default {
+  component: PageHeader.Index,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Structured page-header block matching the [evviku page-header patterns](https://github.com/evviku/design-system-docs/tree/main/docs/patterns/page-header). Two discriminated variants — `PageHeader.Index` (top-level list pages, no breadcrumbs) and `PageHeader.Detail` (entity pages, mandatory breadcrumbs + overflow row + ≤2 visible actions). The variant chosen at the type level enforces the pattern constraints (e.g. you cannot pass an overflow menu to `Index`, or `metadata` to `Detail`).',
+      },
+    },
+  },
+} satisfies Meta<typeof PageHeader.Index>;
+
+const Placeholder = ({ label, height = 'tw-h-48' }: { label: string; height?: string }) => (
+  <div
+    className={`tw-flex tw-items-center tw-justify-center tw-rounded tw-border tw-border-dashed tw-border-border tw-bg-muted/30 tw-text-sm tw-text-muted-foreground ${height}`}
+  >
+    {label}
+  </div>
+);
+
+// Index — Flows (description + primary + secondary actions, no header nav).
+export const IndexFlows: Story = {
+  render: () => (
+    <PageLayout>
+      <PageHeader.Index
+        title="Flows"
+        description="Build flows with branching logic and conditions. Tasks run based on previous results, errors, or custom expressions."
+        documentation={
+          <Button argo variant="invisible" icon="book-blank" aria-label="Documentation" />
+        }
+        action={
+          <>
+            <Button argo variant="secondary" onClick={() => {}}>
+              New folder
+            </Button>
+            <Button argo onClick={() => {}}>
+              New flow
+            </Button>
+          </>
+        }
+      />
+      <PageLayout.Toolbar>
+        <Placeholder label="Search input + filter pills" height="tw-h-10" />
+      </PageLayout.Toolbar>
+      <PageLayout.Content>
+        <Placeholder label="EntityList" height="tw-h-96" />
+      </PageLayout.Content>
+    </PageLayout>
+  ),
+};
+
+// Index — Storage (metadata + header nav + SplitButton primary action).
+// SSOT example: `action.type = "button-group"` → SplitButton in our design system.
+export const IndexStorage: Story = {
+  render: () => (
+    <PageLayout>
+      <PageHeader.Index
+        title="Storage"
+        metadata="3 buckets and 39 tables"
+        documentation={
+          <Button argo variant="invisible" icon="book-blank" aria-label="Documentation" />
+        }
+        action={
+          <SplitButton
+            argo
+            onClick={() => {}}
+            actions={
+              <>
+                <SplitButton.Action icon="upload" onClick={() => {}}>
+                  Upload file
+                </SplitButton.Action>
+                <SplitButton.Action icon="cloud-arrow-down" onClick={() => {}}>
+                  Import from external storage
+                </SplitButton.Action>
+              </>
+            }
+          >
+            New bucket
+          </SplitButton>
+        }
+        headerNav={
+          <Tabs
+            defaultValue="tables"
+            triggers={[
+              { value: 'tables', title: 'Tables & Buckets' },
+              { value: 'files', title: 'Files' },
+              { value: 'data-streams', title: 'Data Streams' },
+              { value: 'storage-jobs', title: 'Storage Jobs' },
+              { value: 'events', title: 'Events' },
+            ]}
+          >
+            <TabsContent value="tables">
+              <Placeholder label="Tables & Buckets list" height="tw-h-96" />
+            </TabsContent>
+            <TabsContent value="files">
+              <Placeholder label="Files list" height="tw-h-96" />
+            </TabsContent>
+            <TabsContent value="data-streams">
+              <Placeholder label="Data Streams list" height="tw-h-96" />
+            </TabsContent>
+            <TabsContent value="storage-jobs">
+              <Placeholder label="Storage Jobs list" height="tw-h-96" />
+            </TabsContent>
+            <TabsContent value="events">
+              <Placeholder label="Events list" height="tw-h-96" />
+            </TabsContent>
+          </Tabs>
+        }
+      />
+    </PageLayout>
+  ),
+};
+
+// Detail — bucket (breadcrumbs + overflow + badges + primary action).
+export const DetailBucket: Story = {
+  render: () => (
+    <PageLayout>
+      <PageHeader.Detail
+        breadcrumbs={
+          <Breadcrumb>
+            <Breadcrumb.List>
+              <Breadcrumb.Item>
+                <Breadcrumb.Link href="#">Storage</Breadcrumb.Link>
+              </Breadcrumb.Item>
+              <Breadcrumb.Separator />
+              <Breadcrumb.Item>
+                <Breadcrumb.Page>Marketing bucket</Breadcrumb.Page>
+              </Breadcrumb.Item>
+            </Breadcrumb.List>
+          </Breadcrumb>
+        }
+        overflowActions={
+          <DropdownMenu>
+            <DropdownMenu.Trigger asChild>
+              <Button
+                argo
+                variant="invisible"
+                size="icon-sm"
+                icon="ellipsis-vertical"
+                aria-label="More actions"
+              />
+            </DropdownMenu.Trigger>
+            <DropdownMenu.Content align="end">
+              <DropdownMenu.Item icon="copy">Copy</DropdownMenu.Item>
+              <DropdownMenu.Item icon="user-group">Manage permissions</DropdownMenu.Item>
+              <DropdownMenu.Separator />
+              <DropdownMenu.Item icon="trash">Delete</DropdownMenu.Item>
+            </DropdownMenu.Content>
+          </DropdownMenu>
+        }
+        title="Marketing bucket"
+        badges={
+          <>
+            <Badge color="green">Active</Badge>
+            <Badge color="gray">Shared</Badge>
+          </>
+        }
+        description="Contains marketing datasets and transformation outputs."
+        primaryAction={
+          <SplitButton
+            argo
+            onClick={() => {}}
+            actions={
+              <>
+                <SplitButton.Action icon="upload" onClick={() => {}}>
+                  Upload CSV
+                </SplitButton.Action>
+                <SplitButton.Action icon="link" onClick={() => {}}>
+                  Link existing table
+                </SplitButton.Action>
+              </>
+            }
+          >
+            Add table
+          </SplitButton>
+        }
+      />
+      <PageLayout.Content>
+        <Placeholder label="Bucket detail body" height="tw-h-96" />
+      </PageLayout.Content>
+    </PageLayout>
+  ),
+};
+
+// Detail — sales dashboard (primary + secondary actions + header nav).
+export const DetailDataApp: Story = {
+  render: () => (
+    <PageLayout>
+      <PageHeader.Detail
+        breadcrumbs={
+          <Breadcrumb>
+            <Breadcrumb.List>
+              <Breadcrumb.Item>
+                <Breadcrumb.Link href="#">Data Apps</Breadcrumb.Link>
+              </Breadcrumb.Item>
+              <Breadcrumb.Separator />
+              <Breadcrumb.Item>
+                <Breadcrumb.Page>Sales dashboard</Breadcrumb.Page>
+              </Breadcrumb.Item>
+            </Breadcrumb.List>
+          </Breadcrumb>
+        }
+        overflowActions={
+          <DropdownMenu>
+            <DropdownMenu.Trigger asChild>
+              <Button
+                argo
+                variant="invisible"
+                size="icon-sm"
+                icon="ellipsis-vertical"
+                aria-label="More actions"
+              />
+            </DropdownMenu.Trigger>
+            <DropdownMenu.Content align="end">
+              <DropdownMenu.Item icon="copy">Duplicate</DropdownMenu.Item>
+              <DropdownMenu.Item icon="bug">Debug mode</DropdownMenu.Item>
+              <DropdownMenu.Separator />
+              <DropdownMenu.Item icon="trash">Delete</DropdownMenu.Item>
+            </DropdownMenu.Content>
+          </DropdownMenu>
+        }
+        title="Sales dashboard"
+        badges={<Badge color="green">Running</Badge>}
+        secondaryAction={
+          <Button argo variant="secondary" onClick={() => {}}>
+            Open editor
+          </Button>
+        }
+        primaryAction={
+          <Button argo onClick={() => {}}>
+            Deploy
+          </Button>
+        }
+        headerNav={
+          <Tabs
+            defaultValue="overview"
+            triggers={[
+              { value: 'overview', title: 'Overview' },
+              { value: 'events', title: 'Events' },
+              { value: 'settings', title: 'Settings' },
+            ]}
+          >
+            <TabsContent value="overview">
+              <Placeholder label="Overview" height="tw-h-96" />
+            </TabsContent>
+            <TabsContent value="events">
+              <Placeholder label="Events" height="tw-h-96" />
+            </TabsContent>
+            <TabsContent value="settings">
+              <Placeholder label="Settings" height="tw-h-96" />
+            </TabsContent>
+          </Tabs>
+        }
+      />
+    </PageLayout>
+  ),
+};

package/src/blocks/PageHeader/PageHeader.tsx

@@ -0,0 +1,7 @@
+import { PageHeaderDetail } from './PageHeaderDetail';
+import { PageHeaderIndex } from './PageHeaderIndex';
+
+export const PageHeader = {
+  Index: PageHeaderIndex,
+  Detail: PageHeaderDetail,
+};

package/src/blocks/PageHeader/PageHeaderDetail.tsx

@@ -0,0 +1,62 @@
+import type { ComponentPropsWithoutRef, ElementRef, ReactNode, Ref } from 'react';
+
+import { cn } from '../../utils';
+
+import { badgesClass, descriptionClass, titleClass, titleRowClass } from './styles';
+
+// Detail page header — single entity pages (bucket, flow, data app, …).
+// Pattern: docs/patterns/page-header/detail/detail-page-header.md
+//   - Breadcrumbs are required; overflow menu sits on the breadcrumbs row.
+//   - Max two visible actions: `primaryAction` + optional `secondaryAction`.
+//   - All other actions belong in the breadcrumbs-row overflow menu.
+type PageHeaderDetailProps = ComponentPropsWithoutRef<'header'> & {
+  breadcrumbs: ReactNode;
+  overflowActions?: ReactNode;
+  title: ReactNode;
+  badges?: ReactNode;
+  description?: ReactNode;
+  primaryAction?: ReactNode;
+  secondaryAction?: ReactNode;
+  headerNav?: ReactNode;
+};
+
+export const PageHeaderDetail = ({
+  ref,
+  className,
+  breadcrumbs,
+  overflowActions,
+  title,
+  badges,
+  description,
+  primaryAction,
+  secondaryAction,
+  headerNav,
+  ...props
+}: PageHeaderDetailProps & { ref?: Ref<ElementRef<'header'>> }) => (
+  <header ref={ref} className={cn('tw-flex tw-w-full tw-flex-col tw-gap-4', className)} {...props}>
+    <div className="tw-flex tw-w-full tw-items-center tw-justify-between tw-gap-4">
+      <div className="tw-min-w-0 tw-flex-1">{breadcrumbs}</div>
+      {overflowActions && (
+        <div className="tw-flex tw-shrink-0 tw-items-center tw-gap-2">{overflowActions}</div>
+      )}
+    </div>
+
+    <div className="tw-flex tw-w-full tw-items-start tw-justify-between tw-gap-4">
+      <div className="tw-flex tw-min-w-0 tw-flex-1 tw-flex-col tw-gap-2 tw-pr-2">
+        <div className={titleRowClass}>
+          <h1 className={titleClass}>{title}</h1>
+          {badges && <div className={badgesClass}>{badges}</div>}
+        </div>
+        {description && <p className={descriptionClass}>{description}</p>}
+      </div>
+      {(primaryAction || secondaryAction) && (
+        <div className="tw-flex tw-shrink-0 tw-items-center tw-gap-2">
+          {secondaryAction}
+          {primaryAction}
+        </div>
+      )}
+    </div>
+
+    {headerNav}
+  </header>
+);