create-keboola-app 0.1.1 → 0.2.1

package/dist/template/AGENTS.md

@@ -60,13 +60,14 @@ src/
   routeTree.gen.ts        # Generated from src/routes/** by the Vite plugin
   nav.ts                  # The rail's destinations and the active-match rule
   overview-sections.tsx   # The ordered registry the overview renders
+  overview-hooks.ts       # useOverview, AbortSignal threaded
+  overview-fixtures.ts    # In-memory overview stub — swap for a real client call
   store.ts                # The Zustand store: storage key, partialize, merge guard
   slices/shell.ts         # Sidebar mode + help visibility
   components/AppChrome.tsx  # AppShell + Navbar + Sidebar
-  routes/__root.tsx       # Root layout
+  routes/__root.tsx       # Root layout — and which routes get the app chrome
   routes/index.tsx        # / — the overview
-  routes/-hooks.ts        # useOverview, AbortSignal threaded
-  routes/-fixtures.ts     # In-memory overview stub — swap for a real client call
+  routes/index.test.tsx   # The overview's branches — a route's test sits with the route
 ```
 <!-- #region block:kpi -->
 - `components/KpiCard.tsx`, `sections/kpi.tsx` — the KPI row.
@@ -78,21 +79,34 @@ src/
 - `recipes/DataGrid.tsx`, `sections/grid.tsx` — the editable grid.
 <!-- #endregion block:grid -->
 <!-- #region block:crud -->
-- `routes/tokens/**` — the CRUD slice: `index.tsx`, `$id.tsx`, `new.tsx`, `-hooks.ts`,
-  `-fixtures.ts`, `-types.ts`, `-nav.ts`. **The entity is a placeholder.** Rename it to yours;
-  the fixture rows are labels only.
+- `routes/tokens/**` (`index.tsx`, `$id.tsx`, `new.tsx`) and `tokens/**` (`hooks.ts`,
+  `fixtures.ts`, `types.ts`, `nav.ts`) — the CRUD slice. **The entity is a placeholder.**
+  Rename it to yours; the fixture rows are labels only.
 <!-- #endregion block:crud -->
 <!-- #region block:assistant -->
 - `components/AssistantPanel.tsx`, `AssistantToggle.tsx`, `HomePrompt.tsx`,
   `SelectionFloater.tsx`, `slices/assistant.ts` — the assistant. `slices/assistant.ts`
   answers with a canned reply; swap that branch for a real request.
 <!-- #endregion block:assistant -->
+<!-- #region block:auth -->
+- `auth/AuthScreen.tsx`, `auth/states.tsx`, `auth/session.ts`, `routes/signed-out.tsx` — the
+  signed-out screen. **Presentational: it reaches no network.** Wiring it up is two edits —
+  the form's `onSubmit` in `states.tsx`, and where the state comes from. `routes/__root.tsx`
+  drops the app chrome for this route, so a visitor with no session sees no rail; a real app
+  usually goes further and renders the screen ahead of the router, which `AuthScreen` supports
+  by carrying its own `tailwindcss-preflight` scope.
+<!-- #endregion block:auth -->
 
 ## Adding a route
 
 Drop a file in `src/routes/`. The Vite plugin regenerates `routeTree.gen.ts` on the next
 `pnpm dev` or `pnpm build`; nothing needs registering by hand.
 
+`src/routes/` holds route files and their tests, nothing else. A route's hooks, fixtures,
+types and components live in a domain directory beside it (`src/reports/`), the way
+`src/auth/` and `src/tokens/` do — a non-route module under `src/routes/` is a route the
+generator has to be told to ignore.
+
 ```tsx
 import { createFileRoute } from '@tanstack/react-router';
 

package/dist/template/README.md

@@ -47,6 +47,11 @@ fails for a missing credential is a worse welcome than an opt-in gate.
 - A docked assistant rail on every route, a composer on the overview, and
   explain-on-selection. All three share one transcript.
 <!-- #endregion block:assistant -->
+<!-- #region block:auth -->
+- **`/signed-out`** — the pre-project screen, rendered without the app chrome: brand lockup,
+  one centred card, a colour-scheme control, and the restoring, expired and unreachable
+  states. Presentational: the form submits nowhere, and `?state=` stands in for your session.
+<!-- #endregion block:auth -->
 
 Every data call is an in-memory fixture that honours an `AbortSignal`. Replacing a fixture with
 a real `@keboola/api-client` call is a drop-in — the query hooks already thread `signal`.

package/dist/template/oxlint.config.ts

@@ -1,41 +1,37 @@
 import { defineConfig } from 'oxlint';
 
 import keboolaShared from '@keboola/oxlint-config';
+import keboolaShadcn, { shadcnSettings } from '@keboola/oxlint-config/shadcn';
 import keboolaTailwind from '@keboola/oxlint-config/tailwind';
 
 export default defineConfig({
-  // `keboolaTailwind` opts into the v4-native Tailwind lint layer
-  // (eslint-plugin-better-tailwindcss). It carries the plugin + rules; the
-  // `entryPoint` below is required — oxlint only reads `settings` from the
-  // root config, so it can't live inside the shared fragment.
-  extends: [keboolaShared, keboolaTailwind],
+  extends: [keboolaShared, keboolaTailwind, keboolaShadcn],
   env: {
     node: true,
   },
   settings: {
     'better-tailwindcss': {
-      // This app's Tailwind v4 CSS entry (the file that `@import`s "tailwindcss").
+      // The file that `@import`s "tailwindcss".
       entryPoint: 'src/index.css',
     },
+    shadcn: shadcnSettings,
   },
   jsPlugins: [
-    // Local design-system + brand-safety lint rules. Aliased to `design` so rule
-    // IDs read `design/<rule>` in lint output.
+    // Aliased to `design`, so rule IDs read `design/<rule>`.
     { name: 'design', specifier: '@keboola/eslint-plugin-design' },
   ],
   rules: {
-    // Shipped at 'warn' for the first pass, matching the plugin convention —
-    // promote to 'error' once generated apps are consistently clean. See
-    // packages/eslint-plugin-design/README.md.
+    'design/max-comment-lines': 'error',
+    // 'warn' until generated apps are consistently clean.
     'design/no-layout-primitives': 'warn',
-    'design/no-inline-color': 'warn',
+    // `design/no-inline-color` off: `shadcn/no-inline-styles` and `no-arbitrary-values` cover it.
     'design/no-primitive-tw-color': 'warn',
     'design/no-native-form-controls': 'warn',
     'design/no-raw-heading-on-page': 'warn',
     'design/prefer-design-modal': 'warn',
+    'design/htmlfor-points-at-nothing': 'error',
 
-    // 'error' from the start: this app is the scaffold template, so a
-    // locale-implicit format here is copied into every generated app.
+    // 'error': the scaffold copies any locale-implicit format into every generated app.
     'design/no-implicit-locale': 'error',
   },
 });

package/dist/template/package.json

@@ -15,39 +15,40 @@
     "type-check": "tsc"
   },
   "dependencies": {
-    "@keboola/brand-registry": "^1.9.4",
-    "@keboola/design": "^11.3.0",
+    "@keboola/brand-registry": "^3.1.0",
+    "@keboola/design": "^17.2.0",
     "@tanstack/react-form": "^1.29.1",
-    "@tanstack/react-query": "^5.96.2",
-    "@tanstack/react-router": "^1.120.4",
+    "@tanstack/react-query": "^5.104.5",
+    "@tanstack/react-router": "^1.170.46",
     "@tanstack/react-table": "^8.21.3",
-    "@tanstack/router-plugin": "^1.120.4",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
+    "@tanstack/router-plugin": "^1.168.48",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
     "zod": "^4.3.6",
     "zustand": "^5.0.8"
   },
   "devDependencies": {
-    "@keboola/eslint-plugin-design": "^0.4.3",
-    "@keboola/oxlint-config": "^10.0.2",
+    "@keboola/eslint-plugin-design": "^0.8.0",
+    "@keboola/oxlint-config": "^10.3.0",
     "@keboola/tsconfig": "^0.2.1",
+    "@shadcn/lint": "^0.1.5",
     "@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",
+    "@tanstack/react-query-devtools": "^5.104.5",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.8",
     "@types/node": "24.12.0",
-    "@types/react": "^19.2.15",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "@vitejs/plugin-react": "^6.0.0",
+    "@vitejs/plugin-react": "^6.1.2",
     "eslint-plugin-better-tailwindcss": "^4.7.0",
     "jsdom": "^26.1.0",
-    "oxfmt": "^0.57.0",
-    "oxlint": "^1.72.0",
+    "oxfmt": "^0.66.0",
+    "oxlint": "^1.89.0",
     "tailwindcss": "^4.3.3",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "vite": "^8.1.5",
-    "vitest": "^4.1.10"
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
   }
 }

package/dist/template/src/auth/AuthScreen.test.tsx

@@ -0,0 +1,44 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { keboola } from '@keboola/brand-registry';
+import { Button, ThemeProvider } from '@keboola/design';
+
+import { AuthScreen } from './AuthScreen';
+
+// The provider is required, not scenery: the header's `ColorModeToggle` reads the scheme through
+// `useTheme`, and `BrandLogo` renders nothing without a brand registered.
+const renderScreen = () =>
+  render(
+    <ThemeProvider brands={[keboola]} defaultBrandId={keboola.id} defaultScheme="light">
+      <AuthScreen title="Sign in">
+        <Button>Continue</Button>
+      </AuthScreen>
+    </ThemeProvider>,
+  );
+
+describe('<AuthScreen />', () => {
+  it('carries the page heading at h1', () => {
+    renderScreen();
+
+    expect(screen.getByRole('heading', { level: 1, name: 'Sign in' })).toBeInTheDocument();
+  });
+
+  it('keeps the colour-scheme control inside the header landmark', () => {
+    // The control is positioned away from the lockup, so its landmark is what can silently
+    // regress — outside one, axe reports it as unreachable by landmark navigation.
+    renderScreen();
+
+    expect(screen.getByRole('banner')).toContainElement(
+      screen.getByRole('button', { name: /^Color mode:/ }),
+    );
+  });
+
+  it('renders the card body inside the main landmark', () => {
+    renderScreen();
+
+    expect(screen.getByRole('main')).toContainElement(
+      screen.getByRole('button', { name: 'Continue' }),
+    );
+  });
+});

package/dist/template/src/auth/AuthScreen.tsx

@@ -0,0 +1,43 @@
+import type { ReactNode } from 'react';
+
+import { BrandLogo, Card } from '@keboola/design';
+
+import { ColorModeToggle } from '../components/ColorModeToggle';
+
+// Must stay a top-level single-quoted `const`: `create-keboola-app` (`parameterise` in
+// `extract.ts`) rewrites it to the generated app's title.
+const PRODUCT = '__APP_TITLE__';
+
+/**
+ * The chrome every pre-project screen shares: brand lockup, one centred card, no navigation.
+ *
+ * - Renders instead of `AppChrome`; `routes/__root.tsx` picks via `useIsAuthRoute`.
+ * - Sets `tailwindcss-preflight` and `text-foreground` itself: a real app mounts it above the router.
+ * - The toggle sits in `header` so axe finds it inside a landmark.
+ * - `variant="mark"` + text name: the wordmark would repeat the brand; the name survives a `null` logo.
+ */
+export function AuthScreen({ title, children }: { title: string; children: ReactNode }) {
+  return (
+    <div className="tailwindcss-preflight tw:relative tw:flex tw:min-h-screen tw:flex-col tw:items-center tw:justify-center tw:gap-6 tw:bg-muted tw:px-4 tw:py-12 tw:text-foreground">
+      <header>
+        <div className="tw:flex tw:items-center tw:gap-3">
+          <BrandLogo variant="mark" className="tw:h-8" />
+          <span className="tw:text-lg tw:font-semibold">{PRODUCT}</span>
+        </div>
+
+        <div className="tw:absolute tw:top-4 tw:right-4">
+          <ColorModeToggle />
+        </div>
+      </header>
+
+      <main className="tw:w-full tw:max-w-md">
+        <Card>
+          <Card.Header layout="stack">
+            <Card.Title as="h1">{title}</Card.Title>
+          </Card.Header>
+          <Card.Content className="tw:flex tw:flex-col tw:gap-4">{children}</Card.Content>
+        </Card>
+      </main>
+    </div>
+  );
+}

package/dist/template/src/auth/session.test.tsx

@@ -0,0 +1,64 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { AuthState } from './session';
+import { AUTH_STATES, isAuthState } from './session';
+
+const renderState = (state: AuthState, onRetry = () => {}) => {
+  const { body: Body } = AUTH_STATES[state];
+  return render(<Body onRetry={onRetry} />);
+};
+
+describe('AUTH_STATES', () => {
+  it('asks for a credential when signed out', () => {
+    renderState('signed-out');
+
+    expect(screen.getByLabelText(/Email/)).toBeInTheDocument();
+    expect(screen.getByLabelText(/Password/)).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Sign in' })).toBeInTheDocument();
+  });
+
+  it('announces the wait while restoring', () => {
+    renderState('restoring');
+
+    // The wait resolves without the reader acting, so the region has to be live.
+    const message = screen.getByText(/still signed in/);
+    expect(message.closest('[aria-live="polite"]')).not.toBeNull();
+  });
+
+  it.each([
+    ['expired', 'Sign in again'],
+    ['unavailable', 'Try again'],
+  ] as const)('lets the reader retry from %s', async (state, action) => {
+    const user = userEvent.setup();
+    const onRetry = vi.fn();
+    renderState(state, onRetry);
+
+    await user.click(screen.getByRole('button', { name: action }));
+
+    expect(onRetry).toHaveBeenCalledOnce();
+  });
+
+  it('distinguishes an expired session from an unreachable service', () => {
+    // Telling someone their session expired while the network is down sends them to re-enter a
+    // password that would have worked, so the two copies must not converge.
+    const { unmount } = renderState('expired');
+    expect(screen.getByText(/session ended/)).toBeInTheDocument();
+    unmount();
+
+    renderState('unavailable');
+    expect(screen.getByText(/could not reach the service/)).toBeInTheDocument();
+  });
+});
+
+describe('isAuthState', () => {
+  it('accepts every declared state and nothing else', () => {
+    for (const state of Object.keys(AUTH_STATES)) expect(isAuthState(state)).toBe(true);
+
+    expect(isAuthState('signedout')).toBe(false);
+    expect(isAuthState(undefined)).toBe(false);
+    // `Object.hasOwn` rather than `in`, so a prototype key is not a state.
+    expect(isAuthState('toString')).toBe(false);
+  });
+});

package/dist/template/src/auth/session.ts

@@ -0,0 +1,42 @@
+import type { ComponentType } from 'react';
+import { useRouterState } from '@tanstack/react-router';
+
+import { Expired, Restoring, SignInForm, Unavailable } from './states';
+
+/** Keep in sync with the literal in `createFileRoute` — TanStack's generator needs source text. */
+export const AUTH_ROUTE = '/signed-out';
+
+/**
+ * Whether the router is on the signed-out screen.
+ *
+ * - Selects the boolean, so moving between chromed routes does not re-render the root.
+ * - A real app asks its session instead; the path only makes the screen reachable without a backend.
+ */
+export const useIsAuthRoute = (): boolean =>
+  useRouterState({ select: (state) => state.location.pathname === AUTH_ROUTE });
+
+/** One pre-project state: the card's heading, and the body that goes under it. */
+type AuthStateView = {
+  title: string;
+  /** `onRetry` returns the screen to the sign-in form. */
+  body: ComponentType<{ onRetry: () => void }>;
+};
+
+/**
+ * The pre-project states, keyed by the session status that produces each.
+ *
+ * - `AuthState` derives from the keys: a state added here is accepted and rendered by the route.
+ * - Components, not render functions, so this module holds no JSX.
+ */
+export const AUTH_STATES = {
+  'signed-out': { title: 'Sign in', body: SignInForm },
+  restoring: { title: 'Restoring your session', body: Restoring },
+  expired: { title: 'Session expired', body: Expired },
+  unavailable: { title: 'Cannot reach the service', body: Unavailable },
+} as const satisfies Readonly<Record<string, AuthStateView>>;
+
+export type AuthState = keyof typeof AUTH_STATES;
+
+/** Narrows an unvalidated search param. */
+export const isAuthState = (value: unknown): value is AuthState =>
+  typeof value === 'string' && Object.hasOwn(AUTH_STATES, value);

package/dist/template/src/auth/states.tsx

@@ -0,0 +1,70 @@
+import { Alert, Button, DotsLoader, useAppForm } from '@keboola/design';
+
+type AuthStateProps = { onRetry: () => void };
+
+/**
+ * The credential form — the one part that differs per app.
+ *
+ * - `onSubmit` reaches no network; each app replaces its body with its own auth.
+ */
+export const SignInForm = () => {
+  const form = useAppForm({
+    defaultValues: { email: '', password: '' },
+    onSubmit: async ({ value }) => {
+      await Promise.resolve(value);
+    },
+  });
+
+  return (
+    <form.AppForm>
+      <form.FormBody>
+        <form.AppField name="email">
+          {(field) => <field.TextField label="Email" type="email" required />}
+        </form.AppField>
+        <form.AppField name="password">
+          {(field) => <field.PasswordField label="Password" required />}
+        </form.AppField>
+        <form.SubmitButton className="tw:w-full">Sign in</form.SubmitButton>
+      </form.FormBody>
+    </form.AppForm>
+  );
+};
+
+/** A persisted session being rehydrated. */
+export const Restoring = () => (
+  <div
+    className="tw:flex tw:items-center tw:gap-3 tw:text-sm tw:text-muted-foreground"
+    aria-live="polite"
+  >
+    <DotsLoader />
+    Checking whether you are still signed in.
+  </div>
+);
+
+/** A credential that was accepted once and is not any more. */
+export const Expired = ({ onRetry }: AuthStateProps) => (
+  <>
+    <Alert variant="warning">
+      Your session ended. Sign in again to pick up where you left off.
+    </Alert>
+    <Button variant="primary" className="tw:w-full" onClick={onRetry}>
+      Sign in again
+    </Button>
+  </>
+);
+
+/**
+ * The service could not be reached, so the credential was never judged.
+ *
+ * - Not `Expired`: that would send the user to re-enter a password that works.
+ */
+export const Unavailable = ({ onRetry }: AuthStateProps) => (
+  <>
+    <Alert variant="error">
+      We could not reach the service. Your credentials are fine — the request never got an answer.
+    </Alert>
+    <Button variant="outline" className="tw:w-full" onClick={onRetry}>
+      Try again
+    </Button>
+  </>
+);

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

@@ -13,10 +13,8 @@ import { AssistantToggle } from './AssistantToggle';
 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`.
+// Composed inline so the AppShell/Navbar/Sidebar wiring stays legible.
+// Navbar follows kbc-ui's AppSiteHeader: Header (brand) / Content (nav) / Footer (actions).
 export function AppChrome({ children }: { children: ReactNode }) {
   const pathname = useRouterState({ select: (s) => s.location.pathname });
   const helpVisible = useAppStore((s) => s.helpVisible);
@@ -29,62 +27,39 @@ export function AppChrome({ children }: { children: ReactNode }) {
 
   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.
+      // Controlled: the store owns the persisted mode; `SidebarModeMenu` 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.
+      // Keeps every destination reachable; also what `expand-on-hover` collapses to.
       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.
+      // Required: variant `none` (the default) renders nothing, silently.
       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).
+      // Closed until the Navbar's AssistantToggle opens it.
       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.
+      // The provider default is too narrow for chat; matches kbc-ui's Kai rail.
       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. */}
+      {/* Header above both rails, so the brand mark aligns to the viewport edge. */}
       <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. */}
+        {/* `flush` drops padding, background and bottom border; the border is restated:
+            - It closes the frame the rails' hairlines start.
+            - `sidebar-border`, not `border`: they meet at the corners, `border` is 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. */}
+          {/* As a flex item the bar would otherwise shrink to its content. */}
           <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. */}
+            {/* Gutter here, not on `Navbar`: the bar's `pl-2` comes from a cva, which doesn't
+                tailwind-merge. With it the logo sits at 18px, aligned with the rail's icons. */}
             <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. */}
+            {/* Carries `flex-1`, pushing Navbar.Footer to the right edge. */}
             <Navbar.Content>
               <Navbar.Menu marker="forward-slash">
                 <Navbar.MenuItem>
@@ -113,31 +88,20 @@ export function AppChrome({ children }: { children: ReactNode }) {
         </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. */}
+          {/* Elevation while `expand-on-hover` is open: the rail overlays the page.
+              - App-scoped, not a `Sidebar` variant: kbc-ui paints `::before`/`::after` wedges on
+                that edge. Promote once reviewed there. */}
           <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. */}
+              {/* The rail's landmark (axe); labelled apart from the Navbar's "Main navigation". */}
               <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. */}
+                      {/* A link takes `aria-current`, not `aria-selected`. */}
                       <Sidebar.MenuButton
                         asChild
                         tooltip={item.label}
@@ -156,8 +120,7 @@ export function AppChrome({ children }: { children: ReactNode }) {
               </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. */}
+            {/* Footer, not Content: `Sidebar.Content` scrolls, the footer is pinned. */}
             <Sidebar.Footer>
               <Sidebar.Menu>
                 <SidebarModeMenu />
@@ -168,23 +131,12 @@ export function AppChrome({ children }: { children: ReactNode }) {
 
         <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. */}
+        {/* The assistant rides every route, one instance per mode:
+            - Normal: the right rail.
+            - Fullscreen: a fixed overlay after AppShell, no rail; exit returns to the page. */}
         {!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.
+          // `Sidebar` brings width, border, scroll and resize; `flush` avoids a second surface.
+          // `styles.css` clips this slot while collapsed; without that rule, add `overflow-x-clip`.
           <AppShell.Aside flush>
             <Sidebar side="right" container resizable>
               <AssistantPanel />

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

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react';
-import type { RefObject } from 'react';
+import type { CSSProperties, RefObject } from 'react';
 
 import { Button } from '@keboola/design';
 
@@ -78,8 +78,15 @@ export function SelectionFloater({
     <Button
       variant="secondary"
       size="small"
-      className="tw:fixed tw:z-50"
-      style={{ top: selection.top - 40, left: selection.left }}
+      className="tw:fixed tw:top-(--floater-top) tw:left-(--floater-left) tw:z-50"
+      // Custom properties, not inline `top`/`left`: the utilities above read them,
+      // and the position is measured from the live selection at runtime.
+      style={
+        {
+          '--floater-top': `${selection.top - 40}px`,
+          '--floater-left': `${selection.left}px`,
+        } as CSSProperties
+      }
       onClick={handleClick}
     >
       Explain with Kai