Multi-Tab & Cross-Sheet Modeling

Kalc provides multi-sheet computational modeling. Variables declared on any sheet in your workspace can be imported, transformed, and composed on any other sheet in real time.

---

The Cross-Tab Reference Syntax (Tab@var)

To reference a variable defined in another tab, type the tab's identifier or title, followed by @, and then the variable name:

// On 'Summary' tab:
net_profit = Revenue@total - Expenses@total     // $42,500.00
tax_due = net_profit * TaxConfig@standard_rate  // $8,500.00

Supported Syntax Styles

Style	Syntax Example	When to Use
Index Aliases	Tab1@tax_rate, Sheet2@subtotal	Quick references based on sheet tab order (1-indexed).
Exact Sheet Titles	Expenses@total, Payroll@net	Clear, readable references matching tab names.
Hyphenated Titles	2024-Budget@tax, Long-Term@horizon	Names with hyphens (lexed safely without subtraction ambiguity).
Spaced Unquoted Titles	Sheet 1@total, Project Alpha@cost	Convenient multi-word sheet titles.
Quoted Titles	'Q1 Planning'@net, "Tax 2026"@net	Complex titles containing special characters or punctuation.
Normalized Slugs	financialmodel@tax	Matches sheet titled "Financial Model" regardless of casing.

---

Editor & UI Integration

1. Interactive Boxed Badges

When you type a cross-tab reference, Kalc formats the TabName@ prefix as an interactive rounded pill badge in the editor. This clearly distinguishes external sheet inputs from local variables.

2. Autocomplete @ Trigger

Typing @ anywhere in the editor immediately triggers the suggestion popup, listing every variable currently exported by other open sheets. Selecting an item replaces @ with the full SheetName@variable reference.

3. Cross-Tab "Go to Declaration" (⌘-Click)

Holding ⌘ and hovering over any cross-tab badge underlines the symbol and turns your cursor into a pointing hand. Clicking it immediately switches to the referenced tab, highlights the definition line, and places the cursor at the declaration.

4. Floating Value Inspector

Hovering your mouse over any cross-tab reference displays a floating HUD badge showing the current evaluated value, the source sheet name, and its formatting.

5. Reactive Tab Flashing

When you edit an upstream variable on Tab 1, all downstream sheets referencing Tab 1's variables recalculate in the background. In the top tab bar, referencing tabs pulse with a subtle amber/mint flashing animation to notify you of updated calculations.

---

Workspace Architecture & Dependency DAG

Cross-sheet computation is orchestrated by WorkspaceCoordinator, a dedicated Swift actor.

graph LR
    A[Tab 1: Assumptions] --> B[Tab 2: Operations]
    A --> C[Tab 3: Marketing]
    B --> D[Tab 4: Consolidated P&L]
    C --> D

Topological Dependency Closure

When you view or edit a tab:

1. WorkspaceCoordinator computes the directed dependency closure.
2. Prerequisite sheets are evaluated topologically before the active sheet.
3. Live variables are injected into the active sheet's Scope via CrossTabResolver.

Deterministic Cycle Detection

If tabs form a circular dependency loop (e.g., Tab A -> Tab B -> Tab A), Kalc terminates recursion before evaluation:

• Emits a non-fatal, structured diagnostic on the referencing line:

  ⚠️ Circular dependency detected: Tab 1 -> Tab 2 -> Tab 1

• Protects the engine from deadlocks, infinite loops, and application crashes.

---

Multi-Tab Chrome & Navigation

Dual-Mode Top Bar

• Single-Tab Mode: When only one tab is open, the redundant tab bar hides completely. A centered HeaderTitleLabel displays the scratchpad or file title, paired with a right-aligned + button (⌘ T).
• Multi-Tab Scrollable Mode: When two or more tabs exist, TabBarView activates with a 76 pt left margin preserving native macOS window traffic lights.

Smooth Horizontal Scrolling

When many tabs overflow the window width:

• The tab bar scrolls smoothly with trackpad or mouse-wheel gestures.
• A persistent 2px thin scroller displays your position without visual clutter.
• Auto-Scroll: Navigating or clicking to an off-screen tab automatically scrolls the viewport to reveal it.

Isolated Undo & Selection Stacks

Each document tab maintains its own independent UndoManager and cursor selection range. Switching between tabs never resets, corrupts, or blends your edit history.

Tab Naming State Machine

• Scratchpad: A new, single untitled window begins as "Scratchpad".
• Automatic Numbering: Opening a second tab automatically renames the first to "Tab 1" and creates "Tab 2".
• File Persistence: Tabs opened from existing .kalc files on disk retain their true file names permanently.
• Restoration: Closing tabs down to a single untitled tab gracefully restores the name "Scratchpad".