Skip to content

Dock navigation

Stable Available in release assets

Present a compact group of peer workspace tools as ordinary destinations rather than desktop-style launch mechanics.

Dock navigation in context

Show code
<nav class="thin-dock-navigation" aria-label="Workspace tools">
  <ul>
    <li><a href="/app/files/">Files</a></li>
    <li><a href="/app/editor/" aria-current="page">Editor</a></li>
    <li><a href="/app/preview/">Preview</a></li>
  </ul>
</nav>

Each authored example uses the production assets and includes copyable markup.

Compact navigation

Named landmarks and ordinary destination links form the default composition.

Show code
<nav class="thin-dock-navigation" aria-label="Workspace tools">
  <ul>
    <li><a href="/app/files/">Files</a></li>
    <li><a href="/app/editor/" aria-current="page">Editor</a></li>
    <li><a href="/app/preview/">Preview</a></li>
  </ul>
</nav>

Long labels

Localized link labels wrap without removing destinations.

Show code
<nav class="thin-dock-navigation" aria-label="Workspace tools">
  <ul>
    <li><a href="/app/files/">Projektübersicht mit ausführlichen Informationen zu internationalen Arbeitsbereichen</a></li>
    <li><a href="/app/editor/" aria-current="page">Editor</a></li>
    <li><a href="/app/preview/">Preview</a></li>
  </ul>
</nav>

RTL navigation

Authored direction changes presentation while source order stays intact.

Show code
<div dir="rtl">
  <nav class="thin-dock-navigation" aria-label="Workspace tools">
    <ul>
      <li><a href="/app/files/">Projektübersicht mit ausführlichen Informationen zu internationalen Arbeitsbereichen</a></li>
      <li><a href="/app/editor/" aria-current="page">Editor</a></li>
      <li><a href="/app/preview/">Preview</a></li>
    </ul>
  </nav>
</div>

Constrained container

A local container retains every destination at narrow and wide widths.

Show code
<div style="inline-size: min(100%, 18rem)">
  <nav class="thin-dock-navigation" aria-label="Workspace tools">
    <ul>
      <li><a href="/app/files/">Projektübersicht mit ausführlichen Informationen zu internationalen Arbeitsbereichen</a></li>
      <li><a href="/app/editor/" aria-current="page">Editor</a></li>
      <li><a href="/app/preview/">Preview</a></li>
    </ul>
  </nav>
</div>

Anatomy

  • Uniquely named navigation landmark
  • Semantic destination list
  • Ordinary links
  • Text current-page state
  • Durable in-flow fallback

Variants and sizes

  • Compact — shown above
  • Long localized labels — shown above
  • Right-to-left — shown above
  • Narrow and wide containers — shown above

Rendered fixtures exercise authored content and constrained layouts with the same production assets.

Current destination

Only the server-authored current destination has aria-current=page.

Show code
<nav class="thin-dock-navigation" aria-label="Workspace tools">
  <ul>
    <li><a href="/app/files/">Files</a></li>
    <li><a href="/app/editor/" aria-current="page">Editor</a></li>
    <li><a href="/app/preview/">Preview</a></li>
  </ul>
</nav>

Long labels and RTL

Localized link content keeps ordinary list and navigation semantics.

Show code
<div dir="rtl">
  <nav class="thin-dock-navigation" aria-label="Workspace tools">
    <ul>
      <li><a href="/app/files/">Projektübersicht mit ausführlichen Informationen zu internationalen Arbeitsbereichen</a></li>
      <li><a href="/app/editor/" aria-current="page">Editor</a></li>
      <li><a href="/app/preview/">Preview</a></li>
    </ul>
  </nav>
</div>

Optional pending state

An application may describe a pending refresh without disabling durable links.

Show code
<nav aria-busy="true" class="thin-dock-navigation" aria-label="Workspace tools">
  <ul>
    <li><a href="/app/files/">Files</a></li>
    <li><a href="/app/editor/" aria-current="page">Editor</a></li>
    <li><a href="/app/preview/">Preview</a></li>
  </ul>
  <p role="status">Navigation is updating. Existing destinations remain available.</p>
</nav>
  • Default — documented, example pending
  • Current destination — shown above
  • Long labels — shown above
  • Narrow container — documented, example pending
  • Wide container — documented, example pending
  • Right-to-left — shown above
  • 200 and 400 percent zoom — documented, example pending
  • Optional pending application state — shown above

Interaction and keyboard behavior

Links perform normal document navigation. Optional Datastar enhancement may refresh server-owned counts or current state but must preserve href values, source order, focus, and returned server truth.

Accessibility

Use nav with a distinct accessible name, lists and ordinary links in logical order, aria-current only for the current destination, visible focus, and touch targets at least the shared control size.

Contract
NATIVE
Basis
Native labelled navigation and links; disclosure or dialog behavior must be explicit when added
Evidence
  • tests/browser/navigation-promotion-runtime.spec.ts
  • tests/browser/navigation-promotion.spec.ts
  • tests/unit/library/application-navigation.test.ts

API

Use nav.thin-dock-navigation with semantic lists and durable href values. Presentation never changes source or focus order. For optional Datastar morphs, keep stable IDs on the navigation region and retained links, preserve durable href values, and let the server author current and pending state.

Behavior tier: datastar-optional

Structured host, property, and example tables are not authored for this item yet. Use the summary above and the primary example.

Fallback

Every destination remains an ordinary link in a named navigation landmark without CSS, JavaScript, or optional application-state enhancement.

Assets and dependencies

  • /foundation.css
  • /layouts.css
  • /components.css

Dependencies: None

Source: packages/ui/src/items/application-navigation/style.ts

Stability evidence

  • Item-specific API, optional dependency and complete variant/state contract: test:tests/unit/library/navigation-promotion.test.ts
  • Native no-JS destinations, keyboard activation, semantic accessibility, target size and difficult-environment screenshots: test:tests/browser/navigation-promotion.spec.ts
  • Pinned standalone/starter Datastar SSE, server error, retry, cancellation, stale-response and retained-focus contract: test:tests/browser/navigation-promotion-runtime.spec.ts