Skip to main content

@react-x11/components

The reference for the components this package ships. The README is the tour — what the package is for, and why a given component is here rather than in react-x11 core. These pages are the details: props, handles, events, and the decisions behind them.

Every page is one directory under src/, and that is not a coincidence — test/docs.test.ts fails if a component has no page or a page has no component.

Components​

PageImportWhat it is
Calendar / DatePicker@react-x11/components/calendarA month grid: one date or a range, any day blockable.
Charts@react-x11/components/chartsCartesian charts; a million points is a normal input.
ColorPicker / ColorField@react-x11/components/color-pickerA colour input: field, hue, alpha, swatches, eyedropper.
Code@react-x11/components/codeA static code block: highlighted, selectable.
CodeEditor@react-x11/components/code-editorMultiline code editing: highlighting, completion.
Flow@react-x11/components/flowA directed-graph editor: nodes, edges, pan and zoom.
Formula@react-x11/components/formulaTeX mathematics: KaTeX layout, native ink, selectable.
Html@react-x11/components/htmlA static HTML + CSS document, selectable, with seams.
Map@react-x11/components/mapsA 2D vector-tile map: pan, zoom, markers, overlays.
Markdown@react-x11/components/markdownStreaming-friendly GFM with cross-block selection.
MediaPlayer@react-x11/components/media-playermpv or VLC, embedded, with real transport control.
QML@react-x11/components/qmlQt's QML language as an authoring layer. No Qt.
ReorderList@react-x11/components/reorderA drag-and-drop list, over core's own drag and drop.
RichTextEditor@react-x11/components/rich-text-editorWYSIWYG editing over ProseMirror; markdown in and out.
Table@react-x11/components/tableA data table: sortable, virtualized, any row height.
Tabs@react-x11/components/tabsOne visible panel at a time, five strip styles.
Terminal@react-x11/components/terminalA real terminal: an embedded emulator, or its own.
TerminalOutput@react-x11/components/terminal-outputA captured session, rendered. <Terminal>'s static sibling.
Three@react-x11/components/threeA three-fiber-shaped 3D scene over either GL backend.
Timeline@react-x11/components/timelineA run of events: a mark per step, a line between.
TrayHost@react-x11/components/tray-hostThe system tray: applications dock their icons in.
Tree@react-x11/components/treeA disclosure tree: seams throughout, and virtualized.

Shared modules​

These are not components — they register nothing, render nothing at import time, and exist because more than one component needs them. They have their own subpaths because an app building a surface of its own needs the same parts.

PageImportWhat it is
ansi@react-x11/components/ansiA captured terminal session, as a document.
richtext@react-x11/components/richtextThe styled-text element a document selects across.
codeblock@react-x11/components/codeblockThe look of a block of code.
code-language@react-x11/components/code-languageThe tokenizer seam, the languages, the palettes.
embed@react-x11/components/embedThe spawn, watch and hand-back lifecycle.

Design documents​

  • A pure-JS VT backend for <Terminal> — the design behind backend="vt".
  • Composable, cost-bounded charts — the decimation pyramid, the command-stream/pixel crossover, and the tooltip-popup policy behind /charts.
  • Rendering a captured session — why a log is a document rather than a grid, and what /ansi and <TerminalOutput> can and cannot represent.
  • The data table — implemented: the prior-art survey, the successor contract with core's <Table>, and the variable-height virtualization it shares with the tree.
  • An HTML control worth having — the pipeline behind <Html>, why the element draws a document rather than composing one, the resource and script seams, the isolated-process mode, and the audit of exposing the seams as a Chrome DevTools Protocol surface.
  • MDX in <Markdown> — block position and expressions shipped: the two gates (components decides what a document may reach, scope whether it may compute), why neither evaluates anything a document that never passed the prop could not already do, and the inline half that is still open on a <richtext> run able to reserve advance width for an embedded element.
  • Maps — the format and provider survey (who serves vector tiles and who does not), the three-cache rendering architecture, and the profile that produced it on both the X11 and the Cocoa backends.
  • Maps on the GPU — the renderer <Map> chooses by default wherever there is direct GL: every frame drawn from vector tiles through <glarea> with no bitmap cache, and the retained renderer as its fallback. The record-stream bucket format, stencil fans instead of triangulation, instanced capsule lines, the measurements against the retained renderer on both backends, and the soak 'auto' became the default on.
  • Adaptive frame pacing — landed upstream: why a pty-fed element must not paint at the display's rate on the Cocoa backend, the frameRate vocabulary react-x11 2.9.0 took into core as the window's policy rather than an element prop, and the opaqueRect() and copy seams the same release opened and the vt terminal adopted.
  • A colour picker — implemented: why the panel belongs here and the screen sampler does not, the CSS-colour value model against what this renderer can actually parse, and the server-side gradients the panes are made of.
  • A drag-and-drop list — implemented: the survey of dnd-kit, hello-pangea/dnd, pragmatic-drag-and-drop, React Aria and Framer's Reorder against the components here, why the engine is core's and this is the sortable layer, the closest-edge model, and why the indicator rather than the slide.
  • The user's calendar on macOS — implemented (react-x11 2.9.1, sidorares/react-x11#508; the deletion here): the survey of every way to reach the user's calendar on a Mac and on Linux, why the desktop-calendar hook moves to react-x11 as a ladder beside notifications and permissions, the EventKit rung through the bridge and the one through osascript that needs no bridge, and the three @windowkit/appkit tickets that unblock the rest.
  • A rich text editor — implemented: the survey of ProseMirror, TipTap, Lexical, Slate, Quill, CKEditor and the native text systems, why the model is ProseMirror's and the view is this package's, the ladder of props from defaultValue to an app-owned EditorState, and the ledger of which parts of EditorView a plugin can count on.

Conventions these pages follow​

  • Props tables list what the component reads, with the default in the description rather than a column of its own — most defaults are a sentence, not a value.
  • Styling is style, always. No component invents a className or a width prop; the root box takes react-x11's style, and that is where width, padding and flexGrow go.
  • data-testname is on every component that renders a host element, for react-x11/test's queries.
  • Nothing here is a hard dependency. Where a component needs a program or a native module, "it is not installed" is an ordinary state with a fallback and a status, never a throw.
  • A page says so when it is not backend-neutral. react-x11 has an X11 backend and a native macOS one, and most of what is here draws through contracts both answer. Where a component needs something only one of them has — XEmbed for <Terminal>'s embedded emulators, <MediaPlayer> and <TrayHost>; the X selection for PRIMARY — its page names the backend rather than leaving the reader to find out on the other one.