Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { createPortal } from 'react-dom';
import { memo, useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
import { parseTabSheet, TAB_ARTICULATIONS, chordLineSegments, pairedLineChunks, chordLyricRows } from '../../lib/tabNotation.js';
import usePopoverPosition from '../../hooks/usePopoverPosition.js';
import useFocusTrap from '../../hooks/useFocusTrap.js';
import useEscapeKey from '../../hooks/useEscapeKey.js';
import ChordDiagram from './ChordDiagram.jsx';
import { activeCtrlClass, ctrlBtnClass } from './constants.js';
/**
* Rendered tab/chord sheet — the shared display surface for the SongBook
* viewer's play mode, the editor's live preview, and the import preview.
*
* Takes the (already-transposed) sheet `text` and renders parseTabSheet's
* classified lines:
* - section → styled heading
* - chords/lyric and chordlyric → paired word groups that wrap both rows together
* - standalone chords → highlighted monospace chord line
* - tabstaff → consecutive staff lines grouped in one overflow-x-auto block
* so a wide staff scrolls as a unit without wrapping
* - lyric/text → plain monospace pre-wrap
*
* `fontSizeRem` scales the whole sheet (viewer font ± control).
* `format='plain'` bypasses parsing entirely and renders the raw text
* verbatim — the explicit opt-out of ALL notation UI (headings, chord
* highlighting, popovers, and the chords-used strip alike).
*
* Instrument-view support (issue #2656): `instrumentView`
* ('guitar'|'ukulele'|'piano', default 'guitar') drives the chord diagrams —
* every chord token is a tappable/keyboard-activatable button that opens a
* viewport-clamped popover with the voicing for the active instrument, and
* because `text` arrives already transposed the diagrams follow the transposed
* names for free. Tab staffs are guitar-specific, so non-guitar views collapse
* each staff block to a one-line note with an inline "show" expand.
*
* Play-along support (issue #4104): `soundingChord` — `{ lineIndex, chordIndex }`
* or null — lights the chord token the synth preview is currently sounding, the
* chord-sheet equivalent of `<DrumSheetView>`'s playhead. The coordinates are
* the ones `sheetChordOccurrences` (lib/chordPlayback.js) hands out, i.e.
* positions in `parseTabSheet(text).lines`, so the schedule and the sheet agree
* on which token is which without either knowing how the other is built. Purely
* presentational: the audio, the transport and the clock all live in
* `useChordPlayer` / `<ChordTransportBar>`.
*/
const POPOVER_WIDTH = 172;
// A tappable chord token. Paired rows reserve its vertical touch padding;
// horizontal padding cancels via negative margins to retain column alignment.
const ChordToken = ({ name, tokenKey, expanded, sounding, onTap }) => (
<button
type="button"
onClick={(e) => onTap(name, tokenKey, e.currentTarget)}
aria-expanded={expanded}
aria-haspopup="dialog"
// The sounding token is marked in the DOM as well as painted: the highlight
// is a background tint, which a test can't read and a high-contrast theme
// may flatten.
data-sounding={sounding ? '' : undefined}
// font-mono is explicit (not inherited): PortOS themes set --port-font-ui
// directly on every <button>, which would render chord names proportional
// and break the sheet's column alignment.
className={`inline align-baseline font-mono text-port-accent font-semibold rounded px-1 -mx-1 py-2 focus-visible:outline focus-visible:outline-1 focus-visible:outline-port-accent ${
sounding ? 'bg-port-accent/25 ring-1 ring-port-accent' : 'hover:bg-port-accent/10'
}`}
>
{name}
</button>
);
const ChordSegments = ({ segments, blockKey, activeKey, soundingChordIndex, onTap }) =>
segments.map((seg, i) => {
if (!seg.chord) return <span key={i}>{seg.text}</span>;
const tokenKey = `${blockKey}:${i}`;
return (
<ChordToken
key={i}
name={seg.text}
tokenKey={tokenKey}
expanded={activeKey === tokenKey}
// `soundingChordIndex` is null when nothing on THIS line is sounding,
// and a chord index is legitimately 0 — so compare explicitly rather
// than leaning on truthiness.
sounding={soundingChordIndex != null && soundingChordIndex === seg.chordIndex}
onTap={onTap}
/>
);
});
const TabLegend = ({ id }) => (
<div id={id} className="mb-3 rounded-lg border border-port-border bg-port-bg/60 px-3 py-2 text-xs font-sans">
<dl className="grid gap-x-4 gap-y-1 sm:grid-cols-2">
{TAB_ARTICULATIONS.map((articulation) => (
<div key={articulation.char} className="flex items-start gap-2">
<dt className="shrink-0 rounded border border-port-border bg-port-card px-1.5 font-mono text-sm text-port-accent">
{articulation.char}
</dt>
<dd className="min-w-0 text-gray-300">
<span className="font-semibold text-white">{articulation.name}</span> — {articulation.detail}
</dd>
</div>
))}
</dl>
</div>
);
function TabSheetView({
text,
format = 'tab',
fontSizeRem = 0.875,
className = '',
instrumentView = 'guitar',
soundingChord = null,
}) {
const plain = format === 'plain';
const { lines } = useMemo(
// 'plain' is the explicit opt-out of notation parsing: render every line
// verbatim (no section headings, no chord highlighting — and no chord
// popovers either) so the stored format selector has an observable
// effect.
() => (plain ? { lines: [] } : parseTabSheet(text)),
[text, plain],
);
// Group consecutive tabstaff lines into one horizontally-scrollable block so
// the six strings of a staff scroll together. Each block keeps the index its
// FIRST line had in `lines`; a chord/lyric pair keeps the chord line index
// that the play-along highlight addresses.
const blocks = useMemo(() => {
const out = [];
lines.forEach((line, lineIndex) => {
const prev = out[out.length - 1];
if (line.type === 'lyric' && prev?.type === 'chords') prev.lines.push(line);
else if (line.type === 'tabstaff' && prev?.type === 'tabstaff') prev.lines.push(line);
else out.push({ type: line.type, lineIndex, lines: [line] });
});
return out;
}, [lines]);
const hasTabstaff = lines.some((line) => line.type === 'tabstaff');
const [legendOpen, setLegendOpen] = useState(false);
const legendId = useId();
const staffIdPrefix = useId();
// Chord popover: { name, key }; placement is owned by usePopoverPosition,
// which re-measures on open and reflows (rAF-coalesced, capture-phase) on
// ancestor scroll/resize — so autoscroll can't detach the dialog from its
// trigger, and the measured height replaces any estimate.
const [popover, setPopover] = useState(null);
const anchorElRef = useRef(null);
const { popoverRef, style: popoverStyle } = usePopoverPosition({
open: !!popover,
width: POPOVER_WIDTH,
position: 'below',
anchorRef: anchorElRef,
// popover?.key: tapping a DIFFERENT occurrence of the same chord swaps
// the anchor element without changing name/view — the key forces a
// re-measure so the dialog moves to the newly-tapped token.
contentDeps: [popover?.key, popover?.name, instrumentView],
});
useFocusTrap(Boolean(popover && popoverStyle), popoverRef);
useEscapeKey(Boolean(popover), () => {
setPopover(null);
anchorElRef.current?.focus();
});
// Tabstaff blocks explicitly expanded while in a non-guitar view.
const [expandedStaffs, setExpandedStaffs] = useState(() => new Set());
// New text (edit, transpose) invalidates block indices and chord names.
useEffect(() => {
setPopover(null);
setExpandedStaffs(new Set());
}, [text]);
const onChordTap = useCallback((name, key, el) => {
setPopover((prev) => {
if (prev?.key === key) return null; // tap again to close
anchorElRef.current = el;
return { name, key };
});
}, []);
// Tap-outside close while the popover is open.
useEffect(() => {
if (!popover) return undefined;
const onPointerDown = (e) => {
if (popoverRef.current?.contains(e.target)) return;
// Chord tokens manage their own open/toggle in onClick — closing here on
// the preceding pointerdown would make a second tap close-then-reopen.
if (e.target.closest?.('[aria-haspopup="dialog"]')) return;
setPopover(null);
};
document.addEventListener('pointerdown', onPointerDown);
return () => {
document.removeEventListener('pointerdown', onPointerDown);
};
}, [popover]);
// 'plain' bypass — after the hooks above (they must run unconditionally)
// and before any notation UI: verbatim text, no strip, no popovers.
if (plain) {
return (
<div
className={`font-mono text-gray-200 whitespace-pre-wrap ${className}`}
style={{ fontSize: `${fontSizeRem}rem`, lineHeight: 1.5 }}
>
{text}
</div>
);
}
return (
<div className={`font-mono text-gray-200 ${className}`} style={{ fontSize: `${fontSizeRem}rem`, lineHeight: 1.5 }}>
{hasTabstaff && (
<div className="mb-1.5 flex justify-end font-sans">
<button
type="button"
onClick={() => setLegendOpen((open) => !open)}
aria-expanded={legendOpen}
aria-controls={legendId}
className={`px-3 ${ctrlBtnClass} ${legendOpen ? activeCtrlClass : ''}`}
>
Legend
</button>
</div>
)}
{hasTabstaff && legendOpen && <TabLegend id={legendId} />}
{blocks.map((block, bi) => {
if (block.type === 'tabstaff') {
// Collapse staffs that don't belong to the active view: a ≥5-line
// staff is guitar tab (collapsed outside Guitar view); a ≤4-line
// staff is plausibly ukulele/bass tab, so the Ukulele view keeps it
// — a uke song's own native tab must not hide under a "guitar tab"
// note. Piano has no tablature, so Piano view collapses every staff.
const looksGuitar = block.lines.length >= 5;
const collapse = instrumentView === 'piano'
? true
: instrumentView === 'ukulele' && looksGuitar;
const staffId = `${staffIdPrefix}-staff-${bi}`;
if (collapse && !expandedStaffs.has(bi)) {
return (
<div key={bi} className="my-1 flex items-center gap-2 text-xs text-gray-500 italic font-sans">
<span>{looksGuitar ? 'guitar tab — switch to Guitar view' : 'tablature — switch to Guitar or Ukulele view'}</span>
<button
type="button"
onClick={() => setExpandedStaffs((prev) => new Set(prev).add(bi))}
aria-label={`Show ${looksGuitar ? 'guitar ' : ''}tablature staff (section ${bi + 1})`}
aria-expanded={false}
aria-controls={staffId}
className="not-italic text-port-accent hover:underline px-1 py-2 -my-2"
>
show
</button>
</div>
);
}
return (
<div id={staffId} key={bi} className="overflow-x-auto whitespace-pre text-gray-300 my-1">
{block.lines.map((line, li) => <div key={li}>{line.text}</div>)}
</div>
);
}
const line = block.lines[0];
// Null unless the sounding chord belongs to THIS line — so a chord index
// can never light the same-numbered token on a different line.
const soundingChordIndex = soundingChord?.lineIndex === block.lineIndex
? soundingChord.chordIndex
: null;
if (line.type === 'chordlyric' || (line.type === 'chords' && block.lines.length === 2)) {
const rows = line.type === 'chordlyric'
? chordLyricRows(line)
: { lyric: block.lines[1].text, chordText: line.text, chords: line.chords };
return (
<div key={bi} className="flex flex-wrap overflow-x-auto" data-chord-lyric-pair="">
{pairedLineChunks(rows.lyric, rows.chordText, rows.chords).map((chunk, ci) => (
<div key={ci} className="shrink-0 whitespace-pre" data-chord-lyric-chunk="">
<div className="h-[calc(1.5em+1rem)]">
<ChordSegments
segments={chunk.segments}
blockKey={`${bi}:${ci}`}
activeKey={popover?.key ?? null}
soundingChordIndex={soundingChordIndex}
onTap={onChordTap}
/>
</div>
<div className="min-h-[1.5em]">{chunk.lyric}</div>
</div>
))}
</div>
);
}
switch (line.type) {
case 'section':
// {end_of_*} directives carry an empty label — render nothing visible.
return line.label
? (
<div key={bi} className="mt-4 mb-1 text-port-accent font-bold uppercase tracking-wide text-[0.85em]">
{line.label}
</div>
)
: <div key={bi} className="mb-1" />;
case 'chords':
return (
<div key={bi} className="whitespace-pre-wrap">
<ChordSegments
segments={chordLineSegments(line.text, line.chords)}
blockKey={bi}
activeKey={popover?.key ?? null}
soundingChordIndex={soundingChordIndex}
onTap={onChordTap}
/>
</div>
);
case 'blank':
return <div key={bi}>{' '}</div>;
case 'directive':
// ChordPro meta plumbing ({title:}/{key:}/{capo:}) — the values
// surface in the viewer's badges/fields, not as raw text.
return null;
case 'lyric':
case 'text':
default:
return <div key={bi} className="whitespace-pre-wrap">{line.text}</div>;
}
})}
{popover && createPortal(
<div
ref={popoverRef}
role="dialog"
aria-label={`${popover.name} chord voicing`}
// max-h + overflow: a many-segment dash-joined token wraps voicings
// into rows that can exceed a short/mobile viewport — the popover
// scrolls internally instead of stranding lower diagrams offscreen.
className="fixed z-50 bg-port-card border border-port-border rounded-lg shadow-xl p-3 font-sans max-h-[min(60vh,480px)] overflow-y-auto"
style={popoverStyle ?? { visibility: 'hidden', left: 0, top: 0, width: POPOVER_WIDTH }}
>
<div className="flex items-center justify-between gap-2 mb-1.5">
<span className="text-sm font-mono font-semibold text-port-accent">{popover.name}</span>
<span className="text-[10px] uppercase tracking-wide text-gray-500">{instrumentView}</span>
</div>
<ChordDiagram name={popover.name} instrument={instrumentView} />
<button type="button" className="mt-2 text-sm text-port-accent py-2 w-full" onClick={() => {
setPopover(null);
anchorElRef.current?.focus();
}}>Close chord diagram</button>
</div>,
document.body,
)}
</div>
);
}
// Props are all primitives (`format`/`instrumentView` included) apart from
// `soundingChord`, which the host memoizes and which only changes when the
// sounding chord does (once a bar, not once a frame) — so memo
// makes re-renders of a host page (stage flips, autoscroll ticks) skip the full
// sheet re-render.
export default memo(TabSheetView);