create-keboola-app 0.0.0

package/dist/template/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "lint": "oxfmt --check && oxlint .",
+    "lint:fix": "oxlint --fix . && oxfmt",
+    "test": "vitest run",
+    "type-check": "tsc"
+  },
+  "dependencies": {
+    "@keboola/brand-registry": "^1.9.2",
+    "@keboola/design": "^11.0.1",
+    "@tanstack/react-form": "^1.29.1",
+    "@tanstack/react-query": "^5.96.2",
+    "@tanstack/react-router": "^1.120.4",
+    "@tanstack/react-table": "^8.21.3",
+    "@tanstack/router-plugin": "^1.120.4",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "zod": "^4.3.6",
+    "zustand": "^5.0.8"
+  },
+  "devDependencies": {
+    "@keboola/eslint-plugin-design": "^0.4.2",
+    "@keboola/oxlint-config": "^10.0.1",
+    "@keboola/tsconfig": "^0.2.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@tanstack/react-query-devtools": "^5.96.2",
+    "@testing-library/jest-dom": "^6.8.0",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "24.12.0",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "@vitejs/plugin-react": "^6.0.0",
+    "eslint-plugin-better-tailwindcss": "^4.7.0",
+    "jsdom": "^26.1.0",
+    "oxfmt": "^0.57.0",
+    "oxlint": "^1.72.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10"
+  }
+}

package/dist/template/public/favicon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 300 512">
+  <defs>
+    <linearGradient id="kbc" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#61E4FF" />
+      <stop offset="0.5" stop-color="#1F8FFF" />
+      <stop offset="1" stop-color="#7C5CFF" />
+    </linearGradient>
+  </defs>
+  <path fill="url(#kbc)" d="M152 320C79.7 320 24.5 233.9 24.5 124.7C24.5 15.6 70.5 0 152 0s123.6 15.6 123.6 124.7C275.5 233.9 217.7 320 152 320zm-8.7-50.5c0-11.2-9.5-20.3-21.2-20.3s-21.2 9.1-21.2 20.3c0 11.2 9.5 20.3 21.2 20.3s21.2-9.1 21.2-20.3zm55.7 0c0-11.2-9.5-20.3-21.2-20.3s-21.2 9.1-21.2 20.3c0 11.2 9.5 20.3 21.2 20.3s21.2-9.1 21.2-20.3zm68.9 115.1c10.2 9.3 20.2 20.5 29 35c5.9 9.7 2.6 22.1-7.5 27.8c-3.4 1.9-7.1 2.8-10.7 2.8c-7.2 0-14.3-3.6-18.3-10c-6.8-11.1-13.8-18.9-21.7-26.1c-7.3-6.7-15.6-12.7-24.9-19.5c-.7-.5-1.4-1-2.1-1.5c-5-3.6-10-6.8-14.9-9.4c.6 1 1.2 2.1 1.8 3.2c14.4 26.4 29.2 63.1 29.2 104.9c0 11.2-9.5 20.3-21.2 20.3c-11.7 0-21.2-9.1-21.2-20.3c.1-31.8-11.6-62.3-23.8-84.9c-4-7.4-8-13.9-11.6-19.3c-3.4 5.2-7.2 11.3-11 18.3c-12.5 22.7-24.5 53.8-24.4 86c0 11.2-9.5 20.3-21.2 20.3s-21.2-9.1-21.2-20.3c.1-41.8 14.9-78.4 29.2-104.9c.6-1.1 1.2-2.1 1.8-3.2c-5 2.7-9.9 5.8-14.9 9.4c-.6 .5-1.3 .9-1.9 1.4c-9.5 6.9-17.8 12.9-25.1 19.7c-7.9 7.2-14.9 15.1-21.7 26.1c-5.9 9.7-18.9 12.9-29 7.2C.5 441.8-2.9 429.3 3.1 419.7c8.9-14.4 18.8-25.7 29-35c9.2-8.4 18.5-15.1 27.6-21.7c1-.7 2-1.4 3-2.2c4.7-3.5 9.6-6.7 14.6-9.6c-5-2.9-9.8-6.1-14.6-9.6C39.8 325 19.9 302.5 3.1 275.1c-5.9-9.7-2.6-22.1 7.5-27.8c10.1-5.7 23.1-2.5 29 7.2c14.6 23.7 31.1 42 48.7 54.9c18.9 13.7 37.4 20.5 56.5 21.5c1.7-.1 3.5-.1 5.2-.1c1.8 0 3.5 .1 5.2 .1c0 0 0 0 0 0c19.1-1.1 37.6-7.9 56.5-21.5c17.6-12.8 34.2-31.2 48.7-54.9c6-9.7 18.9-12.9 29-7.2c10.1 5.7 13.4 18.1 7.5 27.8c-16.8 27.4-36.7 49.9-59.6 66.6c-4.7 3.5-9.6 6.7-14.5 9.6c4.9 2.9 9.8 6.1 14.5 9.6c.9 .7 1.8 1.3 2.7 2c9.2 6.7 18.5 13.5 27.9 22z" />
+</svg>

package/dist/template/src/components/AppChrome.tsx

@@ -0,0 +1,201 @@
+import type { ReactNode } from 'react';
+import { Link, useRouterState } from '@tanstack/react-router';
+
+import { AppShell, BrandLogo, Button, Navbar, Sidebar, SidebarProvider } from '@keboola/design';
+
+import { isActive, NAV } from '../nav';
+import { useAppStore } from '../store';
+
+// #region block:assistant
+import { AssistantPanel } from './AssistantPanel';
+import { AssistantToggle } from './AssistantToggle';
+// #endregion block:assistant
+import { ColorModeToggle } from './ColorModeToggle';
+import { SidebarModeMenu } from './SidebarModeMenu';
+
+// Chrome is composed inline (not a shared package) so the AppShell/Navbar/Sidebar
+// wiring is legible in this exemplar. The Navbar composition follows kbc-ui's
+// AppSiteHeader — Header (brand) / Content (primary nav) / Footer (actions).
+// The rail's destinations and the active-match rule live in `src/nav.ts`.
+export function AppChrome({ children }: { children: ReactNode }) {
+  const pathname = useRouterState({ select: (s) => s.location.pathname });
+  const helpVisible = useAppStore((s) => s.helpVisible);
+  const toggleHelp = useAppStore((s) => s.toggleHelp);
+  // #region block:assistant
+  const fullscreen = useAppStore((s) => s.fullscreen);
+  // #endregion block:assistant
+  const sidebarMode = useAppStore((s) => s.sidebarMode);
+  const setSidebarMode = useAppStore((s) => s.setSidebarMode);
+
+  return (
+    <SidebarProvider
+      // Left rail — app navigation.
+      // - Controlled: the mode is a persisted user preference, and the store is its
+      //   single owner. `SidebarModeMenu` in the rail's footer writes it.
+      leftMode={sidebarMode}
+      onLeftModeChange={setSidebarMode}
+      leftVariant="inset"
+      // `icon` collapse keeps every destination reachable; `off-canvas` would hide them
+      // all. It is also what `expand-on-hover` collapses to between hovers.
+      leftCollapsible="icon"
+      // #region block:assistant
+      // Right rail — the assistant. `rightVariant` is required: a `Sidebar` whose variant
+      // is `none` (the provider's default) renders NOTHING, silently, so configuring only
+      // the left side makes the assistant disappear with no error. Mirrors kbc-ui's Kai
+      // rail, which uses the same pair.
+      rightVariant="sided-floating"
+      rightCollapsible="off-canvas"
+      // Closed until asked for. The assistant being *available* on every route is
+      // the point; holding ~30% of the viewport open on a transcript nobody has
+      // started is not. The Navbar's AssistantToggle opens it (and badges unread
+      // replies seeded from the page's prompt while it's shut).
+      defaultRightMode="collapsed"
+      // Matches kbc-ui's Kai rail. The provider's default is narrower than a chat
+      // transcript wants — message bubbles wrap after a few words at that width.
+      rightWidth={384}
+      // #endregion block:assistant
+    >
+      {/* `headerSpan="full"` puts the header above both rails so the brand mark aligns to
+          the viewport's left edge — the geometry kbc-ui uses. Without it the left rail
+          owns the top-left corner and the bar starts beside it. */}
+      <AppShell headerSpan="full">
+        {/* `flush` drops the slot's padding, background AND bottom border, so the Navbar
+            renders edge to edge. The border is restated here.
+            - Both rails below carry a hairline; without a matching edge under the header
+              those lines start mid-air instead of closing a frame.
+            - `sidebar-border`, not `border`: the two meet at the corners, and `border`
+              is 4 units lighter. */}
+        <AppShell.Header flush className="tw:border-b tw:border-sidebar-border">
+          {/* `flex-1` makes the bar fill the header — as a flex item it would otherwise
+              shrink to its content width. */}
+          <Navbar bordered className="tw:flex-1">
+            {/* Extra left gutter, set here rather than on `Navbar`: the bar's own
+                `pl-2` comes from a cva, which concatenates instead of tailwind-merging,
+                so a competing `pl-*` there would be settled by cascade order. This slot
+                merges with `cn`. The DS default is tuned for the header sitting beside
+                the rail; with `headerSpan="full"` the logo would otherwise hug the
+                viewport edge instead of lining up with the rail's icons below it.
+                `pl-2.5` on top of the bar's `pl-2` puts the logo at 18px — the same
+                x as the rail's icons, measured rather than guessed. */}
+            <Navbar.Header className="tw:pl-2.5">
+              <Link to="/" aria-label="Home" className="tw:flex tw:items-center">
+                <BrandLogo className="tw:h-6" />
+              </Link>
+            </Navbar.Header>
+
+            {/* Navbar.Content is the flexible middle band: it carries `flex-1` inside the
+                bar, so it is what pushes Navbar.Footer out to the right edge. */}
+            <Navbar.Content>
+              <Navbar.Menu marker="forward-slash">
+                <Navbar.MenuItem>
+                  <Navbar.MenuButton asChild>
+                    <Link to="/">Boilerplate</Link>
+                  </Navbar.MenuButton>
+                </Navbar.MenuItem>
+              </Navbar.Menu>
+            </Navbar.Content>
+
+            <Navbar.Footer>
+              <Button
+                variant="invisible"
+                size="small"
+                onClick={toggleHelp}
+                aria-pressed={helpVisible}
+              >
+                {helpVisible ? 'Hide help' : 'Show help'}
+              </Button>
+              {/* #region block:assistant */}
+              <AssistantToggle />
+              {/* #endregion block:assistant */}
+              <ColorModeToggle />
+            </Navbar.Footer>
+          </Navbar>
+        </AppShell.Header>
+
+        <AppShell.Sidebar>
+          {/* Elevation while `expand-on-hover` is hovered open. That mode widens the rail
+              without widening the column it occupies, so the expanded rail overlays the
+              page, and `inset`'s 1px `border-r` does not read as "above".
+
+              App-scoped rather than a `Sidebar` variant rule: kbc-ui runs this mode by
+              default and paints its own corner over the rail's right edge with tuned
+              `::before` / `::after` wedges, so a shadow from the design side would land
+              on that seam unreviewed. Promote it once that composition has been looked
+              at in a browser. */}
+          <Sidebar
+            side="left"
+            className="tw:group-data-[mode=expand-on-hover]/sidebar:group-data-[state=expanded]/sidebar:[&>[data-slot=sidebar]]:shadow-lift"
+          >
+            <Sidebar.Content>
+              {/* AppShell.Sidebar and Sidebar are plain divs, so without this the rail's
+                  links sit outside any landmark — axe flags the content as unreachable by
+                  landmark navigation. Labelled distinctly from the Navbar's "Main
+                  navigation" so the two are tellable apart in a landmark list. */}
+              <nav aria-label="Sections">
+                <Sidebar.Menu>
+                  {NAV.map((item) => (
+                    <Sidebar.MenuItem key={item.to}>
+                      {/* The slot renders an <a>, so the active state is `aria-current="page"`
+                        — `aria-selected` is not a supported attribute on a link. Both get
+                        the same active styling from Sidebar.MenuButton. */}
+                      <Sidebar.MenuButton
+                        asChild
+                        tooltip={item.label}
+                        aria-current={isActive(pathname, item.to) ? 'page' : undefined}
+                      >
+                        <Link to={item.to}>
+                          <Sidebar.MenuIcon>
+                            <item.icon />
+                          </Sidebar.MenuIcon>
+                          {item.label}
+                        </Link>
+                      </Sidebar.MenuButton>
+                    </Sidebar.MenuItem>
+                  ))}
+                </Sidebar.Menu>
+              </nav>
+            </Sidebar.Content>
+
+            {/* Footer, not Content: `Sidebar.Content` is the scroll container, so a
+                control inside it scrolls away with the nav. The footer is pinned. */}
+            <Sidebar.Footer>
+              <Sidebar.Menu>
+                <SidebarModeMenu />
+              </Sidebar.Menu>
+            </Sidebar.Footer>
+          </Sidebar>
+        </AppShell.Sidebar>
+
+        <AppShell.Main>{children}</AppShell.Main>
+        {/* #region block:assistant */}
+        {/* The assistant is chrome, not a page feature: it rides every route. In normal
+            use it is the right rail; fullscreen adds it as a sibling overlay after
+            AppShell (it renders its own `tw:fixed tw:inset-0 tw:z-50`) instead of
+            replacing the rail, so exiting fullscreen returns to the page underneath.
+            Render exactly one instance per mode — the rail is omitted from the Aside
+            slot while fullscreen, so the two never appear at once. */}
+        {!fullscreen && (
+          // The right rail is a `Sidebar`, not a bare div: it brings the width, border,
+          // scroll container and a drag-to-resize handle, so the panel doesn't reimplement
+          // them. `flush` stops the slot painting a second surface underneath it. Same
+          // composition kbc-ui uses for its Kai rail.
+          // The parked `off-canvas` rail used to need `overflow-x-clip` here. The
+          // design system now clips this slot itself while the rail is collapsed
+          // (see `styles.css`), which an unconditional class could not do safely:
+          // a filled rail widens past the slot and would be cropped. The two are
+          // therefore coupled — reverting that rule alone brings the horizontal
+          // scroll back here, so restore this class if you ever do.
+          <AppShell.Aside flush>
+            <Sidebar side="right" container resizable>
+              <AssistantPanel />
+            </Sidebar>
+          </AppShell.Aside>
+        )}
+        {/* #endregion block:assistant */}
+      </AppShell>
+      {/* #region block:assistant */}
+      {fullscreen && <AssistantPanel />}
+      {/* #endregion block:assistant */}
+    </SidebarProvider>
+  );
+}

package/dist/template/src/components/AssistantPanel.test.tsx

@@ -0,0 +1,65 @@
+import { screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { renderWithTheme } from '@keboola/design/testing';
+
+import { useAppStore } from '../store';
+
+import { AssistantPanel } from './AssistantPanel';
+
+// `renderWithTheme`, not a bare `render`: the panel's PromptInput submit button is
+// wrapped in a `Tooltip`, which throws outside a `TooltipProvider`. The app gets one
+// from `ThemeProvider` in main.tsx, so rendering bare here tests a tree the app
+// never has — and it fails only once a prior test has opened a tooltip.
+const render = (ui: Parameters<typeof renderWithTheme>[0]) => renderWithTheme(ui);
+
+describe('AssistantPanel', () => {
+  beforeEach(() => {
+    useAppStore.setState({ messages: [], fullscreen: false });
+  });
+
+  it('sends a prompt and renders the reply as Markdown', async () => {
+    const user = userEvent.setup();
+    render(<AssistantPanel />);
+
+    const form = screen.getByTestId('prompt-input');
+    await user.type(within(form).getByRole('textbox'), 'where do credits go?');
+    await user.click(within(form).getByRole('button'));
+
+    // The reply echoes the question back as a bold heading, so the raw string
+    // appears twice — the user's own turn is the one that is *not* emphasised.
+    const turns = screen.getAllByText('where do credits go?');
+    expect(turns.some((el) => el.tagName !== 'STRONG')).toBe(true);
+
+    // Markdown, not a plain string: the reply's table renders as a real table.
+    expect(screen.getByText('Database extractor')).toBeInTheDocument();
+    expect(screen.getByRole('table')).toBeInTheDocument();
+  });
+
+  it('leaves the user turn as plain text', async () => {
+    const user = userEvent.setup();
+    render(<AssistantPanel />);
+
+    const form = screen.getByTestId('prompt-input');
+    // Markdown syntax a user typed must survive verbatim rather than being
+    // rendered — only assistant turns go through the Markdown renderer.
+    await user.type(within(form).getByRole('textbox'), '**not bold**');
+    await user.click(within(form).getByRole('button'));
+
+    expect(screen.getByText('**not bold**')).toBeInTheDocument();
+  });
+
+  it('toggles fullscreen when the header control is clicked', async () => {
+    const user = userEvent.setup();
+    render(<AssistantPanel />);
+
+    expect(useAppStore.getState().fullscreen).toBe(false);
+
+    await user.click(screen.getByRole('button', { name: /expand to fullscreen/i }));
+    expect(useAppStore.getState().fullscreen).toBe(true);
+
+    await user.click(screen.getByRole('button', { name: /exit fullscreen/i }));
+    expect(useAppStore.getState().fullscreen).toBe(false);
+  });
+});

package/dist/template/src/components/AssistantPanel.tsx

@@ -0,0 +1,96 @@
+import { useState } from 'react';
+
+import { Button, EmptyState, Markdown, MessageBubble, PromptInput } from '@keboola/design';
+import { Expand, MessagesSquare, Minimize2 } from '@keboola/design/icons';
+
+import { useAppStore } from '../store';
+
+export function AssistantPanel() {
+  const messages = useAppStore((s) => s.messages);
+  const send = useAppStore((s) => s.send);
+  const fullscreen = useAppStore((s) => s.fullscreen);
+  const toggleFullscreen = useAppStore((s) => s.toggleFullscreen);
+
+  const [value, setValue] = useState('');
+
+  const handleSend = (text: string) => {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+    send(trimmed);
+    setValue('');
+  };
+
+  return (
+    <div
+      data-assistant-panel
+      className={
+        fullscreen
+          ? 'tw:fixed tw:inset-0 tw:z-50 tw:flex tw:flex-col tw:bg-background'
+          : // Rail mode paints no background of its own — the host `Sidebar` supplies
+            // `bg-sidebar`. Fullscreen has no Sidebar under it, so there the panel *is*
+            // the page and carries `bg-background` itself.
+            'tw:flex tw:h-full tw:flex-col'
+      }
+    >
+      <div className="tw:flex tw:items-center tw:justify-between tw:border-b tw:border-border tw:p-3">
+        {/* A heading, not a span.
+            - It labels the rail as a region.
+            - It is the h2 between the page's h1 and the empty state's h3
+              (`EmptyState.Title` is a hardcoded h3); without it the order skips a level. */}
+        {/* eslint-disable-next-line design/no-raw-heading-on-page -- not a page heading:
+            it labels the assistant rail, a complementary region, so `PageHeader.Index` /
+            `.Detail` is the wrong component. The rule sees one file's JSX and so cannot
+            tell that AppChrome renders this inside AppShell.Aside's `<aside>` landmark. */}
+        <h2 className="tw:m-0 tw:text-sm tw:font-semibold tw:text-foreground">Assistant</h2>
+        <Button variant="invisible" size="icon-sm" onClick={toggleFullscreen}>
+          {fullscreen ? (
+            <>
+              <Minimize2 className="tw:size-4" />
+              <span className="tw:sr-only">Exit fullscreen</span>
+            </>
+          ) : (
+            <>
+              <Expand className="tw:size-4" />
+              <span className="tw:sr-only">Expand to fullscreen</span>
+            </>
+          )}
+        </Button>
+      </div>
+
+      <div className="tw:flex tw:flex-1 tw:flex-col tw:gap-4 tw:overflow-y-auto tw:p-4">
+        {messages.length === 0 ? (
+          // A conversation panel opens empty far more often than not, so the empty state
+          // is the first thing most users see — without it the rail reads as broken.
+          <EmptyState className="tw:my-auto">
+            <EmptyState.Icon>
+              <MessagesSquare className="tw:size-6" />
+            </EmptyState.Icon>
+            <EmptyState.Title>Ask about this page</EmptyState.Title>
+            <EmptyState.Description>
+              Select any passage in the document, or just start typing below.
+            </EmptyState.Description>
+          </EmptyState>
+        ) : (
+          messages.map((message) => (
+            <MessageBubble key={message.id} variant={message.role}>
+              {/* Assistant replies are Markdown; `Markdown` renders tables, code and
+                  ```mermaid fences (lazy-loading the mermaid runtime itself). User
+                  turns stay plain text — running someone's own input through a
+                  Markdown renderer would reformat what they typed. */}
+              {message.role === 'assistant' ? <Markdown>{message.text}</Markdown> : message.text}
+            </MessageBubble>
+          ))
+        )}
+      </div>
+
+      <div className="tw:p-3">
+        <PromptInput
+          value={value}
+          onValueChange={setValue}
+          onSend={handleSend}
+          placeholder="Send a message..."
+        />
+      </div>
+    </div>
+  );
+}

package/dist/template/src/components/AssistantToggle.tsx

@@ -0,0 +1,37 @@
+import { Button, useSidebar } from '@keboola/design';
+import { MessagesSquare } from '@keboola/design/icons';
+
+import { useAppStore } from '../store';
+
+/**
+ * Opens and closes the assistant rail.
+ *
+ * Its own component because `useSidebar` reads the context that `AppChrome`
+ * itself renders — a hook call in `AppChrome`'s body would sit above the
+ * provider and throw.
+ */
+export function AssistantToggle() {
+  const { state, toggle } = useSidebar('right');
+  const unread = useAppStore((s) => s.messages.length);
+  const isOpen = state === 'expanded';
+
+  return (
+    <Button
+      variant="invisible"
+      size="small"
+      onClick={toggle}
+      aria-pressed={isOpen}
+      aria-label={isOpen ? 'Close the assistant' : 'Open the assistant'}
+    >
+      <MessagesSquare className="tw:size-4" />
+      Assistant
+      {/* The rail is closed by default, so a reply arriving from the page's prompt
+          would otherwise land somewhere the user can't see. */}
+      {!isOpen && unread > 0 && (
+        <span className="tw:ml-1 tw:rounded-full tw:bg-primary tw:px-1.5 tw:text-xs tw:text-primary-foreground tw:tabular-nums">
+          {unread}
+        </span>
+      )}
+    </Button>
+  );
+}

package/dist/template/src/components/ColorModeToggle.tsx

@@ -0,0 +1,15 @@
+import { ColorModeSwitch, useTheme } from '@keboola/design';
+
+/**
+ * Light / dark / system control.
+ *
+ * `ColorModeSwitch` is controlled, and the scheme lives on `ThemeProvider` —
+ * `useTheme` is the seam between them. Setting `data-theme` by hand instead
+ * would flip the stylesheet's own tokens but not the brand's per-scheme values,
+ * so the page would end up half-converted.
+ */
+export function ColorModeToggle() {
+  const { scheme, setScheme } = useTheme();
+
+  return <ColorModeSwitch value={scheme} onValueChange={setScheme} />;
+}

package/dist/template/src/components/HomePrompt.tsx

@@ -0,0 +1,35 @@
+import { useState } from 'react';
+
+import { PromptInput } from '@keboola/design';
+
+import { useAppStore } from '../store';
+
+/**
+ * The page's own way into the assistant.
+ *
+ * - Writes to the transcript the rail renders, so sending here is a handoff: the answer shows
+ *   up in the rail, never inline. Two entry points, one conversation.
+ * - `inline` is a single-row composer that reads as one control on the page. The `default`
+ *   variant is a multi-row box sized for a dedicated chat surface — which the rail already is.
+ */
+export function HomePrompt() {
+  const send = useAppStore((s) => s.send);
+  const [value, setValue] = useState('');
+
+  const handleSend = (text: string) => {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+    send(trimmed);
+    setValue('');
+  };
+
+  return (
+    <PromptInput
+      variant="inline"
+      value={value}
+      onValueChange={setValue}
+      onSend={handleSend}
+      placeholder="Ask about this page…"
+    />
+  );
+}

package/dist/template/src/components/KpiCard.test.tsx

@@ -0,0 +1,20 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { KpiCard } from './KpiCard';
+
+describe('KpiCard', () => {
+  it('shows label, value and a positive signed delta', () => {
+    render(<KpiCard label="MRR" value="$12.4k" deltaPct={4.2} />);
+
+    expect(screen.getByText('MRR')).toBeInTheDocument();
+    expect(screen.getByText('$12.4k')).toBeInTheDocument();
+    expect(screen.getByText('+4.2%')).toBeInTheDocument();
+  });
+
+  it('shows a negative signed delta', () => {
+    render(<KpiCard label="Churn" value="2.1%" deltaPct={-1.3} />);
+
+    expect(screen.getByText('-1.3%')).toBeInTheDocument();
+  });
+});

package/dist/template/src/components/KpiCard.tsx

@@ -0,0 +1,24 @@
+import { Card } from '@keboola/design';
+
+type KpiCardProps = {
+  label: string;
+  value: string;
+  deltaPct?: number;
+};
+
+export function KpiCard({ label, value, deltaPct }: KpiCardProps) {
+  const delta = deltaPct === undefined ? null : `${deltaPct >= 0 ? '+' : ''}${deltaPct}%`;
+  const deltaClass = (deltaPct ?? 0) >= 0 ? 'tw:text-success' : 'tw:text-destructive';
+
+  return (
+    <Card>
+      <p className="tw:text-sm tw:text-muted-foreground">{label}</p>
+      <p className="tw:mt-1 tw:text-2xl tw:font-semibold tw:text-foreground tw:tabular-nums">
+        {value}
+      </p>
+      {delta !== null && (
+        <p className={`tw:mt-1 tw:text-sm tw:tabular-nums ${deltaClass}`}>{delta}</p>
+      )}
+    </Card>
+  );
+}

package/dist/template/src/components/SelectionFloater.test.tsx

@@ -0,0 +1,73 @@
+import { useRef } from 'react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { SelectionFloater } from './SelectionFloater';
+
+function Harness({ onExplain }: { onExplain: (text: string) => void }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  return (
+    <div>
+      <div ref={containerRef} data-testid="content">
+        Quarterly revenue rose 12%.
+      </div>
+      <div data-assistant-panel data-testid="panel">
+        Chat message text.
+      </div>
+      <SelectionFloater containerRef={containerRef} onExplain={onExplain} />
+    </div>
+  );
+}
+
+const selectText = (node: Node, start: number, end: number) => {
+  const range = document.createRange();
+  range.setStart(node, start);
+  range.setEnd(node, end);
+  const sel = window.getSelection()!;
+  sel.removeAllRanges();
+  sel.addRange(range);
+  fireEvent.mouseUp(document);
+};
+
+describe('SelectionFloater', () => {
+  it('surfaces Explain with Kai for a selection inside the container and reports the text', () => {
+    const onExplain = vi.fn();
+    render(<Harness onExplain={onExplain} />);
+
+    selectText(screen.getByTestId('content').firstChild!, 0, 17); // "Quarterly revenue"
+
+    const button = screen.getByRole('button', { name: /explain with kai/i });
+    fireEvent.click(button);
+
+    expect(onExplain).toHaveBeenCalledWith('Quarterly revenue');
+  });
+
+  it('ignores a selection inside the assistant panel', () => {
+    const onExplain = vi.fn();
+    render(<Harness onExplain={onExplain} />);
+
+    selectText(screen.getByTestId('panel').firstChild!, 0, 4); // "Chat"
+
+    expect(screen.queryByRole('button', { name: /explain with kai/i })).not.toBeInTheDocument();
+    expect(onExplain).not.toHaveBeenCalled();
+  });
+
+  it('ignores a selection that starts in the container but ends inside the assistant panel', () => {
+    const onExplain = vi.fn();
+    render(<Harness onExplain={onExplain} />);
+
+    const contentNode = screen.getByTestId('content').firstChild!;
+    const panelNode = screen.getByTestId('panel').firstChild!;
+
+    const range = document.createRange();
+    range.setStart(contentNode, 0);
+    range.setEnd(panelNode, 4);
+    const sel = window.getSelection()!;
+    sel.removeAllRanges();
+    sel.addRange(range);
+    fireEvent.mouseUp(document);
+
+    expect(screen.queryByRole('button', { name: /explain with kai/i })).not.toBeInTheDocument();
+    expect(onExplain).not.toHaveBeenCalled();
+  });
+});