astrolabe/docs/spec/01-application-shell.md

# 01 · Application Shell & Navigation

This section describes the overall workspace structure, the header toolbar, the modal system, keyboard shortcuts, URL-based navigation, transient notifications, and the offline/installable nature of the app. Feature-specific behavior lives in the sections referenced inline.

## A. Workspace Layout

Astrolabe is a single-screen workspace. Below a fixed top header sits a three-pane working area, each pane dedicated to one part of the snippet-editing workflow:

- **Snippet library** (left) — browse, search, select, and manage saved snippets (see _Snippet Library_).
- **Spec editor** (center) — edit the Vega-Lite spec of the selected snippet (see _Spec Editor & Draft/Published Workflow_).
- **Live preview** (right) — render the current spec (see _Live Preview_).

Behavior:

- All three panes are visible by default, laid out side by side in the order library, editor, preview.
- Adjacent panes are separated by a vertical drag handle. The user can drag a handle left/right to resize the two panes it sits between; the rest of the layout is unaffected.
- Each pane enforces a minimum width while resizing, so a pane cannot be dragged to nothing.
- Each pane can be individually shown or hidden via a persistent **toggle strip** (a narrow vertical strip of toggle buttons, one per pane, each indicating whether its pane is currently shown). The toggle strip also contains a shortcut button that opens the Datasets manager.
- When a pane is hidden, the remaining visible panes expand to fill the freed space, redistributing proportionally to their remembered widths. When a previously hidden pane is shown again, it returns at its remembered width.
- Hiding all panes is permitted; the toggle strip remains available to bring panes back.
- Pane widths and per-pane visibility persist locally across sessions and are restored on next load. The app remembers a pane's preferred width even while it is hidden, so re-showing it restores that width rather than an arbitrary one.

## B. Header / Toolbar

A fixed header spans the top of the app.

- **Left side**: the app icon, the app title ("Astrolabe"), and a version badge showing the current app version.
- **Right side**: a row of text entry points. Each opens a destination:

| Entry point     | Opens                                                                                                           |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| Import          | A file-picker dialog to choose a previously exported file; the chosen file is imported (see _Import & Export_). |
| Export          | Immediately produces a downloaded file containing all snippets and datasets (see _Import & Export_).            |
| Datasets        | The Datasets manager modal (see _Datasets_).                                                                    |
| Settings        | The Settings modal (see _Settings_).                                                                            |
| About & Privacy | The About & Help modal (keyboard shortcuts, about, and privacy information).                                    |
| Donate          | The Donate modal.                                                                                               |

Notes:

- Import and Export act directly (file dialog / file download); they do not open in-app modals.
- The Datasets, Settings, About & Privacy, and Donate entry points each open a modal (see _Modal System_).

## C. Modal System

The app shows at most one modal at a time. The modal set is: Datasets, Settings, About & Help, Donate, Chart Builder, and Extract-to-Dataset.

- Opening any modal closes whichever modal was previously open; the two never overlap.
- Every modal can be dismissed by: clicking its close button, pressing **Escape**, or clicking the backdrop outside the modal body.
- Clicking inside the modal body does not dismiss it.
- The Chart Builder and Extract-to-Dataset modals are opened from within the Datasets / snippet workflows (see _Chart Builder_ and _Datasets_), not from the header.
- Dismissing a modal returns the user to the underlying workspace unchanged.

## D. Keyboard Shortcuts

Shortcuts are platform-aware: the modifier is **Cmd** on Mac and **Ctrl** on other platforms (shown below as Cmd/Ctrl).

| Shortcut             | Action                                                                             |
| -------------------- | ---------------------------------------------------------------------------------- |
| Cmd/Ctrl + Shift + N | Create a new snippet (see _Snippet Library_)                                       |
| Cmd/Ctrl + K         | Toggle the Datasets manager open/closed                                            |
| Cmd/Ctrl + S         | Publish the current snippet's draft (see _Spec Editor & Draft/Published Workflow_) |
| Cmd/Ctrl + ,         | Open the Settings modal                                                            |
| Escape               | Close the active modal                                                             |

Notes:

- Cmd/Ctrl + K is a toggle: if the Datasets manager is already open it closes it; otherwise it opens it.
- Escape only acts when a modal is open; with no modal open it does nothing.
- The shortcut actions override the browser's default behavior for those key combinations.

## E. Navigation & Shareable URL State

The app reflects its current location in the URL hash so that reloading restores the same view and the browser's Back/Forward buttons move between prior states. The user can copy the URL to share or bookmark a specific location.

States and their hash forms:

| State                       | Hash                           |
| --------------------------- | ------------------------------ |
| A selected snippet          | `#snippet-<id>`                |
| Datasets manager (list)     | `#datasets`                    |
| A specific dataset          | `#datasets/dataset-<id>`       |
| New-dataset form            | `#datasets/new`                |
| Chart Builder for a dataset | `#datasets/dataset-<id>/build` |

Behavior:

- Selecting a snippet updates the URL to that snippet; reloading reopens that snippet.
- Opening the Datasets manager updates the URL to `#datasets`; opening a specific dataset, the new-dataset form, or the Chart Builder for a dataset updates the URL to the corresponding form above.
- Browser Back/Forward navigate between these states (e.g. closing a modal via Back returns to the previously selected snippet).
- On load, the app reads the hash and restores the corresponding state (selected snippet, Datasets list, a specific dataset, the new-dataset form, or the Chart Builder).
- An empty/absent hash opens the default snippets view with no modal.

## F. Toast Notifications

Transient toast messages appear in a corner of the screen to confirm actions or report problems, without interrupting the workflow.

- Four kinds, each visually distinct: **success**, **error**, **warning**, **info**.
- Each toast auto-dismisses after a few seconds, and can also be dismissed manually via its close control.
- Multiple toasts stack rather than replacing one another, and appear/disappear with a brief fade.

Events that raise toasts include:

- Snippet actions: creating, duplicating, deleting, publishing a draft, and reverting/discarding a draft.
- Dataset actions: creating, deleting, and extracting inline data into a dataset.
- Import/Export: results of an import (success/partial/failure) and confirmation of an export.
- Errors: spec/data validation failures and local-storage capacity warnings.

## G. Offline & Installable

Astrolabe is local-first and usable without a network connection.

- After the first successful load, the app works fully offline; the interface and previously loaded content remain available with no connection.
- All snippets, datasets, and settings are stored locally and remain accessible offline (see _Data Model_).
- The app is installable as a standalone application from a supporting browser and, once installed, launches in its own window.