create-keboola-app 0.0.0

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

@@ -0,0 +1,151 @@
+import { useCallback, useMemo, useState } from 'react';
+import {
+  createColumnHelper,
+  flexRender,
+  getCoreRowModel,
+  useReactTable,
+} from '@tanstack/react-table';
+
+import { NumberInput, Table } from '@keboola/design';
+
+import type { BudgetRow } from '../routes/-fixtures';
+import { BUDGET_MONTHS } from '../routes/-fixtures';
+
+// Instantiates the DS editable-grid recipe (`Table.DataGridRecipe` story,
+// `EditableDataGrid`): TanStack Table v8 (headless) for the column/row model,
+// design `Table` for styling, design `NumberInput` as the editable cell, with a
+// live-computed row total column and footer grand total.
+const sum = (xs: number[]) => xs.reduce((a, b) => a + b, 0);
+
+const columnHelper = createColumnHelper<BudgetRow>();
+
+export function CreditBudgetGrid({ rows }: { rows: BudgetRow[] }) {
+  // Server data seeds local edit state, re-seeding when a fetch returns new rows.
+  // Adjusted during render rather than in an effect: an effect would commit the
+  // stale rows first and repaint, and React documents this as the way to reset
+  // state on a prop change (design's own SidebarProvider does the same).
+  const [data, setData] = useState<BudgetRow[]>(rows);
+  const [seed, setSeed] = useState<BudgetRow[]>(rows);
+  if (seed !== rows) {
+    setSeed(rows);
+    setData(rows);
+  }
+
+  const updateCell = useCallback(
+    (rowIndex: number, monthIndex: number, value: number) =>
+      setData((current) =>
+        current.map((row, index) => {
+          if (index !== rowIndex) return row;
+          const months = [...row.months];
+          months[monthIndex] = value;
+          return { ...row, months };
+        }),
+      ),
+    [],
+  );
+
+  const columns = useMemo(
+    () => [
+      columnHelper.accessor('component', {
+        header: 'Component',
+        cell: ({ row, getValue }) => (
+          <>
+            {getValue()}{' '}
+            <span className="tw:text-xs tw:text-muted-foreground">{row.original.kind}</span>
+          </>
+        ),
+      }),
+      ...BUDGET_MONTHS.map((month, monthIndex) =>
+        columnHelper.accessor((row) => row.months[monthIndex] ?? 0, {
+          id: `month-${monthIndex}`,
+          header: month,
+          cell: ({ getValue, row }) => (
+            <NumberInput
+              aria-label={`${row.original.component} ${month}`}
+              value={getValue()}
+              onValueChange={(value) => updateCell(row.index, monthIndex, value ?? 0)}
+            />
+          ),
+        }),
+      ),
+      columnHelper.display({
+        id: 'total',
+        header: 'Total',
+        cell: ({ row }) => (
+          <span className="tw:font-semibold tw:tabular-nums">{sum(row.original.months)}</span>
+        ),
+      }),
+    ],
+    [updateCell],
+  );
+
+  const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+
+  const monthTotals = BUDGET_MONTHS.map((_, monthIndex) =>
+    sum(data.map((row) => row.months[monthIndex] ?? 0)),
+  );
+  const grandTotal = sum(monthTotals);
+
+  return (
+    <Table bordered>
+      <Table.Header>
+        {table.getHeaderGroups().map((headerGroup) => (
+          <Table.Row key={headerGroup.id}>
+            {headerGroup.headers.map((header) => (
+              <Table.Head
+                key={header.id}
+                className={header.column.id === 'component' ? undefined : 'tw:text-right'}
+              >
+                {flexRender(header.column.columnDef.header, header.getContext())}
+              </Table.Head>
+            ))}
+          </Table.Row>
+        ))}
+      </Table.Header>
+      <Table.Body>
+        {table.getRowModel().rows.map((row) => (
+          <Table.Row key={row.id}>
+            {row.getVisibleCells().map((cell) => (
+              <Table.Cell
+                key={cell.id}
+                className={
+                  cell.column.id === 'component'
+                    ? 'tw:min-w-52'
+                    : cell.column.id === 'total'
+                      ? 'tw:text-right tw:tabular-nums'
+                      : // Wide enough for the editor, not just the number. `NumberInput`
+                        // carries 16px of padding on each side, so a `w-20` (80px) cell
+                        // minus the `px-3` gutter left ~22px of text box — enough to
+                        // render "8" and silently hide the "00" of 800.
+                        //
+                        // `min-w`, not `w`: a width is only a hint, and a `w-full` table
+                        // squeezed by the assistant rail compresses past it and clips the
+                        // inputs again. A floor makes the table outgrow its container
+                        // instead, which the wrapper's `overflow-x-auto` then scrolls — a
+                        // single-line input can't be scrolled by eye, so its value has to
+                        // stay fully visible at any container width.
+                        'tw:min-w-28'
+                }
+              >
+                {flexRender(cell.column.columnDef.cell, cell.getContext())}
+              </Table.Cell>
+            ))}
+          </Table.Row>
+        ))}
+      </Table.Body>
+      <Table.Footer>
+        <Table.Row>
+          <Table.Cell className="tw:font-semibold">Total</Table.Cell>
+          {BUDGET_MONTHS.map((month, monthIndex) => (
+            <Table.Cell key={month} className="tw:text-right tw:font-semibold tw:tabular-nums">
+              {monthTotals[monthIndex]}
+            </Table.Cell>
+          ))}
+          <Table.Cell className="tw:text-right tw:font-semibold tw:tabular-nums">
+            {grandTotal}
+          </Table.Cell>
+        </Table.Row>
+      </Table.Footer>
+    </Table>
+  );
+}

package/dist/template/src/routes/-fixtures.ts

@@ -0,0 +1,113 @@
+// In-memory stand-in for a real overview endpoint. Swap `fetchOverview` for the
+// api-client call (e.g. `api.metrics.overview(signal)`) and delete this file.
+// The call takes an AbortSignal and honors it, so the query hook threads
+// cancellation exactly as it would against a real client — see -hooks.ts.
+
+export type Kpi = {
+  label: string;
+  value: string;
+  deltaPct?: number;
+};
+
+/** A month of credit consumption against what was budgeted for it. */
+export type CreditPoint = { month: string; used: number; budgeted: number };
+
+/** One component's monthly credit budget, editable in the grid. */
+export type BudgetRow = {
+  id: string;
+  component: string;
+  kind: string;
+  months: number[];
+};
+
+export type Overview = {
+  kpis: Kpi[];
+  credits: CreditPoint[];
+  budget: BudgetRow[];
+};
+
+export const BUDGET_MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'] as const;
+
+const OVERVIEW: Overview = {
+  kpis: [
+    { label: 'Job success rate', value: '98.7%', deltaPct: 0.3 },
+    { label: 'Storage used', value: '1.4 TB', deltaPct: 4.2 },
+    { label: 'Active configurations', value: '312', deltaPct: 2.1 },
+    // No delta on purpose: `KpiCard` paints a rise green, which is the wrong
+    // signal for a cost. Leaving it off also exercises the optional branch.
+    { label: 'Credits this month', value: '8,420' },
+  ],
+  // Two series of the same order of magnitude, so they read against one linear
+  // axis. Pairing a ~60k series with a ~1k one renders the small one as a flat
+  // line on the floor — a chart that looks informative and isn't.
+  //
+  // Consumption climbs from a low base, so a zero baseline is honest *and* uses
+  // the plot: the story is the gap to the ceiling closing month over month.
+  credits: [
+    { month: 'Jan', used: 4200, budgeted: 8000 },
+    { month: 'Feb', used: 5100, budgeted: 8000 },
+    { month: 'Mar', used: 5900, budgeted: 8000 },
+    { month: 'Apr', used: 6800, budgeted: 8500 },
+    { month: 'May', used: 7600, budgeted: 8500 },
+    { month: 'Jun', used: 8420, budgeted: 8500 },
+  ],
+  // The grid *is* the budget the chart plots: each month's column sums to that
+  // month's `budgeted` value above (8000 ×3, then 8500 ×3). Fixtures that don't
+  // reconcile are the fastest way to make a demo look fake.
+  budget: [
+    {
+      id: 'ex-db',
+      component: 'Database extractor',
+      kind: 'Extractor',
+      months: [4200, 4300, 4400, 4500, 4600, 4700],
+    },
+    {
+      id: 'tr-python',
+      component: 'Python transformation',
+      kind: 'Transformation',
+      months: [2100, 2150, 2200, 2250, 2300, 2350],
+    },
+    {
+      id: 'wr-snowflake',
+      component: 'Snowflake writer',
+      kind: 'Writer',
+      months: [900, 920, 950, 980, 1000, 1050],
+    },
+    {
+      id: 'orchestrator',
+      component: 'Daily orchestration',
+      kind: 'Flow',
+      months: [800, 630, 450, 770, 600, 400],
+    },
+  ],
+};
+
+// Simulates a network round-trip that resolves after `ms`, or rejects the moment
+// an AbortSignal fires — mirroring how a real fetch-based client aborts in-flight
+// when TanStack Query cancels the query.
+const delay = (ms: number, signal?: AbortSignal): Promise<void> =>
+  new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+
+/** Resolves with the project overview after a simulated round-trip; rejects if aborted. */
+export const fetchOverview = async (signal?: AbortSignal): Promise<Overview> => {
+  await delay(200, signal);
+  return {
+    kpis: [...OVERVIEW.kpis],
+    credits: [...OVERVIEW.credits],
+    budget: OVERVIEW.budget.map((row) => ({ ...row, months: [...row.months] })),
+  };
+};

package/dist/template/src/routes/-hooks.ts

@@ -0,0 +1,15 @@
+import { useQuery } from '@tanstack/react-query';
+
+import { fetchOverview } from './-fixtures';
+
+const queryKeys = {
+  overview: ['overview'] as const,
+} as const;
+
+export const useOverview = () =>
+  useQuery({
+    queryKey: queryKeys.overview,
+    // Always thread the query's AbortSignal to the data call — TanStack Query
+    // aborts it on unmount / refetch. Swap `fetchOverview` for the real client.
+    queryFn: ({ signal }) => fetchOverview(signal),
+  });

package/dist/template/src/routes/-index.test.tsx

@@ -0,0 +1,123 @@
+import type { ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { render, screen, waitFor } from '@testing-library/react';
+// #region block:assistant
+import userEvent from '@testing-library/user-event';
+// #endregion block:assistant
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useAppStore } from '../store';
+
+import * as fixtures from './-fixtures';
+import { HomePage } from './index';
+
+const renderPage = () => {
+  // `retry: false` so the error branch is reachable without waiting out backoff.
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+  return render(<HomePage />, { wrapper });
+};
+
+describe('HomePage', () => {
+  beforeEach(() => {
+    useAppStore.setState({ helpVisible: true });
+    // #region block:assistant
+    useAppStore.setState({ messages: [], fullscreen: false });
+    // #endregion block:assistant
+  });
+
+  // #region block:kpi
+  it('renders the KPIs once the overview loads', async () => {
+    renderPage();
+
+    expect(await screen.findByText('Job success rate')).toBeInTheDocument();
+    expect(screen.getByText('Credits this month')).toBeInTheDocument();
+  });
+  // #endregion block:kpi
+
+  // #region block:chart
+  it('renders the credits chart once the overview loads', async () => {
+    renderPage();
+
+    expect(
+      await screen.findByRole('heading', { name: 'Credits: used vs budgeted' }),
+    ).toBeInTheDocument();
+  });
+  // #endregion block:chart
+
+  // #region block:grid
+  it('renders the budget grid once the overview loads', async () => {
+    renderPage();
+
+    expect(await screen.findByText('Component')).toBeInTheDocument();
+  });
+  // #endregion block:grid
+
+  it('shows a loading placeholder before the overview resolves', () => {
+    const { container } = renderPage();
+
+    // Asserted before the query settles: `[data-section]` is the success branch, and it holds
+    // for any block selection — a shell-only app has no KPI label to look for.
+    expect(container.querySelectorAll('[data-section]')).toHaveLength(0);
+    expect(screen.getByRole('heading', { name: 'Overview' })).toBeInTheDocument();
+  });
+
+  it('shows an error state when the overview fails to load', async () => {
+    vi.spyOn(fixtures, 'fetchOverview').mockRejectedValueOnce(new Error('network is down'));
+    renderPage();
+
+    expect(await screen.findByText('Failed to load the overview')).toBeInTheDocument();
+    expect(screen.getByText('network is down')).toBeInTheDocument();
+  });
+
+  // #region block:assistant
+  it('hands a prompt off to the assistant transcript rather than answering inline', async () => {
+    const user = userEvent.setup();
+    renderPage();
+
+    await user.type(screen.getByPlaceholderText('Ask about this page…'), 'why is churn up?');
+    await user.keyboard('{Enter}');
+
+    await waitFor(() => expect(useAppStore.getState().messages).toHaveLength(2));
+    const [question, reply] = useAppStore.getState().messages;
+    expect(question?.text).toBe('why is churn up?');
+    expect(reply?.role).toBe('assistant');
+    // The rail renders the reply; the page must not.
+    expect(screen.queryByText(/Credits tracked under budget/)).not.toBeInTheDocument();
+  });
+
+  it('clears the prompt after sending', async () => {
+    const user = userEvent.setup();
+    renderPage();
+
+    const prompt = screen.getByPlaceholderText('Ask about this page…');
+    await user.type(prompt, 'hello');
+    await user.keyboard('{Enter}');
+
+    expect(prompt).toHaveValue('');
+  });
+
+  it('ignores a whitespace-only prompt', async () => {
+    const user = userEvent.setup();
+    renderPage();
+
+    await user.type(screen.getByPlaceholderText('Ask about this page…'), '   ');
+    await user.keyboard('{Enter}');
+
+    expect(useAppStore.getState().messages).toEqual([]);
+  });
+  // #endregion block:assistant
+
+  it('drops the page description when help is hidden', async () => {
+    renderPage();
+    expect(await screen.findByText(/Credit consumption, job health/)).toBeInTheDocument();
+
+    useAppStore.setState({ helpVisible: false });
+
+    await waitFor(() =>
+      expect(screen.queryByText(/Credit consumption, job health/)).not.toBeInTheDocument(),
+    );
+  });
+});

package/dist/template/src/routes/__root.tsx

@@ -0,0 +1,20 @@
+import { createRootRoute, Outlet } from '@tanstack/react-router';
+
+import { Toaster } from '@keboola/design';
+
+import { AppChrome } from '../components/AppChrome';
+
+export const Route = createRootRoute({
+  component: RootLayout,
+});
+
+function RootLayout() {
+  return (
+    <div className="tailwindcss-preflight">
+      <AppChrome>
+        <Outlet />
+      </AppChrome>
+      <Toaster />
+    </div>
+  );
+}

package/dist/template/src/routes/index.tsx

@@ -0,0 +1,95 @@
+import { Fragment, useRef } from 'react';
+import { createFileRoute } from '@tanstack/react-router';
+
+import { ErrorState, PageHeader, PageLayout } from '@keboola/design';
+
+// #region block:assistant
+import { HomePrompt } from '../components/HomePrompt';
+import { SelectionFloater } from '../components/SelectionFloater';
+// #endregion block:assistant
+import { OVERVIEW_SECTIONS } from '../overview-sections';
+import { useAppStore } from '../store';
+
+import type { Overview } from './-fixtures';
+import { useOverview } from './-hooks';
+
+export const Route = createFileRoute('/')({
+  component: HomePage,
+});
+
+export function HomePage() {
+  const { data, isLoading, isError, error } = useOverview();
+  const helpVisible = useAppStore((s) => s.helpVisible);
+  // Marks the page's data content, as opposed to its chrome and its composer.
+  // #region block:assistant
+  // The selection floater scopes itself to this element, so selecting your own draft text
+  // does not offer to explain it back to you.
+  // #endregion block:assistant
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <PageLayout>
+      <PageLayout.Header>
+        <PageHeader.Index
+          title="Overview"
+          description={
+            helpVisible
+              ? 'Credit consumption, job health, and the per-component budget for this project. Select any figure to ask about it.'
+              : undefined
+          }
+        />
+      </PageLayout.Header>
+
+      <PageLayout.Content className="tw:min-w-0">
+        <div className="tw:flex tw:flex-col tw:gap-6">
+          {/* #region block:assistant */}
+          <HomePrompt />
+          {/* #endregion block:assistant */}
+          <div ref={contentRef} className="tw:flex tw:flex-col tw:gap-6">
+            {isLoading && <OverviewSkeleton />}
+            {isError && <OverviewError error={error} />}
+            {!isLoading && !isError && data !== undefined && <OverviewContent overview={data} />}
+          </div>
+        </div>
+        {/* #region block:assistant */}
+        <SelectionFloater
+          containerRef={contentRef}
+          onExplain={(text) => useAppStore.getState().send(`Explain: ${text}`)}
+        />
+        {/* #endregion block:assistant */}
+      </PageLayout.Content>
+    </PageLayout>
+  );
+}
+
+// The page owns the frame; `src/overview-sections.tsx` owns which sections are present
+// and in what order.
+function OverviewContent({ overview }: { overview: Overview }) {
+  return (
+    <>
+      {OVERVIEW_SECTIONS.map((section) => (
+        <Fragment key={section.id}>{section.render(overview)}</Fragment>
+      ))}
+    </>
+  );
+}
+
+function OverviewSkeleton() {
+  return (
+    <div className="tw:flex tw:flex-col tw:gap-6">
+      {OVERVIEW_SECTIONS.map((section) => (
+        <Fragment key={section.id}>{section.renderSkeleton()}</Fragment>
+      ))}
+    </div>
+  );
+}
+
+function OverviewError({ error }: { error: Error }) {
+  return (
+    <ErrorState>
+      <ErrorState.Icon>⚠</ErrorState.Icon>
+      <ErrorState.Title>Failed to load the overview</ErrorState.Title>
+      <ErrorState.Description>{error.message}</ErrorState.Description>
+    </ErrorState>
+  );
+}

package/dist/template/src/routes/tokens/$id.tsx

@@ -0,0 +1,95 @@
+import { createFileRoute, Link } from '@tanstack/react-router';
+
+import { Breadcrumb, Button, ErrorState, PageHeader, PageLayout, Skeleton } from '@keboola/design';
+
+import { useToken } from './-hooks';
+import type { Token } from './-types';
+
+export const Route = createFileRoute('/tokens/$id')({
+  component: TokenDetailPage,
+});
+
+function TokenDetailPage() {
+  const { id } = Route.useParams();
+  const { data: token, isLoading, isError, error } = useToken(id);
+
+  return (
+    <PageLayout maxWidth="narrow">
+      <PageLayout.Header>
+        <PageHeader.Detail
+          breadcrumbs={
+            <Breadcrumb>
+              <Breadcrumb.List>
+                <Breadcrumb.Item>
+                  <Breadcrumb.Link asChild>
+                    <Link to="/tokens">Tokens</Link>
+                  </Breadcrumb.Link>
+                </Breadcrumb.Item>
+                <Breadcrumb.Separator />
+                <Breadcrumb.Item>
+                  <Breadcrumb.Page>{token?.description ?? id}</Breadcrumb.Page>
+                </Breadcrumb.Item>
+              </Breadcrumb.List>
+            </Breadcrumb>
+          }
+          title={token?.description ?? 'Token detail'}
+        />
+      </PageLayout.Header>
+
+      <PageLayout.Content>
+        {isLoading && <TokenDetailSkeleton />}
+        {isError && <TokenDetailError error={error} />}
+        {!isLoading && !isError && token !== undefined && <TokenFields token={token} />}
+
+        <div className="tw:mt-6">
+          <Button asChild variant="outline">
+            <Link to="/tokens">Back to tokens</Link>
+          </Button>
+        </div>
+      </PageLayout.Content>
+    </PageLayout>
+  );
+}
+
+function TokenDetailSkeleton() {
+  return (
+    <div className="tw:flex tw:flex-col tw:gap-3">
+      <Skeleton className="tw:h-8 tw:w-2/3" />
+      <Skeleton className="tw:h-32 tw:w-full tw:rounded-card" />
+    </div>
+  );
+}
+
+function TokenDetailError({ error }: { error: Error }) {
+  return (
+    <ErrorState>
+      <ErrorState.Icon>⚠</ErrorState.Icon>
+      <ErrorState.Title>Failed to load token</ErrorState.Title>
+      <ErrorState.Description>{error.message}</ErrorState.Description>
+    </ErrorState>
+  );
+}
+
+function TokenFields({ token }: { token: Token }) {
+  return (
+    <dl className="tw:grid tw:grid-cols-[max-content_1fr] tw:gap-x-6 tw:gap-y-3 tw:rounded-card tw:border tw:border-border tw:bg-background tw:p-5 tw:shadow-card">
+      <Field label="ID" value={token.id} />
+      <Field label="Description" value={token.description} />
+      <Field label="Type" value={token.isMasterToken ? 'Master' : 'Limited'} />
+      <Field label="Created" value={new Date(token.created).toLocaleString('en-US')} />
+      <Field
+        label="Expires"
+        value={token.expiresAt ? new Date(token.expiresAt).toLocaleString('en-US') : 'Never'}
+      />
+    </dl>
+  );
+}
+
+function Field({ label, value }: { label: string; value: string }) {
+  return (
+    <>
+      <dt className="tw:text-sm tw:font-medium tw:text-muted-foreground">{label}</dt>
+      <dd className="tw:m-0 tw:text-sm tw:text-foreground">{value}</dd>
+    </>
+  );
+}

package/dist/template/src/routes/tokens/-fixtures.test.ts

@@ -0,0 +1,60 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { createToken, fetchToken, fetchTokens, resetFixtures } from './-fixtures';
+
+describe('fixtures', () => {
+  beforeEach(() => {
+    resetFixtures();
+  });
+
+  it('fetchTokens resolves with an array of tokens', async () => {
+    const tokens = await fetchTokens();
+    expect(Array.isArray(tokens)).toBe(true);
+    expect(tokens.length).toBeGreaterThan(0);
+    expect(tokens[0]).toMatchObject({
+      id: expect.any(String),
+      description: expect.any(String),
+      isMasterToken: expect.any(Boolean),
+      created: expect.any(String),
+    });
+  });
+
+  it('createToken adds a new token and fetchTokens returns it', async () => {
+    const input = { description: 'Test token', expiresIn: 'never' } as const;
+    const created = await createToken(input);
+
+    expect(created.description).toBe(input.description);
+    expect(created.expiresAt).toBeNull();
+    expect(created.isMasterToken).toBe(false);
+
+    const tokens = await fetchTokens();
+    expect(tokens.some((t) => t.id === created.id)).toBe(true);
+  });
+
+  it('createToken sets expiresAt when expiresIn is provided', async () => {
+    const input = { description: 'Expiring token', expiresIn: '86400' } as const;
+    const created = await createToken(input);
+
+    expect(created.expiresAt).not.toBeNull();
+  });
+
+  it('fetchToken resolves a single token by id', async () => {
+    const all = await fetchTokens();
+    const sample = all[0];
+    if (sample === undefined) throw new Error('seed is empty — check INITIAL_TOKENS');
+
+    const fetched = await fetchToken(sample.id);
+    expect(fetched).toEqual(sample);
+  });
+
+  it('fetchToken rejects when the id does not exist', async () => {
+    await expect(fetchToken('tok-missing')).rejects.toThrow(/not found/);
+  });
+
+  it('fetchTokens rejects when its AbortSignal fires', async () => {
+    const controller = new AbortController();
+    const promise = fetchTokens(controller.signal);
+    controller.abort();
+    await expect(promise).rejects.toThrow();
+  });
+});