Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions dist/app.js

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion dist/style.css

Large diffs are not rendered by default.

57 changes: 57 additions & 0 deletions docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -272,6 +272,63 @@ used to announce "not connected" and then render the whole form disabled.
Motion earns its place only where it conveys state: a toast arriving, a banner
appearing, the polling dot pulsing. Everything else is still.

## Two things borrowed from a prototype, and the rest left alone

An IA study for another console (EdgeVault's) was read against this one. Most
of it does not apply here and was not taken: it is built around promoting
config between environments, and this console has no environments, no write
API, and a byte budget. Its list-with-a-side-panel would also be a regression
against "the URL is the artifact", because the panel is not addressable and the
detail *route* already is.

Two things did apply.

**The attention banner on Overview.** Job one in PRODUCT.md is "is the
federation healthy, and if not which upstream?" This page answered that with a
count in the Federation card and left the operator to reach `/upstreams` and
work out the filter. One sentence at the top now names the condition and links
to the list already filtered to it.

It renders nothing when there is nothing to say. A banner that is always
present is furniture, and an operator who has learned to skip it has learned to
skip it on the day it matters. Half-open breakers are not counted: half-open is
neither proven nor failed, and an upstream reporting no breaker at all is
version skew rather than a state. A disconnected upstream whose breaker is also
open is one finding, not two.

It is deliberately **not** `role="alert"`, which is why `Banner` grew an
`announce` prop. The alerting banners — unauthorized, version skew, a failed
read — describe the *console* being degraded: they arrive unbidden and the page
underneath is not what was asked for. Federation health is the opposite. It is
the answer the operator navigated here to read, and hijacking a screen reader
to deliver requested content is noise dressed as urgency. Keeping the role
reserved also keeps `getByRole('alert')` meaning one thing across the suite,
which two tests were relying on without saying so.

**A jump-to palette.** Ctrl/Cmd-K, navigation only. The existing filters are
good and stay in the URL, but neither gets you to a page from somewhere else,
and the catalog runs to several hundred names. Success here is an answer in
under thirty seconds.

Two details are constraints rather than taste. The shipped subset is latin plus
`U+2190-2193`, so the hints use words and the two arrows that are actually in
the file — a command glyph or a return arrow would be drawn by whatever the
machine fell back to, which is the defect this repo already fixed once for the
arrows. And the trigger sits in the top bar, after the skip control in DOM
order, because the skip control is asserted to be the first tab stop.

Both together cost about 13 KiB against the 320 KiB budget, taking it to ~76%.

### What the a11y suite learned from this

`scan()` settled animations once, then scanned. That was enough while every
banner rendered with the route; the attention banner renders when the *data*
lands, which is after `<main>` became visible and after the first settle
resolved — so axe intermittently sampled it mid-fade and reported a contrast
failure that was really a composite. It now settles, waits two frames, and
settles again. The same gap applies to anything that arrives with a query
rather than a route.

## The topology view

`/upstreams?view=map` draws the federation in fold's fold-line vocabulary
Expand Down
16 changes: 14 additions & 2 deletions src/components/Banner.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,18 @@ export type BannerTone = 'bad' | 'warn'

interface Props {
tone?: BannerTone
/**
* Interrupt a screen reader, or wait to be read in order. Default true.
*
* The distinction is not cosmetic. Unauthorized, version skew and a failed
* read describe the *console* being degraded: they arrive unbidden and the
* page beneath them is not what the operator asked for, so announcing them
* is the point. A summary of the federation's own health is the opposite —
* it is the answer to the question the operator navigated here to ask, and
* hijacking the reader to deliver content they already requested is noise
* dressed as urgency. It reads in document order instead.
*/
announce?: boolean
children: ComponentChildren
}

Expand All @@ -15,9 +27,9 @@ interface Props {
* role="alert" is deliberate here and deliberately absent from the toast
* region: this is the one thing on the page worth interrupting for.
*/
export function Banner({ tone = 'bad', children }: Props) {
export function Banner({ tone = 'bad', announce = true, children }: Props) {
return (
<p class={`banner ${tone}`} role="alert">
<p class={`banner ${tone}`} role={announce ? 'alert' : undefined}>
{children}
</p>
)
Expand Down
185 changes: 185 additions & 0 deletions src/components/Palette.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,185 @@
// Jump to a route, an upstream, or one tool in the catalog.
//
// The console already filters well: /upstreams and /catalog both keep their
// query in the URL, and both are instant because the whole federation arrives
// in one snapshot. What neither can do is get you there from somewhere else.
// Success here is defined as an answer in under thirty seconds, and "go to the
// broken upstream from wherever you are" is the shortest version of that.
//
// It only navigates. There is no write API to reach and nothing here mutates,
// so the palette is a faster way to reach a page rather than a second way to
// do anything.
//
// Two details are constraints rather than taste:
//
// - The shipped font subset is latin plus U+2190-2193. No command glyph, no
// return arrow — those would come from whatever the machine fell back to,
// which is the exact defect docs/design.md records about arrows. The hints
// use words and the arrows that are actually in the file.
// - The trigger lives after the skip link in DOM order, because the skip
// link is asserted to be the first tab stop.
import { useEffect, useMemo, useRef, useState } from 'react'
import { useNavigate } from '@tanstack/react-router'
import type { FederationState } from '@/lib/federation'
import type { Catalog, Mode } from '@/lib/mcp'

interface Item {
group: string
label: string
hint?: string
run: () => void
}

const ROUTES: Array<{ label: string; to: string }> = [
{ label: 'Overview', to: '/' },
{ label: 'Upstreams', to: '/upstreams' },
{ label: 'Catalog', to: '/catalog' },
{ label: 'Test console', to: '/test' },
]

export function Palette({
state,
catalog,
onClose,
}: {
state: FederationState | undefined
catalog: Catalog | undefined
onClose: () => void
}) {
const navigate = useNavigate()
const dialog = useRef<HTMLDialogElement>(null)
const [query, setQuery] = useState('')
const [cursor, setCursor] = useState(0)

useEffect(() => {
dialog.current?.showModal()
}, [])

const items = useMemo<Item[]>(() => {
const all: Item[] = ROUTES.map((r) => ({
group: 'Go to',
label: r.label,
run: () => void navigate({ to: r.to }),
}))

for (const u of state?.upstreams ?? []) {
all.push({
group: 'Upstreams',
label: u.id,
hint: u.connected ? undefined : 'not connected',
run: () => void navigate({ to: '/upstreams/$id', params: { id: u.id } }),
})
}

// The catalog is only populated once the operator has connected, so this
// group is absent rather than empty before that.
for (const mode of ['tools', 'prompts', 'resources'] as Mode[]) {
for (const item of catalog?.[mode] ?? []) {
const name = item.name ?? item.uri
if (!name) continue
all.push({
group: 'Catalog',
label: name,
hint: mode.slice(0, -1),
run: () => void navigate({ to: '/test', search: { mode, item: name } }),
})
}
}

return all
}, [state, catalog, navigate])

const matches = useMemo(() => {
const needle = query.trim().toLowerCase()
if (!needle) return items.slice(0, 50)
return items.filter((i) => `${i.label} ${i.group}`.toLowerCase().includes(needle)).slice(0, 50)
}, [items, query])

const selected = Math.min(cursor, Math.max(matches.length - 1, 0))

const run = (item: Item | undefined) => {
if (!item) return
onClose()
item.run()
}

const onKeyDown = (event: KeyboardEvent) => {
if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
event.preventDefault()
if (!matches.length) return
const step = event.key === 'ArrowDown' ? 1 : -1
setCursor((c) => (Math.min(c, matches.length - 1) + step + matches.length) % matches.length)
} else if (event.key === 'Enter') {
event.preventDefault()
run(matches[selected])
}
}

const grouped: Array<{ name: string; items: Array<{ item: Item; index: number }> }> = []
matches.forEach((item, index) => {
const tail = grouped[grouped.length - 1]
if (tail && tail.name === item.group) tail.items.push({ item, index })
else grouped.push({ name: item.group, items: [{ item, index }] })
})

return (
<dialog
ref={dialog}
class="palette"
aria-label="Jump to"
onClose={onClose}
onClick={(e) => {
if (e.target === dialog.current) dialog.current?.close()
}}
>
<div class="pal-input">
<input
value={query}
placeholder="Search routes, upstreams, tools"
aria-label="Search"
role="combobox"
aria-expanded="true"
aria-controls="pal-list"
aria-activedescendant={matches.length ? `pal-${selected}` : undefined}
autocomplete="off"
spellcheck={false}
onInput={(e) => {
setQuery((e.target as HTMLInputElement).value)
setCursor(0)
}}
onKeyDown={onKeyDown}
/>
</div>

{matches.length === 0 ? (
<p class="pal-empty" id="pal-list">
Nothing matches that. Routes, upstream ids and catalog names are searched.
</p>
) : (
<ul class="pal-list" id="pal-list" role="listbox" aria-label="Results">
{grouped.map((group) => (
<li role="group" aria-label={group.name} key={group.name}>
<p class="pal-group" aria-hidden="true">{group.name}</p>
{group.items.map(({ item, index }) => (
<div
key={`${group.name}:${item.label}`}
id={`pal-${index}`}
role="option"
class="pal-item"
aria-selected={index === selected}
onMouseEnter={() => setCursor(index)}
onClick={() => run(item)}
>
<span class="pal-label">{item.label}</span>
{item.hint ? <span class="pal-hint">{item.hint}</span> : null}
</div>
))}
</li>
))}
</ul>
)}

<p class="pal-foot">↑ ↓ to move, Enter to open, Esc to close</p>
</dialog>
)
}
34 changes: 34 additions & 0 deletions src/components/Shell.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ import { Link, useRouterState } from '@tanstack/react-router'
import { useEffect, useRef, useState } from 'react'
import type { ComponentChildren } from 'preact'
import { Wordmark } from './Wordmark'
import { Palette } from './Palette'
import { useMcp } from './McpProvider'
import type { FederationState } from '@/lib/federation'
import { FreshnessIndicator } from './Freshness'
import { useSession, setToken, clearToken } from '@/lib/session'
import { displayVersion } from '@/lib/version'
Expand All @@ -27,6 +30,8 @@ const NAV: NavItem[] = [
]

interface Props {
/** The snapshot, for the palette's upstream entries. */
federation: FederationState | undefined
version: string | undefined
authRequired: boolean | undefined
hint: AuthHint | null
Expand All @@ -41,6 +46,7 @@ interface Props {
}

export function Shell({
federation,
version,
authRequired,
hint,
Expand All @@ -53,7 +59,23 @@ export function Shell({
children,
}: Props) {
const session = useSession()
const mcp = useMcp()
const [palette, setPalette] = useState(false)
const [draft, setDraft] = useState('')

// Owned here rather than in the dialog, so the shortcut works before it has
// ever been opened. Ctrl as well as Meta: an operator on Linux is the
// common case for a self-hosted gateway, not the exception.
useEffect(() => {
const onKey = (e: KeyboardEvent) => {
if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') {
e.preventDefault()
setPalette((open) => !open)
}
}
document.addEventListener('keydown', onKey)
return () => document.removeEventListener('keydown', onKey)
}, [])
const pathname = useRouterState({ select: (s) => s.location.pathname })
const main = useRef<HTMLElement>(null)

Expand Down Expand Up @@ -86,6 +108,10 @@ export function Shell({
<div class="auth">
<FreshnessIndicator updatedAt={updatedAt} fetching={refreshing} failed={failed} />

<button type="button" onClick={() => setPalette(true)} aria-keyshortcuts="Meta+K Control+K">
Jump to
</button>

{hint?.oauth && !signedIn ? (
<button type="button" onClick={onSignIn}>
Sign in
Expand Down Expand Up @@ -154,6 +180,14 @@ export function Shell({
</main>
</div>

{palette ? (
<Palette
state={federation}
catalog={mcp.catalog}
onClose={() => setPalette(false)}
/>
) : null}

<RouteAnnouncer section={section} />

<footer>
Expand Down
Loading
Loading