@keboola/design 1.0.0

package/src/components/Timeline/Timeline.stories.tsx

@@ -0,0 +1,246 @@
+import type { ComponentProps } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Alert } from '../Alert';
+import { ButtonInline } from '../Button';
+import { Icon } from '../Icon';
+
+import { Timeline } from './Timeline';
+
+type TimelineProps = ComponentProps<typeof Timeline>;
+type Variant = NonNullable<TimelineProps['variant']>;
+const variants: Variant[] = ['dashed', 'solid'];
+
+/**
+ * Timeline component shows a list of events in chronological order.
+ */
+export default {
+  component: Timeline,
+  args: {
+    variant: 'dashed',
+  },
+  argTypes: {
+    variant: {
+      description: 'Set Variant',
+      type: {
+        name: 'enum',
+        value: variants,
+      },
+    },
+  },
+} satisfies Meta<typeof Timeline>;
+
+type Story = StoryObj<typeof Timeline>;
+
+export const Default: Story = {
+  render: (props) => (
+    <Timeline {...props}>
+      <Timeline.Item>
+        <Timeline.Connector asChild>
+          <time>2025-05-12</time>
+        </Timeline.Connector>
+        <Timeline.Content>First</Timeline.Content>
+      </Timeline.Item>
+
+      <Timeline.Item>
+        <Timeline.Connector asChild>
+          <time>2025-04-08</time>
+        </Timeline.Connector>
+        <Timeline.Content>Second</Timeline.Content>
+      </Timeline.Item>
+
+      <Timeline.Item>
+        <Timeline.Connector>Unknown</Timeline.Connector>
+        <Timeline.Content>Custom Label</Timeline.Content>
+      </Timeline.Item>
+    </Timeline>
+  ),
+};
+
+/**
+ * Connector is a visual element that connects two items in the timeline.
+ * It can have different alignments and variants.
+ */
+export const Connector: Story = {
+  render: (props) => (
+    <Timeline {...props}>
+      <Timeline.Item>
+        <Timeline.Connector align="center" variant="line" />
+        <Timeline.Content>
+          <Alert>Great stuff</Alert>
+        </Timeline.Content>
+      </Timeline.Item>
+
+      <Timeline.Item>
+        <Timeline.Connector align="start" offset={2} variant="line" />
+        <Timeline.Content>
+          <Alert>Connector at the start with offset</Alert>
+        </Timeline.Content>
+      </Timeline.Item>
+
+      <Timeline.Item>
+        <Timeline.Connector align="center" variant="line" />
+        <Timeline.Content className="tw-flex-col tw-gap-2">
+          <Alert>Centered connector</Alert>
+          <Alert>Something else..</Alert>
+        </Timeline.Content>
+      </Timeline.Item>
+    </Timeline>
+  ),
+};
+
+export const Icons: Story = {
+  render: (props) => (
+    <Timeline {...props}>
+      <Timeline.Item>
+        <Timeline.Connector variant="icon">
+          <Icon icon="check" />
+        </Timeline.Connector>
+        <Timeline.Content>Checked</Timeline.Content>
+      </Timeline.Item>
+
+      <Timeline.Item>
+        <Timeline.Connector variant="icon">
+          <Icon icon="dot-circle" />
+        </Timeline.Connector>
+        <Timeline.Content>Dot</Timeline.Content>
+      </Timeline.Item>
+
+      <Timeline.Item>
+        <Timeline.Connector variant="icon">
+          <Icon icon="search" />
+        </Timeline.Connector>
+        <Timeline.Content>Search</Timeline.Content>
+      </Timeline.Item>
+    </Timeline>
+  ),
+};
+
+export const Lines: Story = {
+  render: (props) => (
+    <Timeline {...props}>
+      <Timeline.Item>
+        <Timeline.Connector variant="line" />
+        <Timeline.Content>First</Timeline.Content>
+      </Timeline.Item>
+
+      <Timeline.Item>
+        <Timeline.Connector variant="line" />
+        <Timeline.Content>Second</Timeline.Content>
+      </Timeline.Item>
+
+      <Timeline.Item>
+        <Timeline.Connector variant="line" />
+        <Timeline.Content>Custom Label</Timeline.Content>
+      </Timeline.Item>
+    </Timeline>
+  ),
+};
+
+export const ConnectorAlign: Story = {
+  render: (props) => (
+    <Timeline {...props}>
+      <Timeline.Item>
+        <Timeline.Connector offset={12} variant="line" />
+        <Timeline.Content className="tw-flex-col">
+          <h1>Start align with an offset to center it on the heading.</h1>
+          <Alert>Hello</Alert>
+        </Timeline.Content>
+      </Timeline.Item>
+
+      <Timeline.Item>
+        <Timeline.Connector variant="line" />
+        <Timeline.Content>For pure text, no extra alignment is needed.</Timeline.Content>
+      </Timeline.Item>
+
+      <Timeline.Item>
+        <Timeline.Connector align="center" variant="line" />
+        <Timeline.Content className="tw-flex-col tw-gap-1">
+          <Alert>Hello</Alert>
+          <Alert>Center align of connector, offset is not necessary</Alert>
+          <Alert>Hello</Alert>
+        </Timeline.Content>
+      </Timeline.Item>
+    </Timeline>
+  ),
+};
+
+export const Nested: Story = {
+  render: (props) => (
+    <Timeline {...props}>
+      <Timeline.Item>
+        <Timeline.Connector align="start" asChild variant="label">
+          <time>2025-12-24</time>
+        </Timeline.Connector>
+        <Timeline.Content className="tw-flex-col">
+          <h4>Documentation Query</h4>
+          <p className="tw-text-neutral-400">How to create SQL transformation</p>
+        </Timeline.Content>
+      </Timeline.Item>
+
+      <Timeline.Item>
+        <Timeline.Connector variant="label">2025-12-24</Timeline.Connector>
+        <Timeline.Content>
+          <Timeline variant="solid">
+            <Timeline.Item>
+              <Timeline.Connector variant="icon">
+                <Icon icon="warehouse" />
+              </Timeline.Connector>
+              <Timeline.Content className="tw-gap-2">
+                <h4>Create SQL Transformation</h4>
+              </Timeline.Content>
+            </Timeline.Item>
+
+            <Timeline.Item>
+              <Timeline.Connector variant="line" />
+              <Timeline.Content className="tw-gap-2">
+                <Icon icon="warehouse" className="tw-text-neutral-400" />
+                <div className="tw-flex tw-flex-col">
+                  <h4>Documentation Query</h4>
+                  <div className="tw-flex tw-gap-2">
+                    <ButtonInline variant="link-reverse">Data Source</ButtonInline>
+                    <span className="tw-text-neutral-400">Salesforce</span>
+                  </div>
+                </div>
+              </Timeline.Content>
+            </Timeline.Item>
+            <Timeline.Item>
+              <Timeline.Connector variant="line" />
+              <Timeline.Content className="tw-gap-2">
+                <Icon icon="warehouse" className="tw-text-neutral-400" />
+                <div className="tw-flex tw-flex-col">
+                  <h4>Documentation Query</h4>
+                  <div className="tw-flex tw-gap-2">
+                    <ButtonInline variant="link-reverse">Data Source</ButtonInline>
+                    <span className="tw-text-neutral-400">Salesforce</span>
+                  </div>
+                </div>
+              </Timeline.Content>
+            </Timeline.Item>
+            <Timeline.Item>
+              <Timeline.Connector align="start" variant="line" />
+              <Timeline.Content className="tw-gap-2">
+                <Icon icon="warehouse" className="tw-text-neutral-400" />
+                <div className="tw-flex tw-flex-col">
+                  <h4>Documentation Query</h4>
+                  <div className="tw-flex tw-gap-2">
+                    <ButtonInline variant="link-reverse">Data Source</ButtonInline>
+                    <span className="tw-text-neutral-400">Salesforce</span>
+                  </div>
+                </div>
+              </Timeline.Content>
+            </Timeline.Item>
+          </Timeline>
+        </Timeline.Content>
+      </Timeline.Item>
+
+      <Timeline.Item>
+        <Timeline.Connector variant="label">2025-12-24</Timeline.Connector>
+        <Timeline.Content className="tw-flex-col">
+          <h4>List of Configurations</h4>
+          <p className="tw-text-neutral-400">Extractor Writer</p>
+        </Timeline.Content>
+      </Timeline.Item>
+    </Timeline>
+  ),
+};

package/src/components/Timeline/Timeline.tsx

@@ -0,0 +1,35 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils';
+
+import { TimelineConnector } from './TimelineConnector';
+import { TimelineContent } from './TimelineContent';
+import { TimelineItem } from './TimelineItem';
+
+type Props = ComponentProps<'ul'> & {
+  variant?: 'solid' | 'dashed';
+};
+
+export const Timeline = ({ className, variant = 'dashed', ...rest }: Props) => {
+  return (
+    <ul
+      {...rest}
+      data-variant={variant}
+      className={cn(
+        'tailwindcss-preflight',
+        'tw-overflow-y-hidden',
+        // reset default styling
+        'tw-p-0',
+        'tw-grid',
+        'tw-grid-cols-[auto_1fr]',
+        'tw-group/timeline',
+        'tw-gap-x-4',
+        className,
+      )}
+    />
+  );
+};
+
+Timeline.Item = TimelineItem;
+Timeline.Content = TimelineContent;
+Timeline.Connector = TimelineConnector;

package/src/components/Timeline/TimelineConnector.tsx

@@ -0,0 +1,154 @@
+import type { ComponentProps, CSSProperties } from 'react';
+import { Root } from '@radix-ui/react-slot';
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+
+import { useLastLineHeight } from './useLastLineHeight';
+
+const connectorWrapper = cva(
+  [
+    'tw-grow',
+    'tw-min-h-8',
+    'tw-py-2',
+
+    // layout
+    'tw-flex',
+    'tw-justify-center',
+
+    // CONNECTOR LINE
+    'tw-relative',
+    'before:tw-absolute',
+    'before:tw-self-start',
+
+    // Centered on x-axis
+    'before:tw-left-1/2',
+    'before:tw--translate-x-1/2',
+    'before:tw-w-px',
+    'before:tw-h-full',
+    'before:group-last/timeline-item:tw-h-[--connector-line-height]',
+
+    // Solid line
+    'before:group-data-[variant=solid]/timeline:tw-bg-neutral-200',
+
+    // Dashed line using gradient
+    'before:group-data-[variant=dashed]/timeline:tw-bg-gradient-to-b',
+    'before:group-data-[variant=dashed]/timeline:tw-from-neutral-200',
+    'before:group-data-[variant=dashed]/timeline:tw-from-50%',
+    'before:group-data-[variant=dashed]/timeline:tw-to-transparent',
+    'before:group-data-[variant=dashed]/timeline:tw-to-50%',
+    'before:group-data-[variant=dashed]/timeline:tw-bg-[length:1px_4px]',
+  ],
+  {
+    defaultVariants: {
+      align: 'start',
+    },
+    variants: {
+      align: {
+        start: ['tw-items-start'],
+        center: ['tw-items-center'],
+        end: ['tw-items-end'],
+        baseline: ['tw-items-baseline'],
+      },
+    },
+  },
+);
+
+const connector = cva(
+  [
+    // ensure that it is always above the connector line.
+    'tw-z-10',
+    'tw-relative',
+  ],
+  {
+    defaultVariants: {
+      variant: 'label',
+    },
+    variants: {
+      variant: {
+        none: [],
+        label: [
+          'tw-bg-neutral-100',
+          'tw-text-neutral-300',
+          'tw-rounded',
+          'tw-p-1.5',
+          'tw-text-nowrap',
+          'tw-text-xs',
+        ],
+        icon: ['tw-bg-white', '[&_svg]:tw-text-neutral-300'],
+        line: [
+          'tw-min-w-8',
+          'tw-overflow-hidden',
+          'tw-w-full',
+          // height of the curved corner
+          'tw-h-1',
+
+          // small offset from top and bottom
+          'tw-my-1.5',
+          // positioning
+          'tw-relative',
+          'before:tw-absolute',
+          'before:tw-left-1/2',
+          'before:tw-bottom-0',
+
+          // sizing
+          'before:tw-w-full',
+          'before:tw-h-full',
+
+          // l-shape
+          'before:tw-border-l',
+          'before:tw-border-b',
+          'before:tw-border-neutral-200',
+
+          'before:tw-rounded-bl',
+          // Solid or dashed
+          'before:group-data-[variant=dashed]/timeline:tw-border-dashed',
+          'before:group-data-[variant=solid]/timeline:!tw-border-solid',
+        ],
+      },
+    },
+  },
+);
+
+type Props = { asChild?: boolean; offset?: number } & ComponentProps<'div'> &
+  VariantProps<typeof connectorWrapper> &
+  VariantProps<typeof connector>;
+
+export const TimelineConnector = ({
+  className,
+  children,
+  asChild,
+  variant,
+  align,
+  offset = 0,
+  style,
+  ...rest
+}: Props) => {
+  const Comp = asChild ? Root : 'div';
+  const { setConnector, setWrapper, height } = useLastLineHeight();
+
+  return (
+    <div
+      ref={setWrapper}
+      style={
+        {
+          '--connector-line-height': `${height}px`,
+        } as CSSProperties
+      }
+      className={connectorWrapper({
+        align,
+      })}
+    >
+      <Comp
+        {...rest}
+        ref={setConnector}
+        style={{
+          top: align === 'end' ? -offset : offset,
+          ...style,
+        }}
+        className={connector({ variant, className })}
+      >
+        {children}
+      </Comp>
+    </div>
+  );
+};

package/src/components/Timeline/TimelineContent.tsx

@@ -0,0 +1,18 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils';
+
+type Props = ComponentProps<'div'>;
+
+export const TimelineContent = ({ className, ...rest }: Props) => (
+  <div
+    {...rest}
+    data-slot="timeline-content"
+    className={cn(
+      'tw-flex',
+      // spacing in between timeline items
+      'tw-py-2',
+      className,
+    )}
+  />
+);

package/src/components/Timeline/TimelineItem.tsx

@@ -0,0 +1,14 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils';
+
+type Props = ComponentProps<'li'>;
+
+export const TimelineItem = ({ className, ...rest }: Props) => {
+  return (
+    <li
+      {...rest}
+      className={cn('tw-contents', 'tw-relative', 'tw-group/timeline-item', className)}
+    />
+  );
+};

package/src/components/Timeline/index.ts

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

package/src/components/Timeline/useLastLineHeight.ts

@@ -0,0 +1,36 @@
+import { useEffect, useState } from 'react';
+
+import { useElement } from '../../hooks/useElement';
+
+const CONNECTOR_MARGIN_TOP = 8;
+
+export const useLastLineHeight = () => {
+  const [wrapper, setWrapper] = useElement();
+  const [connector, setConnector] = useElement();
+  const [height, setHeight] = useState(0);
+
+  useEffect(() => {
+    if (wrapper === null) return;
+    if (connector === null) return;
+
+    const updateHeight = () => {
+      const wrapperRect = wrapper.getBoundingClientRect();
+      const connectorRect = connector.getBoundingClientRect();
+      const distance = connectorRect.top - wrapperRect.top - CONNECTOR_MARGIN_TOP;
+      setHeight(distance);
+    };
+
+    // Initial check.
+    const rafId = requestAnimationFrame(updateHeight);
+
+    return () => {
+      cancelAnimationFrame(rafId);
+    };
+  }, [wrapper, connector]);
+
+  return {
+    height,
+    setWrapper,
+    setConnector,
+  };
+};

package/src/components/Toast/Toast.stories.tsx

@@ -0,0 +1,178 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Button } from '../Button';
+
+import type { ToastOptions } from './toast';
+import { toast } from './toast';
+import { Toaster } from './Toaster';
+import { useNotification } from './useNotification';
+
+type Variant = NonNullable<ToastOptions['variant']>;
+type Icon = ToastOptions['icon'];
+type Position = NonNullable<ToastOptions['position']>;
+
+const variants: Variant[] = ['default', 'info', 'success', 'warning', 'error'];
+const icons: Icon[] = [undefined, 'clock', 'bug', 'sparkles'];
+const positions: Position[] = [
+  'bottom-center',
+  'bottom-left',
+  'bottom-right',
+  'top-center',
+  'top-left',
+  'top-right',
+];
+
+const ToastDemo = (args: ToastOptions) => <Button onClick={() => toast(args)}>Render Toast</Button>;
+
+export default {
+  decorators: (Story) => (
+    <>
+      <Story />
+      <Toaster />
+    </>
+  ),
+  args: {
+    variant: 'info',
+    loading: false,
+    icon: undefined,
+    position: 'bottom-center',
+    title: 'Event has been created',
+    description: 'Your event has been successfully created and is now live.',
+  },
+  argTypes: {
+    variant: {
+      options: variants,
+      control: { type: 'radio' },
+    },
+    icon: {
+      control: { type: 'radio' },
+      description:
+        'Custom Icon (overrides default icon based on variant, or spinner if loading is true)',
+      options: icons,
+    },
+    position: {
+      control: { type: 'radio' },
+      options: positions,
+    },
+  },
+  render: ToastDemo,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      // In docs mode, don't use a global Toaster to avoid toasts appearing in all blocks
+      story: {
+        inline: false,
+      },
+    },
+  },
+} satisfies Meta<ToastOptions>;
+
+type Story = StoryObj<ToastOptions>;
+
+export const Default: Story = {};
+
+export const WithAction: Story = {
+  args: {
+    action: {
+      label: 'Copy',
+      onClick: () => alert('Action clicked!'),
+    },
+  },
+};
+
+export const OnlyTitle: Story = {
+  args: {
+    title: 'This is a title-only toast',
+    description: undefined,
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    title: 'Loading...',
+    loading: true,
+  },
+};
+export const CustomIcon: Story = {
+  args: {
+    title: 'Custom clock icon',
+    icon: 'clock',
+  },
+};
+
+export const CustomPosition: Story = {
+  args: {
+    position: 'top-left',
+  },
+};
+
+export const Jsx: Story = {
+  args: {
+    title: (
+      <>
+        Title can include <em>JSX content</em>
+      </>
+    ),
+    description: (
+      <>
+        This toast demonstrates rendering JSX content. You can include <strong>bold text</strong>
+      </>
+    ),
+  },
+};
+
+export const AutoDismiss: Story = {
+  args: {
+    title: 'This toast will automatically dismiss after 3 seconds.',
+    description: undefined,
+    duration: 3000,
+  },
+};
+
+export const LongContent: Story = {
+  args: {
+    title:
+      'This is a longer description that provides more context about what happened. It might contain important information that the user needs to read carefully. The toast component should handle longer content gracefully and wrap it appropriately even when the message is very long and contains multiple sentences with detailed information.',
+    description: undefined,
+  },
+};
+
+export const LongContentWithAction: Story = {
+  args: {
+    title:
+      'This is a very long description that provides extensive context about what happened. It contains important information that the user needs to read carefully. The toast component should handle longer content gracefully and wrap it appropriately while keeping the action button from shrinking.',
+    action: {
+      label: 'View Details',
+      onClick: () => alert('Action clicked!'),
+    },
+  },
+};
+
+const NotificationDemo = () => {
+  useNotification({
+    title: 'This is a notification triggered by useNotification hook',
+    description: 'It will stay visible until dismissed or component unmounts.',
+    action: {
+      label: 'Take Action',
+      onClick: () => alert('Notification action clicked!'),
+    },
+    position: 'top-center',
+  });
+
+  return (
+    <div className="tw-flex tw-flex-col tw-items-center tw-justify-center">
+      <h4>Declarative notification component built on top of sonner/toast.</h4>
+      <p>
+        Use Notification for <strong>persistent</strong>, system-driven messages that require user
+        acknowledgment (e.g., trial expiration warnings, upgrade prompts, billing alerts). The
+        notification stays visible until the user dismisses it or the component unmounts. Use
+        `toast()` for transient feedback after a user action (e.g., "Saved", "Copied", "Deleted")
+        that auto-dismisses after a few seconds.
+      </p>
+    </div>
+  );
+};
+
+export const UseNotification: Story = {
+  render: NotificationDemo,
+};