@keboola/design 2.0.1 → 2.1.0

package/src/blocks/PageHeader/PageHeaderIndex.tsx

@@ -1,75 +0,0 @@
-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.
-/**
- * Props for `PageHeader.Index`. Index pages have no breadcrumbs and no overflow menu — search and filters
- * belong in `PageToolbar`, not here.
- */
-type PageHeaderIndexProps = Omit<ComponentPropsWithoutRef<'header'>, 'title'> & {
-  title: ReactNode;
-  /** Prose description shown below the title. Mutually exclusive with `metadata` in the pattern; `metadata` wins when both are passed. */
-  description?: ReactNode;
-  /** Count / system summary shown below the title (e.g. "3 buckets and 39 tables"). Wins over `description`. */
-  metadata?: ReactNode;
-  /** Icon-only docs button (`Button argo variant="invisible" icon="book-blank"`). Sits next to `action`. */
-  documentation?: ReactNode;
-  /** Primary "create / add new X" `Button`. Pass `Button argo`. */
-  action?: ReactNode;
-  /** Optional `Tabs` row rendered below the title block. Use only when >1 dataset / section is worth navigating to. */
-  headerNav?: ReactNode;
-};
-
-/**
- * Page header for top-level list / collection pages.
- *
- * **When to use:** the page is a list (Flows, Storage, Jobs, …) with no parent in the same section.
- * Primary action is typically "create / add a new X".
- * **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 `PageToolbar`, not here.
- */
-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

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

package/src/blocks/PageHeader/styles.ts

@@ -1,6 +0,0 @@
-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

@@ -1,94 +0,0 @@
-# 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
-├── PageToolbar              ← search / filter pills (NEVER in header) — separate block
-├── 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>
-  <PageToolbar>{searchAndFilters}</PageToolbar>
-  <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
-  `PageToolbar`.
-
-## 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

@@ -1,146 +0,0 @@
-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';
-
-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`, `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.',
-      },
-    },
-  },
-} 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>
-
-      <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" />
-      </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

@@ -1,139 +0,0 @@
-import type { ComponentPropsWithoutRef, ElementRef, Ref } from 'react';
-
-import { cn } from '../../utils';
-
-/**
- * Props for `PageLayout` root. `maxWidth` constrains the content column —
- * `narrow` (976px) for forms, `default` (1280px) for most pages, `wide` (1600px) for dense detail views,
- * `full` for edge-to-edge layouts.
- */
-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 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>
-);
-
-/**
- * Compound page-chrome block. Provides every kbc-ui page with the same content-column shape:
- * max-width container + vertical rhythm + named slots.
- *
- * **When to use:** every new kbc-ui page. Do not roll your own `<div className="tw-flex tw-flex-col">`
- * chrome. Host `PageHeader.Index` / `PageHeader.Detail` inside `PageLayout.Header` for the structured
- * page-header patterns.
- * **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 `PageToolbar`, never in the header. Form submit bars go in
- * `PageLayout.Footer sticky`.
- *
- * @see RECIPES.md#list-detail — for the index → detail page pattern
- */
-export const PageLayout = Object.assign(Root, {
-  /** Detail-pattern breadcrumb row. Usually composed automatically by `PageHeader.Detail` — slot exists for layouts that don't fit either `PageHeader` variant. */
-  Breadcrumbs,
-  /** Host slot for `PageHeader.Index` / `PageHeader.Detail`, or custom header JSX when neither variant fits. */
-  Header,
-  /** Escape hatch for routing-based tab rows. Use `Tabs` / `TabsContent` core components inside, never a raw `<button>`. */
-  Tabs,
-  /** Main content slot. Lists, cards, tables. */
-  Content,
-  /** Bottom action bar — form submit + cancel. Pass `sticky` for a footer that pins to the viewport. */
-  Footer,
-});

package/src/blocks/PageLayout/index.ts

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