tranquil
Docs

Tree-View Controls & Codicons — Delivery Notes

Delivery summary for the feat/treeview-icons work. For the living feature docs, see Pane Controls, the Pane Controls API Reference, and File-Type Icons. This note records what changed and why.

Context

The tree-view (left dock) had no toolbar. Goal: give it its own pane controls — New File · New Folder · Refresh · Collapse All — matching the VS Code look. Two structural gaps blocked it, plus one standardization opportunity:

  1. Pane controls couldn’t show real icons — items rendered btn.textContent = glyph (Unicode only), only injected on center + right docks, and the whole system was gated behind the showBusinessMockups flag.
  2. Our icon set was impoverished — the old Atom-era Octicons mapped file-add, file-directory-create, and plus to the same glyph, so “new file” and “new folder” were indistinguishable.

Decision (with the user): full migration of the tree’s file/folder glyphs to codicons; pane controls become always-on (left-dock support, no placeholder fallback); codicon assets live in tranquil-theme-icons.

What was done

tranquil-theme-icons — codicons as the standard icon set

  • Vendored the font at resources/fonts/codicon.ttf (from @vscode/codicons dist/).
  • Added styles/codicon.less: an @font-face loading the .ttf over atom://tranquil-theme-icons/resources/fonts/codicon.ttf (the app CSP blocks data: fonts and resolves relative url() against static/ — see the Theme Development “Fonts” quirk), followed by the full .codicon-<name> class set lifted verbatim from dist/codicon.css. Loaded globally, so .codicon-* works in tree-view rows and main-DOM pane-control buttons alike.
  • Added a scoped override block in styles/tranquil-theme-icons.less: for each Octicon-style class the tree renders (files via our service, folders via the tree-view’s default classes), a .tree-view .name.<class>::before rule swaps font-family to "codicon" + the matching codepoint. Specificity 0,3,1 beats the Octicon rule (0,1,1) while preserving its font-size: 16px. Expanded directories get the open-folder glyph.
  • No JS change to lib/tranquil-theme-icons.js: the service keeps returning the same class names; only their rendered glyph changed. Colors were untouched (they key off [data-name]).

tranquil-automations — pane controls: icon field, always-on, tree-view controls

  • lib/pane-controls.js: added an icon field (renders <span class="codicon codicon-<icon>">, falling back to glyph); added the left dock to the observed containers and to LOCATIONS; removed DEFAULT_ITEMS so an unmatched pane shows nothing (required now that the system spans every pane).
  • lib/pane-controls-capability.js: forward the new icon field from guest registrations; the untrusted-browser default reload now uses icon: "refresh".
  • lib/tree-view-controls.js (new): registers the four controls, matched to atom://tree-view. New File / New Folder / Collapse All dispatch tree-view:* commands; Refresh calls the active TreeView instance’s updateRoots() (there is no refresh command).
  • lib/mockup-controls.js (new): the business mockups’ controls (reload / scroll-to-top / about) moved off guest RPC self-registration and onto host-side registration by URL — the same trust-independent path as the tree-view controls. Actions run in the page via ctx.executeJavaScript (about shows a host toast). The <script> self-registration blocks were removed from mockups/*.html, and the mockups are excluded from the untrusted-page default reload (pane-controls-capability.js via isMockupUrl) so they don’t get a duplicate button.
  • lib/tranquil-automations.js: the whole pane-controls system now activates unconditionally — paneControls.activate(), treeViewControls.activate(), mockupControls.activate(), registerCapabilities(rpc) (kept so any other trusted page can self-register), and registerDefaultRemoteControls(rpc) (untrusted-page reload). Only opening the business mockups (and addTrustedRoot(MOCKUPS_DIR)) stays behind the flag. Fixes during testing: (1) the RPC wiring was initially left gated behind the flag, dropping controls on custom HTML pages when mockups were off — moved always-on. (2) The mockups’ own controls depended on the page being trusted at load time, which is racy on restart/reload (symptom: only the untrusted-default “refresh” showed) — so they were converted to the host-side system above.

tranquil-rpc + docs

Codicon codepoints used

Tree-view controls: new-file \ea7f · new-folder \ea80 · refresh \eb37 · collapse-all \eac5.

File/folder glyph overrides (Octicon class → codicon): icon-file-code→\eae9 · icon-ruby→\eb48 · icon-terminal→\ea85 · icon-paintcan→\eb2a · icon-markdown→\eb1d · icon-code→\eac4 · icon-settings→\eaf8 · icon-database→\eace · icon-lock→\ea75 · icon-book→\eaa4 · icon-law→\eb12 · icon-file-text→\ea7b · icon-package→\eb29 · icon-tools→\eb6d · icon-git-branch→\ec6f · icon-key→\eb11 · icon-globe→\eb01 · icon-browser→\eaae · icon-diff→\eae1 · icon-file-symlink-file→\eaee · icon-file-zip→\eaef · icon-file-media→\eaea · icon-file-pdf→\eaeb · icon-file-binary→\eae8 · icon-file-directory→\ea83 (+ expanded folder-opened \eaf7) · icon-file-symlink-directory→\eaed · icon-repo→\ea62 · icon-file-submodule→\eaec.

Verification

  1. nvm use then yarn start.
  2. Tree-view tab-bar shows the four codicon buttons; New File / New Folder open the add-dialog, Collapse All collapses roots, Refresh reloads from disk.
  3. File rows render codicons, with new-file / new-folder now distinct; per-type colors unchanged.
  4. Ordinary editor tabs and empty docks show no placeholder cluster.
  5. With showBusinessMockups on, the mockups’ controls still render (host-side; reload / scroll-to-top / about, no duplicate refresh).

Verified working (manual testing): tree-view controls, codicon file/folder glyphs, and the mockups’ host-side controls all render and function. The left dock does render a .tab-bar for the permanent tree-view item, so the existing .tab-bar injection point worked with no fallback needed. The mockup controls initially failed (only the untrusted-default “refresh” showed) because guest RPC self-registration is trust-at-load-time racy on restart/reload — fixed by converting them to host-side registration (see above).