chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.3.1 Latest 5 packages
0
0
// An app's frame, as its app file's `frame` declares it (docs/views.md,
// "The frame"; HUD checks it as it loads the file, schemas/
// place.hud.frame.json): the app's tabs as its destinations, its one
// primary action, the account's area (its picture on a tab, its items,
// signing out and in), the links at its foot, an aside, and how wide its
// column and its navigation's bands are. An app with none is drawn with
// every default, its tabs alone.
//
// Navigation follows the window's width, in three bands: a bar along the
// foot under `bands.rail`, an icon rail from there, a sidebar with words
// from `bands.sidebar`. The band is the stylesheet's to decide (`frameCss`,
// custom properties by media query, which the components read), never
// code's, so the page the server draws is the one the browser hydrates,
// whatever the window. The screen on top says how wide it is drawn (its
// view's `measure`): the column (`sizes.content`), all the room right of
// the navigation up to `sizes.wide`, or that to the window's edge; an
// aside is drawn right of the column only where the window holds the
// navigation, the screen's measure and the aside.
import type { Call } from '@hud/shared/result';
import type { IconName } from '@hud/renderer';
import type { Measure } from './app';
/** What the host does itself, as an account item: sign the account out, or (signed out) in. */
export type HostItem = { host: 'signOut' | 'signIn'; label?: string; icon?: IconName; about?: string };
/** A screen of the app's in the account's area (Settings), drawn signed in. */
export type CallItem = { label: string; icon: IconName; call: Call };
export type AccountItem = HostItem | CallItem;
export type Frame = {
/** The destinations: the app's tabs. */
destinations?: 'tabs';
/** The app's one primary action: a call whose screen opens at a form (a query's `compose`), that form alone opened over the screen on show; else its screen, opened on the tab on show. */
action?: { label: string; icon: IconName; call: Call };
account?: {
/** The account's picture, on the tab `tab` in place of its icon: a query's answer (`call`, made as each of the browser's accounts), the picture's URL at `at` in it, and the account's name and handle at `name` and `handle`, for its row among the accounts (a view's `Accounts`). */
picture?: { tab: string; call: Call; at: string; name?: string; handle?: string };
items?: AccountItem[];
};
/** Links at the navigation's foot: a path of the app's, or an https URL, opened as a page. */
links?: { label: string; href: string }[];
/** A screen drawn beside the column, where it fits: its call, and how wide it is (320). */
aside?: { call: Call; width?: number };
/** How wide the column is (`content`, 600) and a wide screen at most (`wide`, 935), in CSS pixels. */
sizes?: { content?: number; wide?: number };
/** The window widths the navigation becomes a rail at (600) and a sidebar at (1200). */
bands?: { rail?: number; sidebar?: number };
};
/** How wide the rail and the sidebar are. */
export const RAIL = 72;
export const SIDEBAR = 245;
/** A frame's every size, its defaults filled, and the host's bands over its own. */
export type Layout = { rail: number; sidebar: number; content: number; wide: number; aside: number | null };
/** A frame's layout: the host's `bands` (a host may draw its navigation at its own widths), else the frame's, else the defaults. */
export function layoutOf(frame: Frame | undefined, bands?: Frame['bands']): Layout {
const content = frame?.sizes?.content ?? 600;
return {
rail: bands?.rail ?? frame?.bands?.rail ?? 600,
sidebar: bands?.sidebar ?? frame?.bands?.sidebar ?? 1200,
content,
wide: Math.max(content, frame?.sizes?.wide ?? 935),
aside: frame?.aside ? (frame.aside.width ?? 320) : null
};
}
/** The room right of the navigation at most: a wide screen's, or the column's and the aside's where that is more. */
const roomOf = (layout: Layout) => Math.max(layout.wide, layout.content + (layout.aside ?? 0));
/** The navigation's bands, each from where it starts to before the next: its width, and whether the tab bar or the side navigation draws. */
function bands(layout: Layout) {
return [
{ from: 0, to: layout.rail, nav: 0 },
{ from: layout.rail, to: layout.sidebar, nav: RAIL },
{ from: layout.sidebar, to: Infinity, nav: SIDEBAR }
];
}
/** A media query of a range of window widths. */
function media(from: number, to: number): string {
const parts = [from > 0 ? `(min-width: ${from}px)` : '', to < Infinity ? `(max-width: ${to - 0.02}px)` : ''].filter(Boolean);
return `@media ${parts.join(' and ')}`;
}
/** A string as CSS writes one, quoted: its quote, backslash, line breaks and `<` (the sheet is the page's own `<style>`) escaped. */
const cssString = (text: string) => `"${text.replace(/["\\<\n\r\f]/g, (c) => `\\${c.charCodeAt(0).toString(16)} `)}"`;
/** The label of the form the frame's action opens (its call's `compose`, where that names one): a screen's Bar button that opens it is the action again. */
export function actionForm(frame: Frame | undefined): string | null {
const compose = frame?.action?.call.args.compose;
return typeof compose === 'string' ? compose : null;
}
/**
* The stylesheet that lays the frame out by the window's width, put in the
* page's head: each band's custom properties on the root (`--hud-frame-*`,
* which shell.css and the components draw with), and where an aside fits
* beside a screen of each measure, its width on the frame of that measure
* (`--hud-frame-aside-shown`) and the aside shown. Where the navigation is
* beside the screen (the rail's band and the sidebar's) and draws the
* action (signed in, the frame's `data-signed-in`), a Bar's button for the
* form the action opens (`form`, the renderer's `data-bar-form`) is not
* drawn: under the rail, with no action beside it, it is.
*/
export function frameCss(layout: Layout, form: string | null = null): string {
const room = roomOf(layout);
const rules = [`:root{--hud-frame-content:${layout.content}px;--hud-frame-wide:${layout.wide}px;--hud-frame-room:${room}px;--hud-frame-aside:${layout.aside ?? 0}px}`];
for (const band of bands(layout)) {
const side = band.nav > 0;
const values = [
`--hud-frame-nav:${band.nav}px`,
`--hud-frame-bar-display:${side ? 'none' : 'grid'}`,
`--hud-frame-side-display:${side ? 'block' : 'none'}`,
`--hud-frame-tabbar-height:${side ? '0px' : '3.5rem'}`,
`--hud-frame-band:${side ? 1 : 0}`,
// A tab root's screen bar does not repeat the wordmark the side navigation carries, and with nothing else in it is gone.
`--hud-frame-wordmark-display:${side ? 'none' : 'block'}`,
`--hud-frame-lone-bar-display:${side ? 'none' : 'flex'}`
];
const twin = side && form !== null ? `.hud-frame[data-signed-in] button[data-bar-form=${cssString(form)}]{display:none}` : '';
rules.push(`${media(band.from, band.to)}{:root{${values.join(';')}}${side ? 'html body{background:var(--color-background-primary)}' : ''}${twin}}`);
if (!side || layout.aside === null) continue;
// The aside beside a screen of a measure: where the room holds both, from the window that does.
for (const measure of ['content', 'wide'] as const) {
const width = measure === 'content' ? layout.content : layout.wide;
if (room < width + layout.aside) continue;
const from = Math.max(band.from, band.nav + width + layout.aside);
if (from >= band.to) continue;
rules.push(`${media(from, band.to)}{.hud-frame[data-measure="${measure}"]{--hud-frame-aside-shown:${layout.aside}px}.hud-frame[data-measure="${measure}"] .hud-aside{display:block}}`);
}
}
return rules.join('');
}
/**
* How wide a screen of each measure draws its main area, as an `<img>`'s
* sizes says: in the sidebar's band and the rail's, right of it, the
* column at most `content`, wide at most `wide`, full all the room to the
* window's edge (the frame centred, so half of what is past it); in the
* bar's, the window's width. The renderer sizes its pictures by it
* (`Tree`'s `area`), and the hero's preload asks for the same.
*/
export function areasOf(layout: Layout): Record<Measure, string> {
const room = roomOf(layout);
const of = (measure: Measure) => {
const sized = [layout.sidebar, layout.rail].map((from, i) => {
const nav = i === 0 ? SIDEBAR : RAIL;
const width =
measure === 'content'
? `min(${layout.content}px, 100vw - ${nav}px)`
: measure === 'wide'
? `min(${layout.wide}px, 100vw - ${nav}px)`
: `min(100vw - ${nav}px, 50vw + ${(room + nav) / 2 - nav}px)`;
return `(min-width: ${from}px) ${width}`;
});
return [...sized, '100vw'].join(', ');
};
return { content: of('content'), wide: of('wide'), full: of('full') };
}