Ribbon

Design axioms

1. Account first, off the ribbon. Open / save / sign in / protect live in the profile menu (top right). The ribbon is for the current structure, not document identity.
2. Split by intent, not by implementation.
   • Insert — create something that did not exist. The Insert section opens a metasheet of Table, Dictionary, List, Grid, checkbox, file, … This is the default tab.
   • Table / Dictionary / List / Pivot Table / Chart / Grid — the last tab. Named for the structure you are inside. Transform that structure (transpose, totals, convert).
   • Formulas — the calculation language, defined names, and engine mode.
   • Queries — saved API connections; refresh is explicit.
   • Data — arrange or clean values that already exist (sort, filter, validation, find, import/export).
   • Forms — questions that append a record. A new table can be generated, or an existing table receives the rows. A field can show or hide from an earlier answer.
   • Access — users, nested groups, and who may view / edit / grant on a structure.
   • Format / Type — live on field menus (header ☰), not a ribbon tab.
3. One structure tab, last in the column. Labeled with the type you are in (Table, Dictionary, List, Pivot Table, Chart, Grid), not “Structure”. Insert stays selected until you open that tab.
4. Hard buttons. After you pick a tab, the ribbon shows command buttons (Insert, Formulas, Commands) or section menus (Data). Keytips: Alt, I, T still runs Table.
5. Hide sheet-redundant chords. Settings can hide ribbon commands that already have Ctrl shortcuts (Find, Replace, …). Keytip-only commands stay.
6. Honesty. If it isn’t real, it isn’t on the ribbon. Prefer empty surface over fake buttons.
7. Keytips. Alt (release alone) → tab letter → section letter → command letter (flat tabs skip section). Badges on ribbon; letter underlines only on field dropdowns. Arrows exit keytips and move the selector.

Tab order (left → right)

Top bar (always visible): Undo / Redo, dotted path (workbook name through the current cell), profile menu (sheets, settings, protect). Formula bar sits under the top bar, right of the ribbon column. Profile keytip P. Help /.

Profile menu · Alt, P

Job: which workbook, how it’s stored, who can change it. Not a ribbon tab — the avatar at the top right.

Autosave is always on. Export / Import live on the Data tab. Clipboard, fill, and insert/delete row & column are keyboard + sheet chrome (Ctrl+C/X/V, Ctrl+D, Ctrl++/-, Delete on gutters/headers).

Insert · Alt, I

Job: create new structures or objects in the selected cell. The Insert section is one button that opens a metasheet of those commands. Keytips: Alt, I, then the letter (T table, D dictionary, …).

Formulas · Alt, M

Job: author and control calculation — not data layout.

Library

Calculation

Queries · Alt, Q

Job: saved API connections in the workbook. Fetch is explicit — nothing auto-refreshes.

Data · Alt, D

Job: rearrange, constrain, seed, or move data. Section menus (not a flat column).

Sort & filter

Quality

Get data

Forms · Alt, F

Job: collect answers and append them as one record. Pick an empty cell, then New form. Save into a new table (generated beside the form, or stored on the form when the next cell is taken) or an existing table. Space opens the form.

Show when reads another field: is, is not, is empty, is not empty, or contains. If that field is itself hidden, this one stays hidden too. A generated table grows a column when you add or rename a field. Removing a field leaves the column, so earlier answers stay put.

Access · Alt, A

Job: who the workbook knows, how they cluster, and who may view / edit / grant on a structure. Flat buttons. Only people with Grant Access on a structure can open Permissions for it (and they only see that structure). Users and Groups require Grant Access on the workbook root (or owner).

Structure ▸ Access… still opens Permissions. Nested structures inherit; Add path writes an override for that path (named like the workbook, e.g. Untitled.Budget). Field ☰ has an Access section (View / Edit / Grant). You cannot remove yourself from Users or Admin.

Format & Type · field menu ☰

Not a ribbon tab. Open the field menu on a table header, dictionary Name cell, list Value header, or transposed field gutter. Hotkey letters are underlined here (no keytip badges).

• Type (T) — Any, Field, Value, Structure, File, Toggles (T), and Unique identifier. Field sources allowed values from a list or table column. Picking a type closes the menu.
• Format — follows the current type (number/date codes, font/alignment). Conditional formatting: two color scales (one inverted) and highlight duplicates. Column fit and Hide field live here. On a table whose field headers are the top row, Column fit opens Auto / Auto (column name) / Manual.
• Filter / Sort — same menu.
• Access — View / Edit / Grant access for this field (who may see or change the column). Nested paths inherit workbook rules unless you add a path in Permissions.

View

There is no View tab. Status aggregates already sit in the status bar. Freeze / zoom / gridlines are not implemented, so they are not advertised.

Structure tab · last in the column

One contextual tab, labeled with the type you are in (Table, Dictionary, Field, Pivot Table, Chart, Grid, Form). It is the last tab. Insert stays selected until you open it. Contents follow type. Field’s keytip is E because Forms uses F. The Form tab’s keytip is R.

Why a separate tab? “Transpose” on a list is nonsense; “Insert column” on a list is noise. This tab keeps power tools next to the geometry they act on.

Grid

• Access… — opens Permissions for this grid (same as Access tab → Permissions).
• Cleanup — used range becomes a table (header row) or dictionary (two-column keys).

Table

• Transpose — fields ↔ records; formulas keep field names with same-record trailing dots.
• Show fields — hide a subset without deleting them (formulas still see every field; also field ☰ → Hide field).
• Total record — sum/avg/min/max before headers (or left when transposed); linked table fields stack.
• Lock formulas — share nested field formulas (schema already syncs). Greyed unless the selection is a nested-table field.
• Access…
• Convert to list / dictionary — enabled when the table has one field or one record.

List / Dictionary

• Convert to table (honors records-as-columns pref); numbered ↔ dictionary; Name/Value table for dictionaries.
• Access…

Pivot

• Fields — Field list (Filters / Columns / Rows / Values). Value cells show aggregate formulas in the formula bar.
• Source — Jump to source table; refresh.

What is deliberately not on the ribbon

• File / Home / View tabs. Document identity is the profile menu. Clipboard, fill, and row/column geometry are keyboard + gutters/headers.
• Format tab. Display formats live on field menus so Format isn’t a second home for number codes.
• Hide / Unhide sheet. Not a multi-sheet Excel model. Collaboration “hide” is Access on structures.
• Enter / edit formula. Formula bar and keyboard (=, F2).
• Dive / surface. Space / Esc.
• Undo / Redo. Top bar (and Ctrl+Z/Y).

Workflows (end-to-end)

Each workflow lists the ribbon path a new user should find without hunting. Keyboard-only alternatives in parentheses.

1. Start a new cloud workbook

1. Profile → Sign in…
2. Profile → My sheets → New cloud sheet
3. Autosave writes as you edit (Ctrl+S also saves)

2. Resume yesterday’s work

1. Profile → My sheets → open
2. Or Data → Import → Local file… for a JSON backup

3. Build a nested budget (list of tables)

1. On a list value cell: Insert → Table (section button) or Space → Table
2. Space into the table → Structure tab appears
3. Select a header → Ctrl++ inserts a field; a data row inserts a record (or type in the growth row)
4. Type =Q1.+Q2. on a header as a field formula
5. Esc up; repeat for next list item

4. Lock nested table formulas

1. Parent table with a field of nested tables
2. Structure → Lock formulas
3. Edit one subtable’s headers/formulas → siblings sync fields; lock also shares formulas

5. Sort and filter a table

1. Inside the table, or from anywhere on a table/list: Data → Sort & filter → Sort A→Z / Filters
2. Header Space also opens sort/filter/validation without the ribbon
3. To hide fields (not records): field ☰ → Hide field, or Structure → Show fields

6. Validate a column against a list

1. Data → Sort & filter → Validation…
2. Allow values from another list’s value column
3. On a validated cell, Space picks an allowed value

7. Transpose records and fields

After transpose, Delete/paste on data still only clear/overwrite; use field gutters or record headers to change structure.

1. Open a table (Space)
2. Structure → Transpose
3. Former rows become columns; former headers become the Field column; first-column labels name record columns when useful
4. Undo if the shape was wrong

8. Pivot a table into a summary

1. Open a table (or select the cell that holds one)
2. Insert → Pivot table
3. A pivot object is inserted as a sibling: one column to the right (table/grid parent) or the next list item below (list parent)
4. It is named “{source name} Pivot” (e.g. Transcript → Transcript Pivot)
5. Defaults: group by the leftmost column that has duplicates; sum the rightmost numeric column
6. Space to open — use the Pivot contextual ribbon to add/remove group, value, and filter fields

9. Chart numeric data

1. Select table or list with numbers
2. Insert → Chart

10. Format currency on a whole column

1. Select the table header cell for that column
2. Field ☰ → Format → Currency
3. Values stay raw; formula bar still shows the model value

11. Author and call a LAMBDA

1. In a cell (e.g. list index f): =LAMBDA(x, y, x+y)
2. Cell shows λ(x, y)
3. In another cell: =f(a, b) if a/b are sibling names, or =f(1, 2), or =#myLam(3) for a defined name
4. Inline: =LAMBDA(x, x*2)(5)
5. Discover functions: Formulas → Library

12. Name a cell and reuse it

1. Select the cell
2. Formulas → Defined names → add
3. Reference as #name (or bare name when unambiguous)

13. Manual calc for a heavy sheet

1. Formulas → Calculation: Auto (toggles to Manual)
2. Edit freely; press F9 or Recalc all when ready

14. Find / replace across the tree

1. Data → Find → Find (Ctrl+F)
2. Replace is same menu (current structure scope)

15. Import Excel into the tree

1. Select the destination cell
2. Data → Import → Local file… → choose .xlsx
3. Excel becomes a Dictionary of sheets (grids; tables only when purely tabular with calc-column formulas)

16. Export a backup

1. Data → Export → Download JSON

17. Protect against accidental edits

1. Profile → Protect sheet
2. Same command unprotects (Alt, P, R)

18. Stress-test virtualization

1. Data → Get data → Load 5k-row grid

19. Debug a wrong ref

1. Formulas → Recalc all after a stuck cache suspicion

20. Multi-user limited access

1. Access → Users — add people by email
2. Access → Groups — make Engineering, then a Backend subgroup inside it
3. Open Finance (or another nested structure) → Access → Permissions (or Structure → Access…)
4. Uncheck Inherit. Grant View to Engineering, Edit to Backend, Grant Access only to a lead
5. Access → View as… that lead / an engineer to preview. Navigation refuses restricted nodes. JSON export still contains everything (live view, not a confidentiality boundary)

21. Clipboard round-trip with Excel

1. Select range → Ctrl+C
2. Paste into Excel as TSV; or paste from Excel into Metagrid
3. Ctrl+Shift+V paste values when you want constants only (formula results that are lists or tables paste as those structures, not chip labels)

22. Build a form-like list with validation

1. List of items; one cell per row is a nested small table or validated field
2. Data → Sort & filter → Validation… → from a master options list
3. Space on the cell to pick

Keytips (three levels)

1. Tab — letter on each tab (Structure S, Insert I, Formulas M, Queries Q, Data D, Access A). Profile P.
2. Section — letter on each dropdown (Data only: Sort & filter, Find, Get data, Import, Export). Flat tabs skip this level.
3. Command — letter on the button or inside the open menu. Esc steps back one level.

Example: Table = Alt, I, T. Filters = Alt, D, S, F. Protect = Alt, P, R.

Alt → tabs
  S → Structure (flat; contents follow type)
    T Transpose / F Show fields / O Total record / H Lock formulas / A Access / …
  I → Insert (flat)
    T Table / D Dictionary / L List / G Grid / K Checkbox / F File / B Button / P Pivot / C Chart
  M → Formulas (flat)
    L Library / N Names / C Calculation / R Recalc / then catalog sections
  Q → Queries (flat)
    M Manage / A From API / R Refresh / L Refresh all
  D → Data (menus)
    S Sort & filter → S A→Z / Z Z→A / F Filters / V Validation
    F Find → F Find / H Replace
    G Get data → T Sample table / B 5k grid
    I Import · E Export
  A → Access (flat)
    U Users / G Groups / P Permissions / W View as
  P → Profile
    M My sheets / S Settings / R Protect / W View as / K shortcuts
  / → Help (from tab level)

Implementation notes

• Config: projects/metagrid/js/ui/ribbon.js — RIBBON + CONTEXT_RIBBON.
• Commands: js/ui/commands.js CMDS + cloud overrides in cloud.js.
• No stub buttons. A missing CMDS entry still toasts, but the ribbon only lists real commands.
• Menus use fixed positioning above the formula bar; close on outside click, Esc, command, tab change.