@keboola/design 1.0.0

package/README.md

@@ -0,0 +1,83 @@
+# @keboola/design
+
+The Keboola design system — shadcn-aligned, Radix-underneath, FontAwesome icons.
+
+[![npm version](https://img.shields.io/npm/v/@keboola/design.svg)](https://www.npmjs.com/package/@keboola/design)
+[![Storybook](https://img.shields.io/badge/Storybook-live-FF4785)](https://design-hh9143njj-keboola.vercel.app)
+
+📦 **Storybook:** https://design-hh9143njj-keboola.vercel.app
+
+<!-- TODO (UT-3991 follow-up, Wave D-2): replace with canonical production URL once design Storybook hosting is confirmed -->
+
+📖 **Decision tree:** [`AGENTS.md`](./AGENTS.md) — which component to use when.
+🎨 **Branding:** [`../../docs/branding.md`](../../docs/branding.md) (lands with PR #5674).
+
+## Install
+
+```bash
+yarn add @keboola/design @keboola/tailwind-config
+```
+
+## Use
+
+```tsx
+import { Button } from '@keboola/design';
+import '@keboola/design/styles';
+```
+
+---
+
+### Documentation
+
+```
+$ yarn dev
+```
+
+See [Storybook's documentation](https://storybook.js.org/docs/react/writing-stories/introduction) for an introduction to writing stories
+
+### Testing
+
+```
+$ yarn test
+```
+
+Or in UI mode:
+
+```
+$ yarn test:ui
+```
+
+For more information, read [Vitest's documentation](https://vitest.dev/guide/)
+
+### Icons
+
+All icons should use `Icon` component, which is a wrapper around `FontAwesomeIcon`. Available icons are defined in FontAwesome kit.
+
+#### Managing FontAwesome icons
+
+First, go to [FontAwesome kit](https://fontawesome.com/kits/be8bcf7e5e/icons) and log in via [credentials from 1Password](https://start.1password.com/open/i?a=Z6RK6YPRYZESDHSAB2SWYZSSUM&v=3eqzewv3lbgwupxpmehccbswgq&i=6xk57yia2evbo63mdrtkwtluky&h=keboola.1password.com).
+
+**Adding existing FontAwesome icons:**
+
+- In <b>Pro Styles</b> you pick one style (e.g. <b>Solid</b>), search icon name and click on it
+- After you selected all new icons, click on <b>Save Subset</b>
+
+**Adding custom icons:**
+
+- Click on <b>Upload Icons</b> tab
+- Upload your custom SVG icon(s). Make sure the SVG follows FontAwesome's requirements:
+  - Single color (black fills, no strokes)
+  - Square viewBox (e.g., `0 0 512 512`)
+  - Clean, optimized SVG code
+- Give your icon a meaningful name (use kebab-case)
+- Click <b>Upload</b> and then <b>Save Subset</b>
+
+**Finalizing changes:**
+
+- Update the kit NPM package by running:
+
+```shell
+yarn workspace @keboola/design up @awesome.me/kit-be8bcf7e5e
+```
+
+**Note:** When using custom icons in code, you must use the `fak` prefix (e.g., `<Icon icon={['fak', 'custom-icon']} />`)

package/package.json

@@ -0,0 +1,151 @@
+{
+  "name": "@keboola/design",
+  "version": "1.0.0",
+  "description": "Keboola UI platform design system — shadcn-aligned React primitives, Keboola-branded blocks, and the form bindings built on TanStack Form.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./styles": "./src/styles.css",
+    "./mermaid": "./src/blocks/MermaidDiagram/index.ts",
+    "./markdown-editor": "./src/components/MarkdownEditor/index.ts",
+    "./icon-names": "./src/icon-names.ts"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/keboola/ui.git",
+    "directory": "packages/design"
+  },
+  "homepage": "https://github.com/keboola/ui/tree/main/packages/design#readme",
+  "bugs": {
+    "url": "https://github.com/keboola/ui/issues"
+  },
+  "keywords": [
+    "keboola",
+    "design-system",
+    "react",
+    "radix-ui",
+    "tailwindcss",
+    "shadcn",
+    "components"
+  ],
+  "scripts": {
+    "dev": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "build": "yarn build:js && yarn build:css",
+    "build:js": "tsup",
+    "build:css": "tailwindcss --postcss -c tailwind.config.js -i src/styles.css -o dist/styles.css --minify",
+    "test": "vitest run --passWithNoTests --reporter=dot",
+    "lint": "yarn lint:format && yarn lint:oxlint",
+    "lint:fix": "oxlint --fix . && oxfmt",
+    "knip:check": "yarn --cwd ../.. exec knip --workspace packages/design",
+    "knip:fix": "yarn --cwd ../.. exec knip --workspace packages/design --fix-type types,exports,files",
+    "lint:format": "oxfmt --check",
+    "lint:oxlint": "oxlint . --quiet",
+    "type-check": "tsc"
+  },
+  "engines": {
+    "node": "24.x"
+  },
+  "devDependencies": {
+    "@keboola/oxlint-config": "workspace:^",
+    "@keboola/postcss-config": "workspace:^",
+    "@keboola/tsconfig": "workspace:^",
+    "@storybook/addon-docs": "^10.2.19",
+    "@storybook/addon-links": "^10.2.19",
+    "@storybook/react-vite": "^10.2.19",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.2.15",
+    "@vitejs/plugin-react": "^6.0.0",
+    "eslint-plugin-storybook": "^10.3.5",
+    "oxfmt": "^0.44.0",
+    "oxlint": "^1.56.0",
+    "storybook": "^10.2.19",
+    "tailwindcss": "^3.4.17",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.8",
+    "vitest": "^4.1.2"
+  },
+  "dependencies": {
+    "@awesome.me/kit-be8bcf7e5e": "^1.0.217",
+    "@base-ui/react": "1.5.0",
+    "@codemirror/autocomplete": "^6.20.1",
+    "@codemirror/commands": "^6.10.3",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/lang-python": "^6.2.1",
+    "@codemirror/lang-sql": "^6.10.0",
+    "@codemirror/language": "^6.12.3",
+    "@codemirror/legacy-modes": "^6.5.2",
+    "@codemirror/lint": "^6.9.5",
+    "@codemirror/merge": "^6.12.1",
+    "@codemirror/state": "^6.6.0",
+    "@codemirror/view": "^6.41.0",
+    "@fortawesome/fontawesome-svg-core": "^6.7.2",
+    "@fortawesome/react-fontawesome": "^0.2.2",
+    "@keboola/codemirror-lang-sfsql": "workspace:^",
+    "@keboola/codemirror-lang-sql": "workspace:^",
+    "@keboola/tailwind-config": "workspace:^",
+    "@lexical/code": "^0.42.0",
+    "@lexical/link": "^0.42.0",
+    "@lexical/list": "^0.42.0",
+    "@lexical/markdown": "^0.42.0",
+    "@lexical/react": "^0.42.0",
+    "@lexical/rich-text": "^0.42.0",
+    "@lexical/utils": "^0.42.0",
+    "@radix-ui/react-avatar": "^1.1.11",
+    "@radix-ui/react-checkbox": "^1.3.3",
+    "@radix-ui/react-collapsible": "^1.1.0",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-hover-card": "^1.1.15",
+    "@radix-ui/react-label": "^2.1.7",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-progress": "^1.1.7",
+    "@radix-ui/react-radio-group": "^1.3.8",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-separator": "^1.1.7",
+    "@radix-ui/react-slider": "^1.3.6",
+    "@radix-ui/react-slot": "^1.2.3",
+    "@radix-ui/react-switch": "^1.2.6",
+    "@radix-ui/react-tabs": "^1.1.13",
+    "@radix-ui/react-toggle": "^1.1.10",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@tanstack/react-form": "^1.29.1",
+    "@testing-library/jest-dom": "^6.8.0",
+    "@uiw/codemirror-theme-github": "^4.25.2",
+    "@uiw/react-codemirror": "^4.25.7",
+    "beautiful-mermaid": "^1.1.3",
+    "boring-avatars": "^2.0.4",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "diff": "^9.0.0",
+    "lexical": "^0.42.0",
+    "mermaid": "^11.15.0",
+    "node-diff3": "^3.2.0",
+    "react": "^19.2.6",
+    "react-day-picker": "^9.13.0",
+    "react-dom": "^19.2.6",
+    "react-resizable-panels": "^3.0.4",
+    "react-textarea-autosize": "^8.5.9",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^2.6.0"
+  }
+}

package/src/blocks/AIKit/AnswerSummary.stories.tsx

@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { AnswerSummary } from './AnswerSummary';
+
+export default {
+  title: 'AI Kit/AnswerSummary',
+  component: AnswerSummary,
+} satisfies Meta<typeof AnswerSummary>;
+
+type Story = StoryObj<typeof AnswerSummary>;
+
+export const Success: Story = {
+  args: {
+    variant: 'success',
+    items: [
+      { question: 'Which library should we use?', answer: 'date-fns' },
+      { question: 'What features?', answer: 'parsing, formatting' },
+      { question: 'Any custom?', answer: '' },
+    ],
+  },
+};
+
+export const Dismissed: Story = {
+  args: {
+    variant: 'dismissed',
+    items: [
+      { question: 'Which library should we use?', answer: 'User dismissed' },
+      { question: 'What features?', answer: 'User dismissed' },
+    ],
+  },
+};
+
+export const Failed: Story = {
+  args: {
+    variant: 'dismissed',
+    items: [{ question: 'Which library should we use?', answer: 'Tool failed' }],
+  },
+};

package/src/blocks/AIKit/AnswerSummary.tsx

@@ -0,0 +1,63 @@
+import { useState } from 'react';
+
+import { CollapsibleStepHeader } from './CollapsibleStepHeader';
+import { InlineStepDetail } from './InlineStepDetail';
+import { InlineStepLabel } from './InlineStepLabel';
+
+type AnswerItem = {
+  question: string;
+  answer?: string;
+};
+
+type Variant = 'success' | 'dismissed';
+
+type Props = {
+  items: readonly AnswerItem[];
+  variant?: Variant;
+  noAnswerLabel?: string;
+};
+
+const SECTION_LABELS: Record<Variant, string> = {
+  success: 'Answered questions',
+  dismissed: 'Dismissed questions',
+};
+
+export const AnswerSummary = ({
+  items,
+  variant = 'success',
+  noAnswerLabel = 'No answer',
+}: Props) => {
+  const [isExpanded, setIsExpanded] = useState(false);
+  const toggle = () => setIsExpanded((prev) => !prev);
+  const count = items.length;
+
+  return (
+    <section className="tw-mt-4 tw-flex tw-flex-col tw-gap-4" aria-label={SECTION_LABELS[variant]}>
+      <CollapsibleStepHeader
+        isExpanded={isExpanded}
+        onToggle={toggle}
+        variant={variant}
+        label={`${count} question${count !== 1 ? 's' : ''}`}
+      />
+
+      {isExpanded && (
+        <div className="tw-flex tw-flex-col tw-gap-4 tw-pl-5">
+          {items.map(({ question, answer }, index) => (
+            <div key={`${index}-${question}`} className="tw-flex tw-flex-col tw-gap-1">
+              <InlineStepLabel variant={variant}>{question}</InlineStepLabel>
+              <InlineStepDetail>
+                {answer && answer.length > 0 ? answer : noAnswerLabel}
+              </InlineStepDetail>
+            </div>
+          ))}
+        </div>
+      )}
+    </section>
+  );
+};
+
+export type {
+  AnswerItem as AnswerSummaryItem,
+  Props as AnswerSummaryProps,
+  Variant as AnswerSummaryVariant,
+};

package/src/blocks/AIKit/CollapsibleStepHeader.stories.tsx

@@ -0,0 +1,53 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { CollapsibleStepHeader } from './CollapsibleStepHeader';
+
+export default {
+  title: 'AI Kit/CollapsibleStepHeader',
+  component: CollapsibleStepHeader,
+} satisfies Meta<typeof CollapsibleStepHeader>;
+
+type Story = StoryObj<typeof CollapsibleStepHeader>;
+
+export const Success: Story = {
+  render: () => {
+    const [isExpanded, setIsExpanded] = useState(false);
+    return (
+      <CollapsibleStepHeader
+        isExpanded={isExpanded}
+        onToggle={() => setIsExpanded((prev) => !prev)}
+        label="3 questions answered"
+        variant="success"
+      />
+    );
+  },
+};
+
+export const Error: Story = {
+  render: () => {
+    const [isExpanded, setIsExpanded] = useState(false);
+    return (
+      <CollapsibleStepHeader
+        isExpanded={isExpanded}
+        onToggle={() => setIsExpanded((prev) => !prev)}
+        label="Step failed"
+        variant="error"
+      />
+    );
+  },
+};
+
+export const Processing: Story = {
+  render: () => {
+    const [isExpanded, setIsExpanded] = useState(false);
+    return (
+      <CollapsibleStepHeader
+        isExpanded={isExpanded}
+        onToggle={() => setIsExpanded((prev) => !prev)}
+        label="Processing…"
+        variant="processing"
+      />
+    );
+  },
+};

package/src/blocks/AIKit/CollapsibleStepHeader.tsx

@@ -0,0 +1,65 @@
+import type { ReactNode } from 'react';
+
+import { Icon } from '../../components/Icon';
+import { cn } from '../../utils';
+
+type Variant = 'success' | 'error' | 'processing' | 'dismissed';
+
+type Props = {
+  isExpanded: boolean;
+  onToggle: () => void;
+  label: ReactNode;
+  variant?: Variant;
+};
+
+const variantClasses: Record<Variant, string> = {
+  success:
+    'tw-text-secondary-500 focus-visible:tw-outline-secondary-500 not-disabled:hover:tw-text-secondary-600',
+  error:
+    'tw-text-error-500 focus-visible:tw-outline-error-500 not-disabled:hover:tw-text-error-600',
+  processing:
+    'tw-text-secondary-500 focus-visible:tw-outline-secondary-500 not-disabled:hover:tw-text-secondary-600',
+  dismissed:
+    'tw-text-neutral-700 focus-visible:tw-outline-neutral-500 not-disabled:hover:tw-text-neutral-800',
+};
+
+const renderVariantIcon = (variant: Variant) => {
+  if (variant === 'processing') {
+    return <Icon icon="spinner" spin className="tw-size-4" />;
+  }
+  if (variant === 'error') {
+    return <Icon icon="circle-xmark" className="tw-size-4" />;
+  }
+  if (variant === 'dismissed') {
+    return <Icon icon="circle-xmark" className="tw-size-4 tw-text-neutral-500" />;
+  }
+  return <Icon icon="circle-check" className="tw-size-4" />;
+};
+
+export const CollapsibleStepHeader = ({
+  isExpanded,
+  onToggle,
+  label,
+  variant = 'success',
+}: Props) => {
+  return (
+    <button
+      type="button"
+      aria-expanded={isExpanded}
+      onClick={onToggle}
+      className={cn(
+        'tw-flex tw-w-fit tw-items-center tw-gap-3 tw-text-left tw-text-sm tw-font-medium tw-italic tw-transition-colors focus-visible:tw-outline focus-visible:tw-outline-2 focus-visible:tw-outline-offset-2 disabled:tw-opacity-40',
+        variantClasses[variant],
+      )}
+    >
+      <div className="tw-flex tw-items-center tw-gap-2">
+        {renderVariantIcon(variant)}
+        <span>{label}</span>
+      </div>
+      <Icon
+        icon="chevron-down"
+        className={cn('tw-size-3 tw-transition-transform', isExpanded && 'tw-rotate-180')}
+      />
+    </button>
+  );
+};

package/src/blocks/AIKit/InlineStepDetail.stories.tsx

@@ -0,0 +1,25 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { InlineStepDetail } from './InlineStepDetail';
+
+export default {
+  title: 'AI Kit/InlineStepDetail',
+  component: InlineStepDetail,
+} satisfies Meta<typeof InlineStepDetail>;
+
+type Story = StoryObj<typeof InlineStepDetail>;
+
+export const Default: Story = {
+  args: {
+    children:
+      'The user asked for buckets. I got 15 buckets total - 10 input and 5 output. Let me provide a brief summary as per their preference.',
+  },
+};
+
+export const Multiline: Story = {
+  args: {
+    children: `Line one.
+Line two with a few more words.
+Line three.`,
+  },
+};

package/src/blocks/AIKit/InlineStepDetail.tsx

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react';
+
+type Props = {
+  children: ReactNode;
+};
+
+export const InlineStepDetail = ({ children }: Props) => (
+  <div className="tw-ml-2.5 tw-whitespace-pre-wrap tw-border-l tw-border-neutral-200 tw-pl-3 tw-text-xs tw-text-neutral-400">
+    {children}
+  </div>
+);
+
+export type { Props as InlineStepDetailProps };

package/src/blocks/AIKit/InlineStepLabel.stories.tsx

@@ -0,0 +1,37 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { InlineStepLabel } from './InlineStepLabel';
+
+export default {
+  title: 'AI Kit/InlineStepLabel',
+  component: InlineStepLabel,
+  argTypes: {
+    variant: {
+      control: 'radio',
+      options: ['processing', 'success', 'error'],
+    },
+  },
+} satisfies Meta<typeof InlineStepLabel>;
+
+type Story = StoryObj<typeof InlineStepLabel>;
+
+export const Success: Story = {
+  args: {
+    variant: 'success',
+    children: 'Listing buckets',
+  },
+};
+
+export const Processing: Story = {
+  args: {
+    variant: 'processing',
+    children: 'Loading data',
+  },
+};
+
+export const ErrorState: Story = {
+  args: {
+    variant: 'error',
+    children: 'Failed to load buckets',
+  },
+};

package/src/blocks/AIKit/InlineStepLabel.tsx

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react';
+
+import { Icon } from '../../components/Icon';
+
+type Variant = 'processing' | 'success' | 'error' | 'dismissed';
+
+type Props = {
+  variant: Variant;
+  children: ReactNode;
+};
+
+const renderVariantIcon = (variant: Variant) => {
+  if (variant === 'processing') {
+    return <Icon icon="spinner" spin className="tw-size-3 tw-text-neutral-200" />;
+  }
+  if (variant === 'error') {
+    return <Icon icon="circle-xmark" className="tw-size-3 tw-text-error-500" />;
+  }
+  if (variant === 'dismissed') {
+    return <Icon icon="circle-xmark" className="tw-size-3 tw-text-neutral-200" />;
+  }
+  return <Icon icon="circle-check" className="tw-size-3 tw-text-neutral-200" />;
+};
+
+export const InlineStepLabel = ({ variant, children }: Props) => (
+  <div className="tw-flex tw-items-center tw-gap-1">
+    <div className="tw-flex tw-size-5 tw-shrink-0 tw-items-center tw-justify-center">
+      {renderVariantIcon(variant)}
+    </div>
+    <div className="tw-flex tw-flex-wrap tw-items-center tw-gap-x-1.5 tw-gap-y-1 tw-text-sm tw-font-medium tw-italic tw-text-neutral-800">
+      {children}
+    </div>
+  </div>
+);
+
+export type { Variant as InlineStepLabelVariant, Props as InlineStepLabelProps };