// An app, as its app file (.json) gives it to its clients: its // name, its look (theme.ts), its page head's defaults (head.ts), its tabs, // each tab a tool call (`call`) drawn as the root of its own nav stack, its // routes, the URL each screen has (routes.ts), and its frame (frame.ts). // HUD checks the file as it loads it (docs/views.md, "The operator's // views"); a client bundles its own copy. Signed out, a tab draws `guest` // instead: another call, or "call" for the same one; a tab without it asks // to sign in. A tab's `wordmark` is its screen's title in place of its // label, drawn as the app's logo (Grain's "grain" over its feeds); its // `path` its URL at its root, where that is not its call's route (Grain's // home, `/`); its `badge`, signed in, a count on its icon: a call (`call`) // and where in its answer the count is (`count`, a dotted path, in a // query's `response`); its `first`, signed in, where its root is chosen // from the account's data: the first of a list's items that names a // screen of the app's (Grain's Home, the first of the feeds the person // pinned). Its `scheme`, signed in, where the account chose // light or dark (theme.ts). Its `search`, the search the frame's // navigation opens: a people typeahead (`typeahead`, a call its `params` // are given `q` in), and the URLs, by its routes, of the results for a // text (`results`, its `{q}`) and of a person (`person`, its `{actor}`). // Its `pages`, its own pages (its terms, its privacy policy), each a path // whose screen is HUD's `describe_app` of that page: its Markdown, which // HUD read from the file the page names as it loaded the app file. Its // `signIn`, its own sign-in screen (SignIn.svelte): what it says, and // where it finds accounts as a handle is typed (typeahead.ts). import type { Call } from '@hud/shared/result'; import type { IconName, UiNode, UiTabsProps, UiTree } from '@hud/renderer'; import type { Frame } from './frame'; import type { AppHead } from './head'; import { callOf, Names, pathOf, same, type Route } from './routes'; import type { Look, Scheme } from './theme'; export type Badge = { call: Call; count: string }; export type Search = { typeahead: Call; results: string; person: string }; /** A public query matching accounts to what is typed, at an XRPC host of its own: its paths are dotted, in its answer (`items`) and in each item. */ export type Typeahead = { url: string; method: string; param: string; params?: Record; items: string; did: string; handle: string; name?: string; avatar?: string; avatarFallback?: string }; /** The app's own sign-in screen: its heading, a line under it and one under the form (their links Markdown's `[label](href)`), the field's placeholder, making an account, and the typeahead. */ export type SignInPlan = { title: string; text?: string; placeholder?: string; legal?: string; create?: { text?: string; label: string }; typeahead?: Typeahead }; /** * Where a tab's root is chosen from the account's data, signed in: a query * (`call`), the list in its answer (`at`, a path as `at` reads one), where * in each of its items a path of the app's is (`path`, dotted), and the * procedure after which it is read again (`after`). */ export type First = { call: Call; at: string; path: string; after?: string }; export type Tab = { label: string; icon: IconName; call: Call; guest?: Call | 'call'; wordmark?: string; path?: string; badge?: Badge; first?: First }; export type Page = { path: string; title: string; description?: string; markdown: string }; export type App = { domain: string; name: string; look?: Look; head: AppHead; scheme?: Scheme; search?: Search; signIn?: SignInPlan; tabs: Tab[]; routes: Route[]; pages?: Page[]; frame?: Frame }; /** The call whose answer is one of the app's own pages: HUD's `describe_app` of it, by its path. */ export const pageCall = (app: App, page: Page): Call => ({ name: 'describe_app', args: { domain: app.domain, page: page.path } }); const routed = new WeakMap(); /** Every screen of the app's with a URL: its pages, each a route of its path (tried first, as no route has a page's path), then its routes. */ export function routesOf(app: App): Route[] { let all = routed.get(app); if (!all) routed.set(app, (all = [...(app.pages ?? []).map((page) => ({ path: page.path, call: pageCall(app, page) })), ...app.routes])); return all; } /** How wide a screen is drawn, as its view's `measure` asks: the frame's column (content), all its room right of the navigation (wide), or that to the window's edge (full). */ export type Measure = 'content' | 'wide' | 'full'; /** A screen's measure, as its tree says it; content where it says none. */ export const measureOf = (ui: UiTree | null | undefined): Measure => ui?.measure ?? 'content'; /** The call a tab draws, signed in or not; null where it needs an account. */ export function tabCall(tab: Tab, signedIn: boolean): Call | null { if (signedIn || tab.guest === 'call') return tab.call; return tab.guest ?? null; } /** A tab's URL at its root. */ export const tabPath = (app: App, tab: Tab, names: Names) => tab.path ?? pathOf(tab.call, routesOf(app), names) ?? '/'; /** Whether a path (with its query string) is a tab's own URL, `own`: the same, or with a query a link added (`?utm_source=`) where the tab's has none. */ export const isTabPath = (own: string, pathname: string, search: string) => own === pathname + search || (!own.includes('?') && own === pathname); /** The origin a listed path is read against: a path of the app's own, never another site's (`//host`, `/\host`). */ const OWN = 'https://app.invalid'; /** * The root a tab's `first` chooses from what its query answered: the * screen of the first item whose path has one, the tab's own URL its * `call` (Grain's Recent, pinned as `/` by older apps), any other by the * app's routes; null where none has (nothing listed, or nothing the app * draws, as Grain's Groups is not). */ export async function chosenRoot(app: App, tab: Tab, answer: unknown, resolve: (actor: string) => Promise): Promise { const first = tab.first; const items = first ? at(answer, first.at) : null; if (!first || !Array.isArray(items)) return null; const own = tabPath(app, tab, new Names()); for (const item of items) { const path = at(item, first.path); const url = typeof path === 'string' && path.startsWith('/') ? new URL(path, OWN) : null; if (url?.origin !== OWN) continue; if (isTabPath(own, url.pathname, url.search)) return tab.call; const found = await callOf(url.pathname, url.search, routesOf(app), resolve); if (found) return found.call; } return null; } /** * Each tab's root: its call, signed in or not (`tabCall`); signed in, a * tab with `first` the screen its query's answer chooses (`chosenRoot`), * its call where the query fails (`ask` answers its data, or null) or * chooses none. Made for each page, so a list the person reordered is * what the next page's tab opens. */ export async function rootsOf(app: App, signedIn: boolean, ask: (call: Call) => Promise, resolve: (actor: string) => Promise): Promise<(Call | null)[]> { return Promise.all( app.tabs.map(async (tab) => { const own = tabCall(tab, signedIn); if (!signedIn || !tab.first) return own; return (await chosenRoot(app, tab, await ask(tab.first.call), resolve)) ?? own; }) ); } /** A tree's first `Tabs` strip, depth first through its children; null where it has none. */ function stripOf(node: UiNode): UiTabsProps | null { if (node.c === 'Tabs') return node.p as UiTabsProps; for (const child of node.k ?? []) { const found = stripOf(child); if (found) return found; } return null; } /** Whether a screen's tree has a `Tabs` strip that offers the screen itself (its item `selected`): a feed of Home's strip, as Grain's pinned ones. */ export const inStrip = (ui: UiTree): boolean => (stripOf(ui.root)?.items ?? []).some((item) => item.selected); /** * The tab a screen is the root of, in its root's place: where the screen's * tree has a `Tabs` strip that offers the screen itself (`inStrip`) and a * tab's root call (`roots`, `rootsOf`'s) beside it, that tab (Grain's * Following, or a pinned feed, a choice of Home's strip); else -1. * Choosing a strip's tab draws its call in the root's place (Stack's * `swap`), so a URL of one is drawn so too, by the server as by the * browser: the tab's root level, its strip shown and no back. A screen * once there that its strip no longer offers (a feed unpinned) is a * screen pushed over the root again (Stack's `unswapped`). */ export function swappedTab(roots: (Call | null)[], ui: UiTree): number { if (!inStrip(ui)) return -1; const items = stripOf(ui.root)?.items ?? []; const offered = items.flatMap((item) => (item.open && 'call' in item.open ? [item.open.call] : [])); return roots.findIndex((own) => own !== null && offered.some((call) => same(call, own))); } /** What is at a dotted path in an answer: in a query's `response`, else in the answer itself; a key `@name` is the element of an array whose `$type` is `name` or ends `#name`. */ export function at(answer: unknown, path: string): unknown { const data = answer as Record | null; let found: unknown = data && typeof data === 'object' && 'response' in data ? data.response : data; for (const key of path.split('.')) { if (key.startsWith('@') && Array.isArray(found)) { const name = key.slice(1); found = found.find((item) => { const type = (item as { $type?: unknown } | null)?.$type; return typeof type === 'string' && (type === name || type.endsWith(`#${name}`)); }); } else found = typeof found === 'object' && found !== null ? (found as Record)[key] : undefined; } return found; }