@keboola/design 1.0.0

package/src/blocks/PageHeader/PageHeaderIndex.tsx

@@ -0,0 +1,56 @@
+import type { ComponentPropsWithoutRef, ElementRef, ReactNode, Ref } from 'react';
+
+import { cn } from '../../utils';
+
+import { descriptionClass, titleClass, titleRowClass } from './styles';
+
+// Index page header — list / collection pages (Flows, Storage, Jobs, …).
+// Pattern: docs/patterns/page-header/index/index-page-header.md
+//   - No breadcrumbs (top-level pages).
+//   - `metadata` wins over `description` (mutually exclusive in pattern).
+//   - At most one primary `action`; pair with the `documentation` icon button.
+type PageHeaderIndexProps = ComponentPropsWithoutRef<'header'> & {
+  title: ReactNode;
+  description?: ReactNode;
+  metadata?: ReactNode;
+  documentation?: ReactNode;
+  action?: ReactNode;
+  headerNav?: ReactNode;
+};
+
+export const PageHeaderIndex = ({
+  ref,
+  className,
+  title,
+  description,
+  metadata,
+  documentation,
+  action,
+  headerNav,
+  ...props
+}: PageHeaderIndexProps & { ref?: Ref<ElementRef<'header'>> }) => {
+  const subtitle = metadata ?? description;
+  return (
+    <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-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>
+          </div>
+          {subtitle && <p className={descriptionClass}>{subtitle}</p>}
+        </div>
+        {(documentation || action) && (
+          <div className="tw-flex tw-shrink-0 tw-items-center tw-gap-2">
+            {documentation}
+            {action}
+          </div>
+        )}
+      </div>
+      {headerNav}
+    </header>
+  );
+};

package/src/blocks/PageHeader/index.ts

@@ -0,0 +1 @@
+export { PageHeader } from './PageHeader';

package/src/blocks/PageHeader/styles.ts

@@ -0,0 +1,6 @@
+export const titleRowClass = 'tw-flex tw-flex-wrap tw-items-center tw-gap-x-3 tw-gap-y-2';
+export const titleClass =
+  'tw-m-0 tw-text-3xl tw-font-semibold tw-leading-9 tw-text-foreground tw-break-words';
+export const badgesClass = 'tw-flex tw-flex-wrap tw-items-center tw-gap-2';
+export const descriptionClass =
+  'tw-m-0 tw-max-w-[800px] tw-break-words tw-text-sm tw-leading-5 tw-text-muted-foreground';

package/src/blocks/PageLayout/AGENTS.md

@@ -0,0 +1,94 @@
+# PageLayout
+
+Compound block that gives every kbc-ui page the same shape. Renders the
+**content column** of the page — the left-rail `Sidebar` lives outside it in
+the app shell.
+
+`PageLayout` is the page **chrome** only: max-width container + vertical
+rhythm + named slots. It deliberately has no opinion about what goes inside
+the slots — for the structured Index / Detail page-header patterns reach for
+the `PageHeader` block.
+
+## When to use
+
+- **Always** reach for `PageLayout` first for a new page. Do not roll your own
+  `<div className="tw-flex tw-flex-col">` chrome.
+- Put a `PageHeader.Index` or `PageHeader.Detail` inside `PageLayout.Header`
+  for the structured page-header patterns. Use the slot with custom JSX only
+  when neither variant fits.
+
+## Anatomy
+
+```text
+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)
+├── PageLayout.Content       ← main slot
+└── PageLayout.Footer        ← bottom action bar (form submit, `sticky` variant)
+```
+
+All slots take any `ReactNode` — no structured props live on the slot itself.
+
+`maxWidth` on the root: `narrow` (976px, forms) / `default` (1280px) /
+`wide` (1600px, dense detail views) / `full`.
+
+## Recommended composition
+
+```tsx
+// Index page
+<PageLayout>
+  <PageLayout.Header>
+    <PageHeader.Index title="Storage" metadata="3 buckets and 39 tables" … />
+  </PageLayout.Header>
+  <PageLayout.Toolbar>{searchAndFilters}</PageLayout.Toolbar>
+  <PageLayout.Content>{list}</PageLayout.Content>
+</PageLayout>
+
+// Detail page — PageHeader.Detail owns the breadcrumbs row internally
+<PageLayout>
+  <PageLayout.Header>
+    <PageHeader.Detail breadcrumbs={…} title="Marketing bucket" … />
+  </PageLayout.Header>
+  <PageLayout.Content>{body}</PageLayout.Content>
+</PageLayout>
+
+// Form
+<PageLayout maxWidth="narrow">
+  <PageLayout.Header>
+    <PageHeader.Detail breadcrumbs={…} title="Create token" … />
+  </PageLayout.Header>
+  <PageLayout.Content>{fields}</PageLayout.Content>
+</PageLayout>
+<PageLayout.Footer sticky>{cancelAndSubmit}</PageLayout.Footer>
+```
+
+## Rules from the design-system patterns
+
+Source of truth: [evviku/design-system-docs page-header patterns](https://github.com/evviku/design-system-docs/tree/main/docs/patterns/page-header).
+Most of these constraints are enforced by `PageHeader` itself; this block just
+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`.
+
+## Component rules
+
+- **Always opt into the `argo` variant** on any `Button` you render in
+  `PageLayout.Footer` or as custom Header JSX.
+- **Never use a raw `<button>`** inside `PageLayout.Tabs`. Use the
+  `Tabs` / `TabsContent` core components from `@keboola/design`.
+
+## Stories
+
+`PageLayout.stories.tsx` focuses on the chrome — for the structured page
+headers see `PageHeader.stories.tsx`.
+
+| Story                      | Purpose                                               |
+| -------------------------- | ----------------------------------------------------- |
+| `Anatomy`                  | Labelled slot positions with placeholders             |
+| `WithTabs`                 | `Tabs` core component nested in the layout            |
+| `FormPageWithStickyFooter` | `maxWidth="narrow"` + sticky footer (Cancel / submit) |

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

@@ -0,0 +1,143 @@
+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 { PageLayout } from './PageLayout';
+
+type Story = StoryObj<typeof PageLayout>;
+
+export default {
+  component: PageLayout,
+  parameters: {
+    layout: 'fullscreen',
+    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.',
+      },
+    },
+  },
+} satisfies Meta<typeof PageLayout>;
+
+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>
+);
+
+// Anatomy — labelled slots with placeholder content so the slot positions are
+// obvious. For real index / detail pages reach for `PageHeader.Index` /
+// `PageHeader.Detail` in the `Header` slot rather than rolling your own.
+export const Anatomy: Story = {
+  render: () => (
+    <PageLayout>
+      <PageLayout.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>
+      </PageLayout.Breadcrumbs>
+
+      <PageLayout.Header>
+        <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>
+
+      <PageLayout.Content>
+        <Placeholder label="EntityList / Table" height="tw-h-96" />
+      </PageLayout.Content>
+    </PageLayout>
+  ),
+};
+
+// With tab navigation — `PageLayout.Tabs` is an escape hatch for routing-based
+// tab rows. For controlled tabs, use the `Tabs` core component (shown here)
+// either inside `PageLayout.Content` or via `PageHeader.*` `headerNav`.
+export const WithTabs: Story = {
+  render: () => (
+    <PageLayout>
+      <PageLayout.Header>
+        <Placeholder label="Header" height="tw-h-20" />
+      </PageLayout.Header>
+
+      <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>
+  ),
+};
+
+// Narrow form with sticky footer — `maxWidth="narrow"` constrains the form
+// column; `Footer sticky` keeps the Cancel / Submit row pinned to the viewport.
+export const FormPageWithStickyFooter: Story = {
+  render: () => (
+    <div className="tw-flex tw-min-h-screen tw-flex-col">
+      <PageLayout maxWidth="narrow">
+        <PageLayout.Breadcrumbs>
+          <Breadcrumb>
+            <Breadcrumb.List>
+              <Breadcrumb.Item>
+                <Breadcrumb.Link href="#">Settings</Breadcrumb.Link>
+              </Breadcrumb.Item>
+              <Breadcrumb.Separator />
+              <Breadcrumb.Item>
+                <Breadcrumb.Page>New API token</Breadcrumb.Page>
+              </Breadcrumb.Item>
+            </Breadcrumb.List>
+          </Breadcrumb>
+        </PageLayout.Breadcrumbs>
+
+        <PageLayout.Header>
+          <Placeholder label="PageHeader.Detail (form title)" height="tw-h-20" />
+        </PageLayout.Header>
+
+        <PageLayout.Content>
+          <div className="tw-flex tw-flex-col tw-gap-4">
+            <Placeholder label="Field: Name" height="tw-h-16" />
+            <Placeholder label="Field: Scope" height="tw-h-16" />
+            <Placeholder label="Field: Expires at" height="tw-h-16" />
+            <Placeholder label="Field: Description" height="tw-h-24" />
+          </div>
+        </PageLayout.Content>
+      </PageLayout>
+
+      <PageLayout.Footer sticky>
+        <Button argo variant="secondary" onClick={() => {}}>
+          Cancel
+        </Button>
+        <Button argo onClick={() => {}}>
+          Create token
+        </Button>
+      </PageLayout.Footer>
+    </div>
+  ),
+};

package/src/blocks/PageLayout/PageLayout.tsx

@@ -0,0 +1,130 @@
+import type { ComponentPropsWithoutRef, ElementRef, Ref } from 'react';
+
+import { cn } from '../../utils';
+
+type RootProps = ComponentPropsWithoutRef<'div'> & {
+  maxWidth?: 'default' | 'narrow' | 'wide' | 'full';
+};
+
+const maxWidthClass = {
+  narrow: 'tw-max-w-[976px]',
+  default: 'tw-max-w-[1280px]',
+  wide: 'tw-max-w-[1600px]',
+  full: 'tw-max-w-full',
+} as const;
+
+const Root = ({
+  ref,
+  className,
+  maxWidth = 'full',
+  children,
+  ...props
+}: RootProps & { ref?: Ref<ElementRef<'div'>> }) => (
+  <div
+    ref={ref}
+    className={cn(
+      'tw-flex tw-flex-col tw-gap-4 tw-w-full tw-mx-auto tw-px-6 tw-py-4',
+      maxWidthClass[maxWidth],
+      className,
+    )}
+    {...props}
+  >
+    {children}
+  </div>
+);
+
+const Breadcrumbs = ({
+  ref,
+  className,
+  children,
+  ...props
+}: ComponentPropsWithoutRef<'div'> & { ref?: Ref<ElementRef<'div'>> }) => (
+  <div ref={ref} className={cn('tw-w-full', className)} {...props}>
+    {children}
+  </div>
+);
+
+const Header = ({
+  ref,
+  className,
+  children,
+  ...props
+}: ComponentPropsWithoutRef<'header'> & { ref?: Ref<ElementRef<'header'>> }) => (
+  <header ref={ref} className={cn('tw-w-full', className)} {...props}>
+    {children}
+  </header>
+);
+
+const Tabs = ({
+  ref,
+  className,
+  children,
+  ...props
+}: ComponentPropsWithoutRef<'div'> & { ref?: Ref<ElementRef<'div'>> }) => (
+  <div
+    ref={ref}
+    className={cn('tw-flex tw-w-full tw-items-center tw-border-b tw-border-border', className)}
+    {...props}
+  >
+    {children}
+  </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,
+  children,
+  ...props
+}: ComponentPropsWithoutRef<'div'> & { ref?: Ref<ElementRef<'div'>> }) => (
+  <div ref={ref} className={cn('tw-flex tw-w-full tw-flex-1 tw-flex-col', className)} {...props}>
+    {children}
+  </div>
+);
+
+type FooterProps = ComponentPropsWithoutRef<'footer'> & {
+  sticky?: boolean;
+};
+
+const Footer = ({
+  ref,
+  className,
+  sticky = false,
+  children,
+  ...props
+}: FooterProps & { ref?: Ref<ElementRef<'footer'>> }) => (
+  <footer
+    ref={ref}
+    className={cn(
+      'tw-flex tw-w-full tw-items-center tw-justify-end tw-gap-3 tw-border-t tw-border-border tw-bg-background tw-px-6 tw-py-4',
+      sticky && 'tw-sticky tw-bottom-0 tw-z-10',
+      className,
+    )}
+    {...props}
+  >
+    {children}
+  </footer>
+);
+
+export const PageLayout = Object.assign(Root, {
+  Breadcrumbs,
+  Header,
+  Tabs,
+  Toolbar,
+  Content,
+  Footer,
+});

package/src/blocks/PageLayout/index.ts

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

package/src/blocks/PasswordInput/PasswordInput.stories.tsx

@@ -0,0 +1,114 @@
+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 { PasswordInput } from './PasswordInput';
+
+type Story = StoryObj<typeof PasswordInput>;
+type PasswordInputProps = ComponentProps<typeof PasswordInput>;
+type State = NonNullable<PasswordInputProps['state']>;
+type Variant = NonNullable<PasswordInputProps['variant']>;
+type Sizing = NonNullable<PasswordInputProps['sizing']>;
+type FocusVariant = NonNullable<PasswordInputProps['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'];
+
+/**
+ * Password input with optional visibility toggle, clear button, and Caps Lock
+ * detection. Works in both controlled and uncontrolled modes.
+ */
+export default {
+  component: PasswordInput,
+  args: {
+    placeholder: 'Password',
+    variant: 'primary',
+    state: 'default',
+    sizing: 'default',
+    focusVariant: 'default',
+    allowClear: false,
+    allowPasswordToggle: true,
+    defaultPasswordVisibility: false,
+    readOnly: false,
+    disabled: false,
+    onValueChange: action('onValueChange'),
+    onValueBlur: action('onValueBlur'),
+  },
+  // Suppress Bitwarden's auto-fill icon while developing in Storybook.
+  render: (args) => <PasswordInput {...args} data-bwignore />,
+  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 PasswordInput>;
+
+export const Basic: Story = {};
+
+const ControlledDemo = (props: ComponentProps<typeof PasswordInput>) => {
+  const [value, setValue] = useState('');
+  const handleOnValueChange = (next: string) => {
+    action('onValueChange')(next);
+    setValue(next);
+  };
+
+  return (
+    <PasswordInput {...props} value={value} onValueChange={handleOnValueChange} data-bwignore />
+  );
+};
+
+export const Controlled: Story = {
+  render: ControlledDemo,
+};
+
+const UncontrolledDemo = (props: ComponentProps<typeof PasswordInput>) => {
+  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}>
+      <PasswordInput
+        {...props}
+        onValueChange={action('onValueChange')}
+        onValueBlur={action('onValueBlur')}
+      />
+      <Button type="submit">Submit</Button>
+    </form>
+  );
+};
+
+export const Uncontrolled: Story = {
+  render: UncontrolledDemo,
+  args: {
+    defaultValue: 'hunter2',
+    allowClear: true,
+    name: 'uncontrolled-password-input',
+  },
+};