create-keboola-app 0.0.0

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

@@ -0,0 +1,88 @@
+import { useEffect, useState } from 'react';
+import type { RefObject } from 'react';
+
+import { Button } from '@keboola/design';
+
+type FloaterSelection = {
+  text: string;
+  top: number;
+  left: number;
+};
+
+// Selections inside an assistant-panel instance (rail or fullscreen) never
+// trigger the floater — marker kept in sync with AssistantPanel's root.
+const ASSISTANT_PANEL_SELECTOR = '[data-assistant-panel]';
+
+export function SelectionFloater({
+  containerRef,
+  onExplain,
+}: {
+  /** Only selections anchored inside this element trigger the floater. */
+  containerRef: RefObject<HTMLElement | null>;
+  onExplain: (text: string) => void;
+}) {
+  const [selection, setSelection] = useState<FloaterSelection | null>(null);
+
+  useEffect(() => {
+    const handleSelectionChange = () => {
+      const sel = window.getSelection();
+      const text = sel?.toString().trim() ?? '';
+      const anchorNode = sel?.anchorNode ?? null;
+      const focusNode = sel?.focusNode ?? null;
+      const container = containerRef.current;
+
+      if (!sel || sel.rangeCount === 0 || !text || !anchorNode || !focusNode || !container) {
+        setSelection(null);
+        return;
+      }
+
+      const toElement = (node: Node) =>
+        node.nodeType === Node.ELEMENT_NODE ? (node as Element) : node.parentElement;
+
+      const anchorElement = toElement(anchorNode);
+      const focusElement = toElement(focusNode);
+
+      const isValid = (element: Element | null) =>
+        !!element && container.contains(element) && !element.closest(ASSISTANT_PANEL_SELECTOR);
+
+      if (!isValid(anchorElement) || !isValid(focusElement)) {
+        setSelection(null);
+        return;
+      }
+
+      const range = sel.getRangeAt(0);
+      const rect =
+        typeof range.getBoundingClientRect === 'function'
+          ? range.getBoundingClientRect()
+          : { top: 0, left: 0 };
+      setSelection({ text, top: rect.top, left: rect.left });
+    };
+
+    document.addEventListener('mouseup', handleSelectionChange);
+    document.addEventListener('selectionchange', handleSelectionChange);
+    return () => {
+      document.removeEventListener('mouseup', handleSelectionChange);
+      document.removeEventListener('selectionchange', handleSelectionChange);
+    };
+  }, [containerRef]);
+
+  if (!selection) return null;
+
+  const handleClick = () => {
+    onExplain(selection.text);
+    window.getSelection()?.removeAllRanges();
+    setSelection(null);
+  };
+
+  return (
+    <Button
+      variant="secondary"
+      size="small"
+      className="tw:fixed tw:z-50"
+      style={{ top: selection.top - 40, left: selection.left }}
+      onClick={handleClick}
+    >
+      Explain with Kai
+    </Button>
+  );
+}

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

@@ -0,0 +1,68 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { Sidebar, SidebarProvider } from '@keboola/design';
+
+import { useAppStore } from '../store';
+
+import { SidebarModeMenu } from './SidebarModeMenu';
+
+// Mirrors AppChrome's wiring.
+// - The provider is controlled from the store, so a pick travels menu -> setMode ->
+//   onLeftModeChange -> store. An uncontrolled provider would pass with that chain broken.
+// - The `<Sidebar>` is required, not scenery: `Sidebar.MenuButton` reads
+//   `SidebarInstanceContext`, which `<Sidebar>` provides and `SidebarProvider` does not.
+function Harness() {
+  const sidebarMode = useAppStore((s) => s.sidebarMode);
+  const setSidebarMode = useAppStore((s) => s.setSidebarMode);
+
+  return (
+    <SidebarProvider
+      leftMode={sidebarMode}
+      onLeftModeChange={setSidebarMode}
+      leftVariant="inset"
+      leftCollapsible="icon"
+    >
+      <Sidebar side="left">
+        <Sidebar.Footer>
+          <Sidebar.Menu>
+            <SidebarModeMenu />
+          </Sidebar.Menu>
+        </Sidebar.Footer>
+      </Sidebar>
+    </SidebarProvider>
+  );
+}
+
+describe('<SidebarModeMenu />', () => {
+  beforeEach(() => {
+    useAppStore.setState({ sidebarMode: 'expanded' });
+  });
+
+  it.each([
+    ['Collapsed', 'collapsed'],
+    ['Expand on hover', 'expand-on-hover'],
+  ])('writes %s through to the store', async (label, mode) => {
+    // Radix marks the closed menu's content `pointer-events: none`; userEvent's check
+    // targets real pointer obstruction, not this.
+    const user = userEvent.setup({ pointerEventsCheck: 0 });
+    render(<Harness />);
+
+    await user.click(screen.getByRole('button', { name: 'Sidebar mode' }));
+    await user.click(screen.getByRole('menuitemradio', { name: label }));
+
+    expect(useAppStore.getState().sidebarMode).toBe(mode);
+  });
+
+  it('marks the active mode as checked', async () => {
+    const user = userEvent.setup({ pointerEventsCheck: 0 });
+    useAppStore.setState({ sidebarMode: 'expand-on-hover' });
+    render(<Harness />);
+
+    await user.click(screen.getByRole('button', { name: 'Sidebar mode' }));
+
+    expect(screen.getByRole('menuitemradio', { name: 'Expand on hover' })).toBeChecked();
+    expect(screen.getByRole('menuitemradio', { name: 'Expanded' })).not.toBeChecked();
+  });
+});

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

@@ -0,0 +1,54 @@
+import type { SidebarMode } from '@keboola/design';
+import { DropdownMenu, Sidebar, useSidebar } from '@keboola/design';
+import { PanelLeft } from '@keboola/design/icons';
+
+const MODES: { value: SidebarMode; label: string }[] = [
+  { value: 'expanded', label: 'Expanded' },
+  { value: 'collapsed', label: 'Collapsed' },
+  { value: 'expand-on-hover', label: 'Expand on hover' },
+];
+
+/**
+ * Picks the left rail's mode. All three come from `SidebarProvider`.
+ *
+ * - `expand-on-hover` is a mode of its own, not `collapsed` plus a hover handler: the
+ *   rail reports `mode="expand-on-hover"` while its `state` flips on hover. Styling that
+ *   distinguishes "the user collapsed this" from "collapsed until hovered" reads `mode`.
+ * - A radio group, not a cycling button: three modes have no natural next, and the menu
+ *   shows which is active without clicking through.
+ * - `setMode` writes through `onLeftModeChange` into the app store, which persists it.
+ */
+export function SidebarModeMenu() {
+  const { setMode, mode } = useSidebar('left');
+
+  return (
+    <Sidebar.MenuItem>
+      <DropdownMenu>
+        <DropdownMenu.Trigger asChild>
+          {/* `w-fit` keeps the trigger icon-sized rather than rail-wide, so it holds its
+              position when the rail collapses to icons. */}
+          <Sidebar.MenuButton
+            tooltip="Sidebar mode"
+            className="tw:w-fit"
+            icon={<PanelLeft />}
+            aria-label="Sidebar mode"
+          />
+        </DropdownMenu.Trigger>
+        {/* `align="start"` — the trigger sits at the rail's left edge, so a centered
+            menu would hang off the viewport when the rail is collapsed. */}
+        <DropdownMenu.Content align="start">
+          <DropdownMenu.Label>Sidebar mode</DropdownMenu.Label>
+          {/* `RadioGroup` is generic over its value: `value={mode}` pins it to
+              `SidebarMode`, so `setMode` slots in without a cast. */}
+          <DropdownMenu.RadioGroup value={mode} onValueChange={setMode}>
+            {MODES.map(({ value, label }) => (
+              <DropdownMenu.RadioItem key={value} closeOnSelect indicatorAlign="end" value={value}>
+                {label}
+              </DropdownMenu.RadioItem>
+            ))}
+          </DropdownMenu.RadioGroup>
+        </DropdownMenu.Content>
+      </DropdownMenu>
+    </Sidebar.MenuItem>
+  );
+}

package/dist/template/src/index.css

@@ -0,0 +1,26 @@
+/* Tailwind v4. Standard theme + this app's own utilities (auto-detected from its
+ * source). The `@keboola/design/theme` import adds design's semantic color tokens
+ * (portable @theme, no @config/@plugin) so the app can generate themed utilities
+ * like `tw:bg-background`; `@keboola/design/styles/compiled` supplies design's
+ * component chrome, the runtime `--*` tokens, and the scoped preflight as plain CSS. */
+
+/* Declare the cascade-layer order up front. Everything — the app's own generated
+ * utilities AND design's compiled utilities — shares ONE `utilities` layer, so v3-style
+ * SPECIFICITY still decides conflicts. This matters: design styles component internals
+ * with higher-specificity descendant rules (e.g. SearchInput's `[&>input]:py-[15px]`)
+ * that must keep beating a plain `p-0`; a dedicated higher app-utilities layer would let
+ * plain app utilities override them (layer beats specificity), zeroing component padding.
+ * The only conflict specificity can't settle is same-specificity DUPLICATES — the app's
+ * `md:grid-cols-3` vs design-compiled's `grid-cols-1` (both 0,1,0). CSS breaks that tie by
+ * SOURCE ORDER, so design's compiled CSS is imported BEFORE the app's own `utilities.css`;
+ * the app's utilities land later and win the tie, fixing the responsive/grid/filter
+ * collapse. `base`/`components` keep design's preflight below its component chrome. */
+@layer theme, base, components, utilities;
+@import 'tailwindcss/theme.css' layer(theme) prefix(tw);
+@import '@keboola/design/theme';
+@import '@keboola/design/styles/compiled';
+@import 'tailwindcss/utilities.css' layer(utilities) prefix(tw);
+
+body {
+  @apply tw:m-0 tw:min-h-screen tw:bg-background;
+}

package/dist/template/src/main.tsx

@@ -0,0 +1,57 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+import { createRouter, RouterProvider } from '@tanstack/react-router';
+
+import { keboola } from '@keboola/brand-registry';
+import { ThemeProvider } from '@keboola/design';
+
+import './index.css';
+
+// Route tree is code-generated by @tanstack/router-plugin/vite on `pnpm dev` or
+// `pnpm build`. The committed stub in routeTree.gen.ts keeps type-check + CI
+// green without needing to run the dev server first.
+import { routeTree } from './routeTree.gen';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60_000,
+      retry: 1,
+    },
+  },
+});
+
+const router = createRouter({ routeTree });
+
+// Register the router instance for type-safety globally. Module augmentation
+// only works through `interface` declarations, so we suppress the project-wide
+// "prefer type over interface" rule here.
+declare module '@tanstack/react-router' {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface Register {
+    router: typeof router;
+  }
+}
+
+const root = document.getElementById('app');
+if (!root) throw new Error('Root element #app not found');
+
+createRoot(root).render(
+  <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      {/* Register the brands and make one active. Without `brands` + `defaultBrandId`
+          the provider falls back to the brandless `design-system` sentinel: no brand
+          tokens are injected and `BrandLogo` renders nothing. */}
+      {/* `defaultScheme="system"` follows the OS and resolves reactively. The scheme
+          belongs here, not on individual components — the provider writes
+          `data-theme` and injects the brand's per-scheme token values together. */}
+      <ThemeProvider brands={[keboola]} defaultBrandId={keboola.id} defaultScheme="system">
+        <RouterProvider router={router} />
+      </ThemeProvider>
+      {/* eslint-disable-next-line turbo/no-undeclared-env-vars -- Vite built-in, not a real env var */}
+      {import.meta.env.DEV && <ReactQueryDevtools initialIsOpen={false} />}
+    </QueryClientProvider>
+  </StrictMode>,
+);

package/dist/template/src/nav.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { isActive, NAV } from './nav';
+
+describe('isActive', () => {
+  it('matches the root only exactly', () => {
+    expect(isActive('/', '/')).toBe(true);
+    expect(isActive('/tokens', '/')).toBe(false);
+  });
+
+  it('keeps a section active on its nested routes', () => {
+    expect(isActive('/tokens', '/tokens')).toBe(true);
+    expect(isActive('/tokens/new', '/tokens')).toBe(true);
+  });
+
+  it('does not treat a sibling that merely shares a prefix as nested', () => {
+    expect(isActive('/tokens-archive', '/tokens')).toBe(false);
+  });
+});
+
+describe('NAV', () => {
+  it('points every destination at a rooted path', () => {
+    for (const item of NAV) expect(item.to.startsWith('/')).toBe(true);
+  });
+});

package/dist/template/src/nav.ts

@@ -0,0 +1,38 @@
+import type { ComponentType } from 'react';
+
+import { LayoutDashboard } from '@keboola/design/icons';
+
+// #region block:crud
+import { tokensNavItem } from './routes/tokens/-nav';
+// #endregion block:crud
+
+export type NavItem = { to: string; label: string; icon: ComponentType };
+
+/**
+ * The left rail's destinations, in render order.
+ *
+ * - `as const` keeps each `to` a literal. `Link`'s `to` is typed against the generated
+ *   route tree, so a widened `string` fails type-check at the call site.
+ * - `satisfies` checks the shape without erasing those literals.
+ * - Icons render with no props (`<item.icon />`).
+ * - Each block contributes its own entry from a module the block owns, so a deselected block
+ *   takes its import with it.
+ */
+export const NAV = [
+  { to: '/', label: 'Overview', icon: LayoutDashboard },
+  // #region block:crud
+  tokensNavItem,
+  // #endregion block:crud
+] as const satisfies readonly NavItem[];
+
+/**
+ * Whether `to` is the active destination for `pathname`.
+ *
+ * - The root matches exactly.
+ * - Any other item stays active on its nested routes, matching Router's default
+ *   non-exact `Link` behaviour.
+ * - A sibling that merely shares the prefix (`/tokens-archive` under `/tokens`) is not
+ *   nested — hence the `/` in the boundary check.
+ */
+export const isActive = (pathname: string, to: string) =>
+  to === '/' ? pathname === '/' : pathname === to || pathname.startsWith(`${to}/`);

package/dist/template/src/overview-sections.test.tsx

@@ -0,0 +1,36 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { render, waitFor } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { HomePage } from './routes/index';
+import { OVERVIEW_SECTIONS } from './overview-sections';
+
+const renderPage = () => {
+  const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return render(
+    <QueryClientProvider client={client}>
+      <HomePage />
+    </QueryClientProvider>,
+  );
+};
+
+describe('the overview', () => {
+  it('shows one placeholder per registered section while loading', () => {
+    const { container } = renderPage();
+
+    expect(container.querySelectorAll('[data-section-skeleton]')).toHaveLength(
+      OVERVIEW_SECTIONS.length,
+    );
+  });
+
+  it('renders one section per registry entry once loaded', async () => {
+    const { container } = renderPage();
+
+    await waitFor(() =>
+      expect(container.querySelectorAll('[data-section]')).toHaveLength(OVERVIEW_SECTIONS.length),
+    );
+    for (const section of OVERVIEW_SECTIONS) {
+      expect(container.querySelector(`[data-section="${section.id}"]`)).not.toBeNull();
+    }
+  });
+});

package/dist/template/src/overview-sections.tsx

@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react';
+
+import type { Overview } from './routes/-fixtures';
+// #region block:chart
+import { chartSection } from './sections/chart';
+// #endregion block:chart
+// #region block:grid
+import { gridSection } from './sections/grid';
+// #endregion block:grid
+// #region block:kpi
+import { kpiSection } from './sections/kpi';
+// #endregion block:kpi
+
+/**
+ * One block's contribution to the overview.
+ *
+ * - `id` is the anchor: `data-section` when rendered, `data-section-skeleton` while
+ *   loading.
+ * - `renderSkeleton` lives with `render` so a section's placeholder matches its real
+ *   shape.
+ */
+export type OverviewSection = {
+  id: string;
+  render: (overview: Overview) => ReactNode;
+  renderSkeleton: () => ReactNode;
+};
+
+/** The sections this app carries, in render order. */
+export const OVERVIEW_SECTIONS: readonly OverviewSection[] = [
+  // One entry per section block, appended in render order.
+  // #region block:kpi
+  kpiSection,
+  // #endregion block:kpi
+  // #region block:chart
+  chartSection,
+  // #endregion block:chart
+  // #region block:grid
+  gridSection,
+  // #endregion block:grid
+];

package/dist/template/src/recipes/Chart.test.tsx

@@ -0,0 +1,24 @@
+import { render, screen } from '@testing-library/react';
+import { expect, it } from 'vitest';
+
+import { LineChartCard } from './Chart';
+
+it('renders the chart card title and legend labels', () => {
+  render(
+    <LineChartCard
+      title="Revenue"
+      xKey="month"
+      series={[{ key: 'mrr', label: 'MRR', tokenVar: '--chart-1' }]}
+      data={[
+        { month: 'Jan', mrr: 10 },
+        { month: 'Feb', mrr: 12 },
+      ]}
+      // recharts' <ResponsiveContainer> only renders once it measures a
+      // non-zero size via ResizeObserver, which jsdom never provides — an
+      // explicit width keeps the chart (and its legend) deterministic.
+      width={400}
+    />,
+  );
+  expect(screen.getByText('Revenue')).toBeInTheDocument();
+  expect(screen.getByText('MRR')).toBeInTheDocument();
+});

package/dist/template/src/recipes/Chart.tsx

@@ -0,0 +1,56 @@
+import { Card } from '@keboola/design';
+import { type ChartColorToken, LineChart } from '@keboola/design/charts';
+
+// Token-aware chart recipe — colors come from CSS vars (semantic/brand tokens),
+// never hex, so it re-themes with the active brand. `LineChartCard` is a thin
+// app-level card wrapper over the DS `@keboola/design/charts` `LineChart`.
+// The chart palette slots the DS exposes; narrowed so a typo is a compile error.
+type ChartTokenVar = '--chart-1' | '--chart-2' | '--chart-3' | '--chart-4' | '--chart-5';
+
+type Series = { key: string; label: string; tokenVar: ChartTokenVar };
+
+type LineChartCardProps = {
+  title: string;
+  data: readonly Record<string, number | string>[];
+  xKey: string;
+  series: readonly Series[];
+  // Forwarded to the DS `LineChart` only when set; otherwise its responsive
+  // `width="100%"` default applies. Tests pass an explicit size — recharts'
+  // <ResponsiveContainer> only renders once it measures a non-zero size via
+  // ResizeObserver, which jsdom never provides.
+  width?: number;
+};
+
+// Maps a `--chart-N` token var name to the design system's `--color-chart-N`
+// palette slot (1–5). `LineChart` resolves colors from this slot internally —
+// it never accepts a raw CSS var or hex value.
+const CHART_COLOR_SLOTS: Record<ChartTokenVar, ChartColorToken> = {
+  '--chart-1': 1,
+  '--chart-2': 2,
+  '--chart-3': 3,
+  '--chart-4': 4,
+  '--chart-5': 5,
+};
+
+export function LineChartCard({ title, data, xKey, series, width }: LineChartCardProps) {
+  return (
+    <Card>
+      <Card.Header>
+        <Card.Title as="h2">{title}</Card.Title>
+      </Card.Header>
+      <Card.Content>
+        <LineChart
+          data={[...data]}
+          xKey={xKey}
+          width={width}
+          series={series.map((s) => ({
+            dataKey: s.key,
+            name: s.label,
+            color: CHART_COLOR_SLOTS[s.tokenVar],
+          }))}
+          showLegend
+        />
+      </Card.Content>
+    </Card>
+  );
+}

package/dist/template/src/recipes/DataGrid.test.tsx

@@ -0,0 +1,47 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expect, it } from 'vitest';
+
+import type { BudgetRow } from '../routes/-fixtures';
+
+import { CreditBudgetGrid } from './DataGrid';
+
+const ROWS: BudgetRow[] = [
+  {
+    id: 'ex-db',
+    component: 'Database extractor',
+    kind: 'Extractor',
+    months: [800, 820, 850, 900, 940, 980],
+  },
+  {
+    id: 'tr-python',
+    component: 'Python transformation',
+    kind: 'Transformation',
+    months: [310, 320, 330, 350, 360, 380],
+  },
+];
+
+it('recomputes the row total and footer total when a monthly cell is edited', async () => {
+  const user = userEvent.setup();
+  render(<CreditBudgetGrid rows={ROWS} />);
+
+  expect(screen.getByText('Component')).toBeInTheDocument();
+
+  const janCell = screen.getByLabelText('Database extractor Jan');
+  const row = janCell.closest('tr');
+  expect(row).not.toBeNull();
+  // 800 + 820 + 850 + 900 + 940 + 980 = 5290
+  expect(row?.textContent).toContain('5290');
+
+  await user.clear(janCell);
+  await user.type(janCell, '1000');
+  await user.tab();
+
+  // 1000 + 820 + 850 + 900 + 940 + 980 = 5490
+  expect(row?.textContent).toContain('5490');
+
+  const footer = document.querySelector('tfoot');
+  expect(footer).not.toBeNull();
+  // grand total across both rows shifts from 7340 to 7540 (+200 edit delta)
+  expect(footer?.textContent).toContain('7540');
+});