@knpkv/rly 0.13.0 → 0.15.0

package/README.md

@@ -31,7 +31,10 @@ Import the global layers once at the application boundary:
 @import "@knpkv/rly/styles.css";
 ```
 
-The stylesheet contains self-hosted Geist and Geist Mono variable fonts,
+The stylesheet contains self-hosted Geist and Geist Mono variable fonts (with
+`font-display: optional`: preload each file in `RLY_FONT_FACES` from your own
+origin with `crossorigin`, and Geist renders from first paint; a late face keeps
+the metric-matched fallback for that page view rather than swapping),
 semantic `light-dark()` color pairs, typography, spacing, shape, motion, a
 scoped reset, and base styles. Set `data-theme="light|dark|system"` on the rly
 root; system is the default. Forced colors and reduced motion are handled
@@ -448,6 +451,75 @@ target, expected revision, impact, and evidence beside a named human reviewer.
 Its owned authorization button stays disabled until the controlled exact-action
 confirmation is checked, and terminal outcomes remain visible after review.
 
+`RelayMark` is Relay's mark, the baton: two open hooks with a stroke passed between
+them. The bare mark is drawn in the current colour, so it follows its host's text in
+every theme and in forced colours; sizes are 16, 20 (default), 24 and 32px, and 16px
+stays legible in one colour. `RelayMark.Tile` sets it on the agent colour (20, 24 or
+32px); in forced colours the tile becomes an outline in its context's colour
+(LinkText in a link, ButtonText in a button). Both are decorative
+unless given a `label`. The same mark on its tile ships as `@knpkv/rly/relay-mark.svg`
+for a host's favicon.
+
+`RelayLauncher` is the header button that opens and closes Relay: the mark, a label
+("Relay" unless the host names it) and the Ctrl/⌘+J hint. It sits in the host's header
+like any other control, never fixed over the page. `expanded` drives `aria-expanded`,
+and `aria-keyshortcuts` names the shortcut while the visible hint stays hidden from
+assistive technology. `shortcut` is required: pass `useRelayShortcut()` (Ctrl/⌘+J for
+the platform) only when the host binds that key and prevents the browser's own Ctrl+J,
+or `null` where it binds none, such as a live terminal that keeps its chords.
+The hint hides at 40rem and below, and the button is 32px tall, 44px for a coarse pointer.
+
+`RelayComposer` is Relay's message box: it grows with its text up to 12 lines or 40%
+of the viewport, Enter adds a line and Ctrl/⌘+Enter sends (said beside Send), and an
+IME composition never sends. Context refs are removable chips. One `preset` slot holds
+the run preset. Stop appears only when the host passes `onStop`. While `busyReason` is
+set, Send stays focusable and announces why it is unavailable. `useRelayDraft(objectKey, { newRequestId })`
+keeps the draft per object (the JSON ObjectRef) for the page, so closing, reopening or
+resizing Relay keeps it and one object's draft never sends as another's; pass
+`storage: () => sessionStorage` to survive a reload (never localStorage). Its
+`submission()` reuses one request id until the text changes, so a retry after an
+uncertain outcome is deduplicated; call `accepted(requestId)` once the server accepts
+that request, which clears the draft unless the user has typed since.
+
+`RelayPanel` is Relay's frame: header (mark, title, exact scope with the revision in
+mono, an optional pin, options, close), tabs whose counts are part of their names, a
+freshness line, a body, and a footer for the composer. Only the body scrolls, so the
+composer never leaves the screen. `overlay` floats over the right of the page with
+no backdrop and no focus trap; render it right after the launcher so Tab order
+follows. `pinned` is a sticky column for the host's grid, and `fullscreen` is a modal
+dialog with the page inert. Escape and the close button call `onClose` and return
+focus to the launcher; closing hides Relay in every presentation, and whether it was
+pinned stays the host's remembered preference. `useRelayPresentation({ pinned,
+minHostWidth })` picks the presentation: full screen at 640 CSS px and narrower,
+pinned only when the user pinned it at 1440 and up with the host's minimum beside the
+440px column, otherwise the overlay. Hosts set `--rly-relay-panel-offset` to their
+sticky header's height and `--app-bottom-inset` to any bar docked at the bottom.
+Full screen portals through `PortalProvider`, so render Relay inside one, and set
+`interactive-widget=resizes-content` in the viewport meta so the full-screen footer
+stays above a phone's on-screen keyboard.
+
+`useRelaySummon` binds that shortcut. From the page it opens Relay and focuses the composer (or, if
+Relay is already open, moves focus to the composer); from inside Relay it takes focus back to where it
+came from, and Relay stays open. Full screen, it closes Relay. Escape closes Relay when focus is inside
+it or Relay is full screen, and returns focus. Only the exact chord is handled and prevented, so Ctrl+K,
+`?`, g-sequences and Alt keys reach the host. On a non-Latin layout the physical J key works; a Latin
+layout uses the J the user sees. Escape is left to an IME composition and to a dialog, listbox or menu
+open inside or opened from Relay, including inside shadow roots. When the element Relay came from is
+gone, focus returns to the `launcher`; after a close, focus returns once Relay has actually closed.
+Attach the returned `regionRef` to Relay's region and `composerRef` to the composer, which is focused
+as soon as it mounts. The hook follows Relay into another document (an iframe portal). Pass the same
+`shortcut` the launcher advertises, or `null` while the host's own surface owns the key; Escape inside
+Relay works either way.
+
+```tsx
+import { RelayLauncher, useRelayShortcut, useRelaySummon } from "@knpkv/rly/patterns"
+
+;const shortcut = useRelayShortcut()
+const { composerRef, regionRef } = useRelaySummon({ fullscreen: false, launcher, onOpenChange: setOpen, open, shortcut })
+
+<RelayLauncher expanded={open} onClick={() => setOpen((value) => !value)} ref={launcher} shortcut={shortcut} />
+```
+
 `RelayDock` is the shared product frame for one adapter-owned Relay thread. It
 starts collapsed, keeps context plus profile and model selection visible above
 the scrolling thread, and accepts explicit ready, loading, empty, error, and