/**
* Pure HTML atoms shared by the Bytefly browser pages.
*
* Each helper returns a string with every dynamic *value* escaped through
* `lib/escape.ts`. Fields documented as trusted (`css`, an `icon` glyph, an
* attribute key) are code-authored constants, never model or file text.
*/
import { escapeHtml } from "../escape.ts";
import { pageSource } from "../format.ts";
import { THEME_JS_PATH } from "./runtime.ts";
import { WEB_THEME_TOKENS } from "./tokens.ts";
/** Options for {@link docHead}. */
export interface DocHeadOptions {
/** Page title, escaped. */
title: string;
/** Trusted CSS assembled by the page. */
css: string;
/**
* The mount prefix this page answers under, e.g. `/files`; `""` for the origin's
* root. A page's scripts and links are emitted under it, because a session serves
* several pages on one origin.
*/
base?: string;
}
/**
* A page's browser-tab title: ` · · `.
*
* One convention across the served pages, so a strip of tabs reads as one product. The
* page's name comes first, lowercase and the same word `appHead`'s `product`
* carries; then what the page is showing; then the count a reader opens the tab for. A
* part the page does not have is left out rather than drawn empty, so a board with
* nothing open reads `board · my-pi-agent` and a plan reads `plan review · `.
*/
export function tabTitle(product: string, subject?: string, count?: string): string {
const kept = [product, subject, count];
return kept.filter((part) => part !== undefined && part !== "").join(" · ");
}
/**
* The same body, as the browser receives it.
*
* The board's count is live, so its tab is repainted on every frame and this rule has to
* cross into the bundle. The body is a value the fragment substitutes, so only `.replace`'s
* replacement patterns are forbidden; `test/spliced-bodies.test.ts` holds them.
*/
export const TAB_TITLE_JS = pageSource(tabTitle);
/**
* The `data-base` attribute a page's `` carries, which its own bundle reads
* (`base()` in `client-runtime.ts`) to build every URL it emits.
*
* `""` — the origin's root — writes nothing at all, so a page served alone is markup
* without a mount to name.
*/
export function baseAttribute(base: string): string {
return base === "" ? "" : ` data-base="${escapeHtml(base)}"`;
}
/**
* The shared document head: charset, viewport, colour scheme, title, the page
* CSS, and the pre-paint theme bootstrap. The body and its scripts stay with
* each page.
*/
export function docHead(options: DocHeadOptions): string {
return `
${escapeHtml(options.title)}
${markIcon()}
`;
}
/**
* The mark's blocks: `█▀█` over `█▀ █`, as `[x, height]` per row in a 4x2 grid.
*
* One shape, three places — the header lockup, the tab icon, and the TUI header's
* half-blocks — so it is written once. The rows differ: the top fills x=2, the bottom
* leaves it empty and fills x=3, which is what makes the mark read as two glyphs.
*/
const MARK_ROWS: ReadonlyArray<{ group: "top" | "bottom"; rects: ReadonlyArray }> = [
{
group: "top",
rects: [
[0, 1],
[1, 0.5],
[2, 1],
],
},
{
group: "bottom",
rects: [
[0, 1],
[1, 0.5],
[3, 1],
],
},
];
/** One row of the mark, as ``s starting at `y`. */
function markRowRects(row: (typeof MARK_ROWS)[number], y: number): string {
return row.rects.map(([x, height]) => ``).join("");
}
/**
* The mark as a standalone SVG, in one appearance's colours.
*
* A favicon is its own document: it cannot read the page's tokens, so the fills are
* resolved here from the same palette the page paints with, and each appearance gets
* its own icon.
*/
function markSvg(fills: { top: string; bottom: string }): string {
const rows = MARK_ROWS.map((row, index) => `${markRowRects(row, index)}`);
return ``;
}
/**
* The tab icon: the mark, in the appearance the reader's system is in.
*
* The dark icon is the plain `rel="icon"` — the page paints dark at `:root`, and a
* browser that reads no `media` query on an icon keeps it. The light one is the
* override, so a light tab does not carry a mark tuned for a dark one.
*/
export function markIcon(): string {
const dark = encodeURIComponent(
markSvg({ top: WEB_THEME_TOKENS.dark["--accent"], bottom: WEB_THEME_TOKENS.dark["--warn"] }),
);
const light = encodeURIComponent(
markSvg({ top: WEB_THEME_TOKENS.light["--accent"], bottom: WEB_THEME_TOKENS.light["--warn"] }),
);
return `
`;
}
/**
* The Bytefly nameplate: the two-tone half-block mark, the `bytefly` wordmark,
* and the product name. The mark mirrors the TUI header (`█▀█` / `█▀ █`), drawn
* as a 4x2 grid so the accent and warning rows stay crisp at any zoom.
*/
function brandLockup(product: string): string {
const rows = MARK_ROWS.map((row, index) => `${markRowRects(row, index)}`);
return `bytefly${escapeHtml(product)}`;
}
/**
* The theme toggle button. Keeps the `#theme-toggle` id and `.theme-glyph`
* span the shared `THEME_TOGGLE_JS` scripts find.
*/
export function themeToggle(): string {
return ``;
}
/**
* The page's subject: what this page is of — a repository's name, a served root.
*
* It is the toolbar's splitter as well as its label, so the only thing after it is the page's
* own facts and the app's chrome. The whole value is on the hover, because the line truncates
* its head: two clones of one repository, or two served folders, are told apart by the path.
*/
/** What the identity row's subject says: the label, and the whole value it stands for. */
export interface PageSubjectOptions {
/** Element id, for a client that repaints the label. */
id?: string;
/** Visible label, escaped. */
label: string;
/** The whole value, on the hover; the label may be a truncated head of it. */
title: string;
}
function pageSubject(options: PageSubjectOptions): string {
const id = options.id === undefined ? "" : ` id="${escapeHtml(options.id)}"`;
return `${escapeHtml(options.label)}`;
}
/**
* The live-state line: the state's colour, its glyph, and its word.
*
* The tone is a `bf-tone--*` modifier and the glyph is decoration, so a client repaints the
* word and the class and never the shape ({@link paintLive} does exactly that). `attrs`
* carries a page's own hooks — the browse pages put their polling interval and the revision
* of what they drew there. The line is not a live region: the header is where a reader looks
* for the state, and a page that announced every repaint would talk over its own content.
*/
export function liveChip(options: {
id: string;
label: string;
title?: string;
hidden?: boolean;
attrs?: Record;
}): string {
const title = options.title === undefined ? "" : ` title="${escapeHtml(options.title)}"`;
const attrs = Object.entries(options.attrs ?? {})
.map(([key, value]) => ` ${key}="${escapeHtml(value)}"`)
.join("");
return `◉${escapeHtml(options.label)}`;
}
/**
* The live line's one action: reload the page.
*
* It starts hidden and a client reveals it when the page stops being true — the folder it
* drew changed on disk, or the stream it reads has gone. Reloading is not a write: a page
* that cannot change a card can still ask the server for the page again.
*/
export function reloadChip(options: { title: string }): string {
return ``;
}
/** The `?` button that opens {@link keysSheet}, which is the one trigger both pages use. */
export function keysButton(): string {
return button({
label: "?",
variant: "icon",
id: "keys-open",
title: "Keyboard shortcuts",
attrs: { "aria-haspopup": "dialog" },
});
}
/** The app's chrome, in the identity row's last zone: the key sheet, then the theme toggle. */
function toolbarChrome(): string {
return `
${keysButton()}${themeToggle()}
`;
}
/** Options for {@link appHead}: the page's name, what it is of, and its own two rows. */
export interface AppHeadOptions {
/** The product name the lockup carries, and the word `tabTitle` names the page by, e.g. `board`. */
product: string;
/** The page's subject, as the identity row's one truncating label reads it. */
subject: PageSubjectOptions;
/** Trusted markup for the facts zone: the live line, its reload, or the page's own sentence. */
facts: string;
/**
* Trusted markup for the page's own controls. Absent on a page with none, which has one row —
* and so no rule, because a line with nothing under it draws the head's border twice.
*/
controls?: string;
/** A page's own class on the identity row, code-authored. */
identityClass?: string;
/** A page's own class on the control row, code-authored. */
controlsClass?: string;
}
/**
* The app head: the identity row, over the page's own control row when it has one.
*
* One atom writes the shell's whole header, so no page can put the row rule where no row follows
* it: the mark, the subject, the facts and the app's chrome sit in the identity row, and the rule
* and the control row are written only for a page that passes controls. A page's classes reach
* its own row through `identityClass` and `controlsClass`; the zones themselves are the kit's.
*/
export function appHead(options: AppHeadOptions): string {
const identity = options.identityClass === undefined ? "" : ` ${options.identityClass}`;
const row = `
`;
}
/**
* The footer: one line, and only where the page's content came from.
*
* The live state and the key-sheet affordance live in the header, which never scrolls away,
* so a footer that repeated them would be a second place for a fact the reader already has.
* The line wraps rather than cutting a fact off it, so the end that names the folder always
* survives. `factsId` is for a page whose client keeps the line true after a frame; the
* facts ride the document so a slow frame never leaves the footer blank.
*/
export function pageFooter(options: { facts: string; factsId?: string }): string {
const id = options.factsId === undefined ? "" : ` id="${escapeHtml(options.factsId)}"`;
return ``;
}
/** A state's tone, mapping to a `bf-tone--*` modifier. */
export type ChipTone = "accent" | "success" | "warn" | "danger" | "dim" | "muted";
/** Options for {@link chip}. */
export interface ChipOptions {
/** Visible text, escaped. */
label: string;
/** Optional tone modifier. */
tone?: ChipTone;
/** Trusted leading glyph or SVG. */
icon?: string;
/** A page's own class, code-authored, appended after the kit's own. */
className?: string;
/** Extra code-authored attributes — a tooltip, an accessible name; keys and values escaped. */
attrs?: Record;
}
/** A status tag: a glyph and a word on a 2px rail, with no box around them. */
export function chip(options: ChipOptions): string {
const tone = options.tone ? ` bf-tone--${options.tone}` : "";
const page = options.className ? ` ${options.className}` : "";
const icon = options.icon ? `${options.icon}` : "";
const attrs = Object.entries(options.attrs ?? {})
.map(([key, value]) => ` ${key}="${escapeHtml(value)}"`)
.join("");
return `${icon}${escapeHtml(options.label)}`;
}
/** A button variant, mapping to a `bf-btn--*` modifier. */
export type ButtonVariant = "primary" | "ghost" | "icon";
/** Options for {@link button}. */
export interface ButtonOptions {
/** Visible text, escaped. */
label: string;
/** Optional variant modifier. */
variant?: ButtonVariant;
/** Element id. */
id?: string;
/** Tooltip and accessible name. */
title?: string;
/** Sets `aria-pressed` when defined. */
pressed?: boolean;
/** Extra code-authored attributes; keys and values are escaped. */
attrs?: Record;
}
/** A `type="button"` control wired to the kit classes. */
export function button(options: ButtonOptions): string {
const classes = options.variant ? `bf-btn bf-btn--${options.variant}` : "bf-btn";
const attrs: Array<[string, string]> = [];
if (options.id) attrs.push(["id", options.id]);
if (options.title) attrs.push(["title", options.title]);
if (options.pressed !== undefined) attrs.push(["aria-pressed", String(options.pressed)]);
for (const [key, value] of Object.entries(options.attrs ?? {})) attrs.push([key, value]);
const rendered = attrs.map(([key, value]) => ` ${key}="${escapeHtml(value)}"`).join("");
return ``;
}
/** One row of the keyboard sheet: the key or chord, and what it does. */
export interface KeyHint {
/** The key or chord, one `` per entry; a single string is one key, chord, or alias run. */
keys: string | readonly string[];
/** What the key does. */
label: string;
}
/**
* The `?` keyboard sheet: the dialog of key/label rows both pages share, hidden
* until the client opens it.
*
* The ids are the contract with `keysDialogScript` in `runtime.ts` — `#keys-dialog`
* for the sheet, `#keys-close` for its own close button — and its trigger is
* {@link keysButton}.
*/
export function keysSheet(rows: readonly KeyHint[], note?: string): string {
const kbd = (key: string): string => `${escapeHtml(key)}`;
const body = rows
.map((row) => {
const keys = typeof row.keys === "string" ? kbd(row.keys) : row.keys.map(kbd).join(" ");
return `