@keboola/design 1.2.1 → 1.3.0

package/src/blocks/PageToolbar/PageToolbar.stories.tsx

@@ -0,0 +1,348 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Badge } from '../../components/Badge';
+import { Button } from '../../components/Button';
+import { ButtonGroup } from '../../components/ButtonGroup';
+import { Combobox } from '../../components/Combobox';
+import { Icon } from '../../components/Icon';
+import { PageLayout } from '../PageLayout';
+import { SearchInput } from '../SearchInput';
+
+import { PageToolbar } from './PageToolbar';
+
+type Story = StoryObj<typeof PageToolbar>;
+
+export default {
+  component: PageToolbar,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Two-row toolbar for index pages — `Search` left, `Filters` → `Sort` → `Actions` → `View` right, and an optional `ActiveFilters` row below for filter chips (Standard variant) or filter tokens (Query Builder variant). The block is variant-agnostic: callers compose chips or tokens as plain `ReactNode` children of `ActiveFilters`. See the [design-system pattern](https://github.com/evviku/design-system-docs/blob/main/docs/patterns/toolbar/toolbar.md) for the source spec.',
+      },
+    },
+  },
+} satisfies Meta<typeof PageToolbar>;
+
+const PlaceholderList = () => (
+  <div className="tw-flex tw-h-72 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">
+    EntityList / Table
+  </div>
+);
+
+// Default — Main row only (Search left, Filters + Sort + View right). No active filters,
+// so the Active Filters row is not rendered.
+export const Default: Story = {
+  render: () => {
+    const [query, setQuery] = useState('');
+    const [status, setStatus] = useState<'all' | 'failed' | 'success' | null>(null);
+    const [sort, setSort] = useState<'newest' | 'oldest' | null>('newest');
+
+    return (
+      <PageLayout>
+        <PageToolbar>
+          <PageToolbar.Search>
+            <SearchInput
+              variant="argo"
+              sizing="medium"
+              allowClear
+              placeholder="Search jobs"
+              value={query}
+              onValueChange={setQuery}
+            />
+          </PageToolbar.Search>
+
+          <PageToolbar.Right>
+            <PageToolbar.Filters>
+              <Combobox
+                variant="argo"
+                sizing="medium"
+                allowClear
+                items={['all', 'failed', 'success'] as const}
+                value={status}
+                onValueChange={setStatus}
+                placeholder="Status"
+                className="tw-w-40"
+              />
+            </PageToolbar.Filters>
+            <PageToolbar.Sort>
+              <Combobox
+                variant="argo"
+                sizing="medium"
+                items={['newest', 'oldest'] as const}
+                value={sort}
+                onValueChange={setSort}
+                placeholder="Sort"
+                className="tw-w-32"
+              />
+            </PageToolbar.Sort>
+          </PageToolbar.Right>
+        </PageToolbar>
+
+        <PageLayout.Content>
+          <PlaceholderList />
+        </PageLayout.Content>
+      </PageLayout>
+    );
+  },
+};
+
+// Standard Filters variant — non-editable chips rendered into the Active Filters row,
+// with a Clear action self-aligned to the far right. Uses `Badge` as a stand-in until
+// the dedicated `FilterChip` primitive ships.
+export const WithStandardFilters: Story = {
+  render: () => {
+    type Active = { id: string; label: string; value: string };
+    const [active, setActive] = useState<Active[]>([
+      { id: 'status', label: 'Status', value: 'Failed' },
+      { id: 'owner', label: 'Owner', value: 'John Doe' },
+    ]);
+
+    return (
+      <PageLayout>
+        <PageToolbar>
+          <PageToolbar.Search>
+            <SearchInput variant="argo" sizing="medium" allowClear placeholder="Search jobs" />
+          </PageToolbar.Search>
+
+          <PageToolbar.Right>
+            <PageToolbar.Filters>
+              <Combobox
+                variant="argo"
+                sizing="medium"
+                allowClear
+                items={['Failed', 'Success', 'Running'] as const}
+                placeholder="Status"
+                className="tw-w-36"
+              />
+              <Combobox
+                variant="argo"
+                sizing="medium"
+                allowClear
+                items={['John Doe', 'Jane Doe'] as const}
+                placeholder="Owner"
+                className="tw-w-40"
+              />
+            </PageToolbar.Filters>
+          </PageToolbar.Right>
+
+          {active.length > 0 && (
+            <PageToolbar.ActiveFilters>
+              {active.map((filter) => (
+                <Badge
+                  key={filter.id}
+                  variant="default"
+                  color="gray"
+                  suffix={
+                    <button
+                      type="button"
+                      aria-label={`Remove ${filter.label} filter`}
+                      onClick={() => setActive((prev) => prev.filter((f) => f.id !== filter.id))}
+                      className="tw-flex tw-items-center"
+                    >
+                      <Icon icon="xmark" />
+                    </button>
+                  }
+                >
+                  {filter.label}: {filter.value}
+                </Badge>
+              ))}
+              <PageToolbar.Clear onClick={() => setActive([])} />
+            </PageToolbar.ActiveFilters>
+          )}
+        </PageToolbar>
+
+        <PageLayout.Content>
+          <PlaceholderList />
+        </PageLayout.Content>
+      </PageLayout>
+    );
+  },
+};
+
+// Query Builder variant — editable tokens rendered into the Active Filters row, with
+// `AddFilter` between the tokens and Clear. Uses `Badge` with a `chevron-down` suffix
+// as a stand-in until the dedicated `FilterToken` primitive ships.
+export const WithQueryBuilder: Story = {
+  render: () => {
+    type Token = { id: string; label: string; values: string[] };
+    const [tokens, setTokens] = useState<Token[]>([
+      { id: 'status', label: 'Status', values: ['Failed', 'Success'] },
+      { id: 'owner', label: 'Owner', values: ['John'] },
+    ]);
+
+    return (
+      <PageLayout>
+        <PageToolbar>
+          <PageToolbar.Search>
+            <SearchInput variant="argo" sizing="medium" allowClear placeholder="Search jobs" />
+          </PageToolbar.Search>
+
+          <PageToolbar.Right>
+            <PageToolbar.Filters>
+              <Button argo variant="outline">
+                <Icon icon="sliders" />
+                Filter
+              </Button>
+            </PageToolbar.Filters>
+          </PageToolbar.Right>
+
+          {tokens.length > 0 && (
+            <PageToolbar.ActiveFilters>
+              {tokens.map((token) => (
+                <Badge
+                  key={token.id}
+                  variant="default"
+                  color="gray"
+                  suffix={<Icon icon="chevron-down" />}
+                >
+                  {token.label}: {token.values.join(', ')}
+                </Badge>
+              ))}
+              <PageToolbar.AddFilter onClick={() => {}} />
+              <PageToolbar.Clear onClick={() => setTokens([])} />
+            </PageToolbar.ActiveFilters>
+          )}
+        </PageToolbar>
+
+        <PageLayout.Content>
+          <PlaceholderList />
+        </PageLayout.Content>
+      </PageLayout>
+    );
+  },
+};
+
+// View Controls — list/grid toggle is **always** the last control group on the right.
+// Never render anything after `PageToolbar.View`.
+export const WithViewControls: Story = {
+  render: () => {
+    const [view, setView] = useState<'list' | 'grid'>('list');
+
+    return (
+      <PageLayout>
+        <PageToolbar>
+          <PageToolbar.Search>
+            <SearchInput variant="argo" sizing="medium" allowClear placeholder="Search items" />
+          </PageToolbar.Search>
+
+          <PageToolbar.Right>
+            <PageToolbar.Filters>
+              <Combobox
+                variant="argo"
+                sizing="medium"
+                allowClear
+                items={['Active', 'Archived'] as const}
+                placeholder="Status"
+                className="tw-w-36"
+              />
+            </PageToolbar.Filters>
+            <PageToolbar.Sort>
+              <Combobox
+                variant="argo"
+                sizing="medium"
+                items={['Newest', 'Oldest'] as const}
+                value="Newest"
+                placeholder="Sort"
+                className="tw-w-32"
+              />
+            </PageToolbar.Sort>
+            <PageToolbar.Actions>
+              <Button argo variant="outline">
+                <Icon icon="cloud-arrow-down" />
+                Export
+              </Button>
+            </PageToolbar.Actions>
+            <PageToolbar.View>
+              {/* Temporary view toggle until the dedicated `ToggleGroup` primitive ships.
+                  Two plain outline icon buttons with `aria-pressed` for state; selected
+                  styling lives on the consumer until the primitive lands. */}
+              <ButtonGroup space="extra-small">
+                <Button
+                  argo
+                  variant="outline"
+                  size="icon"
+                  onClick={() => setView('list')}
+                  aria-label="List view"
+                  aria-pressed={view === 'list'}
+                  className={view === 'list' ? 'tw-bg-accent tw-text-accent-foreground' : undefined}
+                >
+                  <Icon icon="table-rows" />
+                </Button>
+                <Button
+                  argo
+                  variant="outline"
+                  size="icon"
+                  onClick={() => setView('grid')}
+                  aria-label="Grid view"
+                  aria-pressed={view === 'grid'}
+                  className={view === 'grid' ? 'tw-bg-accent tw-text-accent-foreground' : undefined}
+                >
+                  <Icon icon="table-cells" />
+                </Button>
+              </ButtonGroup>
+            </PageToolbar.View>
+          </PageToolbar.Right>
+        </PageToolbar>
+
+        <PageLayout.Content>
+          <PlaceholderList />
+        </PageLayout.Content>
+      </PageLayout>
+    );
+  },
+};
+
+// Responsive — at narrow viewport the right cluster wraps below Search, the Active
+// Filters row keeps chips on multiple lines, and Search stays visible. No horizontal
+// scroll. Shown inside a 480px frame to simulate a small breakpoint.
+export const Responsive: Story = {
+  parameters: {
+    layout: 'centered',
+  },
+  render: () => (
+    <div className="tw-w-[480px] tw-rounded tw-border tw-border-border tw-bg-background tw-p-4">
+      <PageToolbar>
+        <PageToolbar.Search>
+          <SearchInput variant="argo" sizing="medium" allowClear placeholder="Search jobs" />
+        </PageToolbar.Search>
+
+        <PageToolbar.Right>
+          <PageToolbar.Filters>
+            <Combobox
+              variant="argo"
+              sizing="medium"
+              allowClear
+              items={['Failed', 'Success'] as const}
+              placeholder="Status"
+              className="tw-w-32"
+            />
+            <Combobox
+              variant="argo"
+              sizing="medium"
+              allowClear
+              items={['John', 'Jane'] as const}
+              placeholder="Owner"
+              className="tw-w-32"
+            />
+          </PageToolbar.Filters>
+        </PageToolbar.Right>
+
+        <PageToolbar.ActiveFilters>
+          <Badge variant="default" color="gray" suffix={<Icon icon="xmark" />}>
+            Status: Failed
+          </Badge>
+          <Badge variant="default" color="gray" suffix={<Icon icon="xmark" />}>
+            Owner: John Doe
+          </Badge>
+          <Badge variant="default" color="gray" suffix={<Icon icon="xmark" />}>
+            Created by: Marketing team
+          </Badge>
+          <PageToolbar.Clear onClick={() => {}} />
+        </PageToolbar.ActiveFilters>
+      </PageToolbar>
+    </div>
+  ),
+};

package/src/blocks/PageToolbar/PageToolbar.tsx

@@ -0,0 +1,119 @@
+import type { ComponentPropsWithoutRef, ElementRef, Ref } from 'react';
+
+import { Button } from '../../components/Button';
+import { Icon } from '../../components/Icon';
+import { cn } from '../../utils';
+
+type DivProps = ComponentPropsWithoutRef<'div'> & { ref?: Ref<ElementRef<'div'>> };
+
+const Root = ({ ref, className, children, ...props }: DivProps) => (
+  <div
+    ref={ref}
+    className={cn('tw-flex tw-flex-wrap tw-items-center tw-gap-3 tw-w-full', className)}
+    {...props}
+  >
+    {children}
+  </div>
+);
+
+const Search = ({ ref, className, children, ...props }: DivProps) => (
+  <div
+    ref={ref}
+    className={cn(
+      'tw-mr-auto tw-flex tw-items-center tw-gap-2 tw-w-full sm:tw-w-auto sm:tw-min-w-64 sm:tw-max-w-md',
+      className,
+    )}
+    {...props}
+  >
+    {children}
+  </div>
+);
+
+const Right = ({ ref, className, children, ...props }: DivProps) => (
+  <div
+    ref={ref}
+    className={cn('tw-flex tw-flex-wrap tw-items-center tw-gap-2', className)}
+    {...props}
+  >
+    {children}
+  </div>
+);
+
+const ControlGroup = ({ ref, className, children, ...props }: DivProps) => (
+  <div ref={ref} className={cn('tw-flex tw-items-center tw-gap-2', className)} {...props}>
+    {children}
+  </div>
+);
+
+const ActiveFilters = ({ ref, className, children, ...props }: DivProps) => (
+  <div
+    ref={ref}
+    className={cn('tw-flex tw-flex-wrap tw-items-center tw-gap-2 tw-basis-full', className)}
+    {...props}
+  >
+    {children}
+  </div>
+);
+
+type ActionProps = ComponentPropsWithoutRef<typeof Button>;
+
+const AddFilter = ({ className, children, ...props }: ActionProps) => (
+  <Button argo variant="invisible" size="small" className={cn('tw-gap-1.5', className)} {...props}>
+    <Icon icon="plus" />
+    {children ?? 'Add filter'}
+  </Button>
+);
+
+const Clear = ({ className, children, ...props }: ActionProps) => (
+  <Button argo variant="invisible" size="small" className={cn('tw-ml-auto', className)} {...props}>
+    {children ?? 'Clear all'}
+  </Button>
+);
+
+/**
+ * Two-row toolbar for index pages — search on the left, filter / sort / utility / view
+ * controls on the right, an optional Active Filters row below for filter chips or tokens.
+ *
+ * **When to use:** every index page that supports search or filtering. Hosts inside
+ * `PageLayout` as the search / filter row — replaces the older bare-`<div>` `PageLayout.Toolbar`.
+ * **When NOT to use:** detail pages, form pages, or anywhere there is no search / filter
+ * surface. For routing-based tab rows reach for `PageLayout.Tabs`.
+ *
+ * **Recommended composition (enforced at the call site):**
+ *
+ * - `Search` sits on the left; the right cluster auto-aligns via flex.
+ * - Right cluster order: `Filters` → `Sort` → `Actions` → `View`. View controls are always
+ *   the final control group — do not render any control after `View`.
+ * - `ActiveFilters` is the second row. Render it only when one or more filters are active.
+ * - `Clear` self-aligns to the far right of `ActiveFilters`.
+ *
+ * The block is variant-agnostic: render filter chips (Standard variant, non-editable) or
+ * tokens (Query Builder variant, editable) into `ActiveFilters` as plain children — do not
+ * mix the two in one toolbar.
+ *
+ * @see https://github.com/evviku/design-system-docs/blob/main/docs/patterns/toolbar/toolbar.md
+ */
+export const PageToolbar = Object.assign(Root, {
+  /** Left slot — typically a `SearchInput`. */
+  Search,
+  /** Right cluster — host the four control groups below in the recommended order. */
+  Right,
+  /** Filter controls (`Combobox`, `Select`, `DatePicker`). */
+  Filters: ControlGroup,
+  /** Sort control. */
+  Sort: ControlGroup,
+  /** Utility actions (Export, Refresh, …). */
+  Actions: ControlGroup,
+  /** View toggle (List / Grid). Always render last in the right cluster. */
+  View: ControlGroup,
+  /**
+   * Active filters row. Render only when one or more filters are active. Pass filter chips
+   * (Standard variant) or tokens (Query Builder variant) as children, optionally followed
+   * by `AddFilter` / `Clear`.
+   */
+  ActiveFilters,
+  /** "+ Add filter" action — typically rendered after the chips/tokens in `ActiveFilters`. */
+  AddFilter,
+  /** "Clear all" action — self-aligns to the far right of `ActiveFilters`. */
+  Clear,
+});

package/src/blocks/PageToolbar/index.ts

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

package/src/blocks/PasswordInput/PasswordInput.tsx

@@ -9,8 +9,8 @@ import type {
   Ref,
 } from 'react';
 
-import { Icon } from '../../components/Icon';
 import { InputGroup } from '../../components/InputGroup';
+import { ArrowBigUpDash, Eye, EyeOff, X } from '../../icons';
 import { createChangeInputEvent, mergeRefs } from '../../utils';
 
 type InputGroupProps = Pick<
@@ -151,27 +151,27 @@ export const PasswordInput = ({
       {(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"
-            />
+            <ArrowBigUpDash className="tw-size-4 tw-text-primary">
+              <title>Caps Lock is on</title>
+            </ArrowBigUpDash>
           )}
           {canClear && (
             <InputGroup.Button
-              icon="xmark"
               aria-label="Clear password"
               onMouseDown={(event) => event.preventDefault()}
               onClick={handleClear}
-            />
+            >
+              <X className="tw-size-4" />
+            </InputGroup.Button>
           )}
           {allowPasswordToggle && (
             <InputGroup.Button
-              icon={isPasswordVisible ? 'eye-slash' : 'eye'}
               aria-label={isPasswordVisible ? 'Hide password' : 'Show password'}
               onMouseDown={(event) => event.preventDefault()}
               onClick={handleTogglePasswordVisibility}
-            />
+            >
+              {isPasswordVisible ? <EyeOff className="tw-size-4" /> : <Eye className="tw-size-4" />}
+            </InputGroup.Button>
           )}
         </InputGroup.Addon>
       )}

package/src/blocks/SearchInput/SearchInput.tsx

@@ -1,8 +1,8 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
 import type { ChangeEventHandler, ComponentProps, ElementRef, FocusEventHandler, Ref } from 'react';
 
-import { Icon } from '../../components/Icon';
 import { InputGroup } from '../../components/InputGroup';
+import { Search, X } from '../../icons';
 import { debounce } from '../../utils';
 
 type InputGroupProps = Pick<
@@ -12,18 +12,43 @@ type InputGroupProps = Pick<
 
 type InputGroupInputProps = Omit<ComponentProps<typeof InputGroup.Input>, 'value' | 'defaultValue'>;
 
+/**
+ * Props for `SearchInput`. `onValueChange` is debounced by default (300ms) so callers can wire it directly
+ * to expensive filter / fetch operations without `useMemo` plumbing. `value={null}` / `value={undefined}`
+ * is treated as "not provided" — the component falls back to `defaultValue` (or, if absent, internal
+ * state initialized to empty). `value={""}` is controlled-empty.
+ */
 type Props = InputGroupProps &
   InputGroupInputProps & {
     value?: string | null;
     defaultValue?: string | null;
+    /** Called with the latest string value after the debounce window (default 300ms). Fires synchronously on clear and when `disableDebounce` is set. For sync echo of every keystroke use `onChange`. */
     onValueChange?: (value: string) => void;
+    /** Called with the string value on blur. */
     onValueBlur?: (value: string) => void;
+    /** Called when the user clicks the clear button. Receives no arguments — the value is reset to "". */
     onClear?: () => void;
+    /** Render the trailing clear (x) button when there's a non-empty value. */
     allowClear?: boolean;
+    /** Bypass the debounce — `onValueChange` fires synchronously on every keystroke. */
     disableDebounce?: boolean;
+    /** Debounce window in ms. Default 300. Ignored when `disableDebounce` is set. */
     debounceDelay?: number;
   };
 
+/**
+ * Debounced search input with a leading magnifying-glass icon and optional clear button.
+ *
+ * **When to use:** the search field inside `PageLayout.Toolbar`, list / table search, combobox-less
+ * free-text filters. `onValueChange` is debounced so callers can wire it directly to fetches without
+ * `useMemo` plumbing.
+ * **When NOT to use:** for a plain string input use `TextInput`; for selecting from a known enumerated
+ * list use `Combobox` (which has its own search built in); for free-form tag entry use `Tagger`.
+ * **Composition:** typically rendered in `PageLayout.Toolbar` next to `MultiCombobox` filter pills. Use
+ * `allowClear` for the canonical x-to-reset affordance.
+ *
+ * @see RECIPES.md#filter-toolbar — for the search + filter chips toolbar pattern
+ */
 export const SearchInput = ({
   ref,
 
@@ -118,7 +143,7 @@ export const SearchInput = ({
       className={className}
     >
       <InputGroup.Addon align="inline-start">
-        <Icon icon="magnifying-glass" className="tw-text-muted-foreground" />
+        <Search className="tw-size-4 tw-text-muted-foreground" />
       </InputGroup.Addon>
 
       <InputGroup.Input
@@ -134,11 +159,12 @@ export const SearchInput = ({
       {canClear && (
         <InputGroup.Addon align="inline-end">
           <InputGroup.Button
-            icon="xmark"
             aria-label="Clear search"
             onMouseDown={(event) => event.preventDefault()}
             onClick={handleClear}
-          />
+          >
+            <X className="tw-size-4" />
+          </InputGroup.Button>
         </InputGroup.Addon>
       )}
     </InputGroup>

package/src/blocks/SearchInputWithNavigation/SearchInputWithNavigation.tsx

@@ -1,8 +1,9 @@
 import type { ComponentProps, KeyboardEvent, Ref } from 'react';
 
-import { Button, ButtonGroup, cn, Icon, Separator, TextInput } from '@keboola/design';
+import { Button, ButtonGroup, cn, Separator, TextInput } from '@keboola/design';
 
 import { keyCodes } from '../../constants/keyCodes';
+import { ChevronDown, ChevronUp, Search } from '../../icons';
 
 type SearchInputWithNavigationProps = {
   currentIndex: number | null;
@@ -51,7 +52,7 @@ export const SearchInputWithNavigation = ({
       placeholder={placeholder}
       onValueChange={onValueChange}
       onClear={onClear}
-      prefix={<Icon className="tw-text-neutral-400" icon="magnifying-glass" />}
+      prefix={<Search className="tw-size-4 tw-text-neutral-400" />}
       focusVariant={focusVariant}
       onKeyDown={handleKeyDown}
       variant={variant}
@@ -72,15 +73,17 @@ export const SearchInputWithNavigation = ({
               size="icon-3xs"
               onClick={onNavigatePrevious}
               disabled={!totalResults}
-              icon="angle-up"
-            />
+            >
+              <ChevronUp className="tw-size-4" />
+            </Button>
             <Button
               variant="inline"
               size="icon-3xs"
               onClick={onNavigateNext}
               disabled={!totalResults}
-              icon="angle-down"
-            />
+            >
+              <ChevronDown className="tw-size-4" />
+            </Button>
           </ButtonGroup>
         </div>
       }

package/src/blocks/SplitButton/SplitButton.stories.tsx

@@ -1,6 +1,8 @@
 import type { ComponentProps } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
+import { Pencil, Trash2 } from '@keboola/design/icons';
+
 import { Modal } from '../../components/Modal';
 
 import { SplitButton } from './SplitButton';
@@ -49,10 +51,11 @@ export const Default: Story = {
       {...args}
       actions={
         <SplitButton.Actions>
-          <SplitButton.Action icon="trash">Action 1</SplitButton.Action>
-          <SplitButton.Action icon="pen">Action 2</SplitButton.Action>
+          <SplitButton.Action>Action 1</SplitButton.Action>
+          <SplitButton.Action>Action 2</SplitButton.Action>
         </SplitButton.Actions>
       }
+      icon={<Pencil className="tw-size-4" />}
     >
       {args.children}
     </SplitButton>
@@ -70,8 +73,8 @@ export const PrimaryButtonAsTrigger: Story = {
   args: {
     actions: (
       <SplitButton.Actions>
-        <SplitButton.Action icon="trash">Action 1</SplitButton.Action>
-        <SplitButton.Action icon="pen">Action 2</SplitButton.Action>
+        <SplitButton.Action icon={<Trash2 />}>Action 1</SplitButton.Action>
+        <SplitButton.Action icon={<Pencil />}>Action 2</SplitButton.Action>
       </SplitButton.Actions>
     ),
   },