@react-x11/components 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Andrey Sidorov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# @react-x11/components
+
+Components for [react-x11](https://github.com/sidorares/react-x11) that do
+not belong in the core package.
+
+Everything here is built on react-x11's public API — the built-in host
+elements, or the `registerElement` seam in `react-x11/host`. Nothing here
+needs a change to core to exist, and core does not grow to carry it.
+
+> **Not published yet.** This package needs react-x11 2.0.0, which is not on
+> npm — the subpath exports it imports (`react-x11/host`, `/node`, `/style`,
+> `/test`) are on core's `master`, unreleased. Until then, use it from a
+> checkout.
+
+## What is here, and what is in core
+
+react-x11 itself carries an element or component when **any** of these hold:
+
+- the vast majority of UI apps use it;
+- it depends on renderer internals — implementing it outside would mean
+  exposing details that should not be public, or giving up performance;
+- it needs enough standards compliance that the behaviour is hard to agree on
+  or implement piecemeal.
+
+This package carries it when **all** of these hold:
+
+- a smaller fraction of apps need it;
+- it can be built on the public react-x11 API;
+- it is big enough that core would pay for it, in install closure or in
+  maintenance.
+
+So `<box>`, `<text>`, `<window>`, buttons, menus, dialogs and the rest of the
+widget set are core. Heavier, more specialised things live here.
+
+The line can also fall inside a single feature. `<glarea>` is core — it is a
+real X window on a GLX visual, which is renderer internals. A Three.js-shaped
+scene graph drawn into it is not: that is composition over a public element,
+and it belongs here.
+
+## Install
+
+```bash
+npm install @react-x11/components
+```
+
+`react` and `react-x11` are peer dependencies — deliberately. Registering a
+host element mutates state inside react-x11, so a second copy of the renderer
+would leave you with an element that lays out correctly and never paints.
+
+## Usage
+
+```jsx
+import { Sparkline } from '@react-x11/components';
+
+function App() {
+  return (
+    <window width={360} height={160} title="components">
+      <box style={{ flexGrow: 1, padding: 16 }}>
+        <Sparkline
+          data={[3, 7, 4, 9, 6, 11, 8]}
+          color="#c0392b"
+          strokeWidth={2}
+          style={{ width: 320, height: 80 }}
+        />
+      </box>
+    </window>
+  );
+}
+```
+
+Importing a component is what teaches react-x11 its element, so there is no
+setup call to remember and no registration to run at startup.
+
+## Tree-shaking
+
+Use one component, pay for one component. Each is its own module with its own
+entry point, the package declares `"sideEffects": false`, and importing the
+barrel for nothing at all bundles to nothing. That last property is a test in
+this repo, not an aspiration.
+
+Deep imports work too, for apps without a bundler:
+
+```js
+import { Sparkline } from '@react-x11/components/sparkline';
+```
+
+## Components
+
+| Component   | Import                            |                                                |
+| ----------- | --------------------------------- | ---------------------------------------------- |
+| `Sparkline` | `@react-x11/components/sparkline` | A bare line chart. Needs a width and a height. |
+
+## Roadmap
+
+Candidates to move here, none of them moved yet:
+
+- `<markdown>` and `<html>`, currently in react-x11 over ntk's document
+  widgets. `<svg>` and `<tex>` stay in ntk. Mermaid was dropped rather than
+  extracted — 155 MB of install closure for a grammar.
+- The 3D scene graph and a Three.js / react-three-fiber-shaped layer, with
+  `<glarea>` itself staying in core.
+- A react-flow-style node/edge graph editor.
+- `<Tabs>`, undecided — it may well stay in core.
+
+## Contributing
+
+[AGENTS.md](AGENTS.md) is the contributor guide: the rule for what belongs
+here, the layout, the tree-shaking constraints, and the two ways a registered
+element fails silently.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@react-x11/components",
+  "version": "0.1.0",
+  "description": "Components for react-x11 that do not belong in the core package",
+  "keywords": [
+    "react",
+    "react-x11",
+    "x11",
+    "components",
+    "widgets",
+    "desktop",
+    "ui"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sidorares/react-x11-components.git"
+  },
+  "author": "Andrey Sidorov <andrey.sidorov@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "files": [
+    "src"
+  ],
+  "sideEffects": false,
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./sparkline": {
+      "types": "./src/sparkline/index.d.ts",
+      "default": "./src/sparkline/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check:package": "node scripts/check-package.mjs",
+    "examples:sparkline": "tsx examples/sparkline.jsx"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-x11": "^2.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.32.0",
+    "@types/react": "^19.2.17",
+    "esbuild": "^0.28.1",
+    "eslint": "^9.32.0",
+    "eslint-plugin-react": "^7.37.5",
+    "globals": "^17.8.0",
+    "prettier": "^3.6.0",
+    "react": "^19.2.8",
+    "react-x11": "github:sidorares/react-x11#master",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,2 @@
+export { Sparkline, SPARKLINE_ELEMENT } from './sparkline/index.js';
+export type { SparklineProps } from './sparkline/index.js';

package/src/index.js

@@ -0,0 +1,9 @@
+// The convenience barrel. `import { Sparkline } from '@react-x11/components'`
+// and `import { Sparkline } from '@react-x11/components/sparkline'` are the
+// same module either way — with `sideEffects: false` and no side effects at
+// this level, a bundler drops the components an app does not name.
+//
+// This file must never do more than re-export. Anything with a side effect
+// here (a registration, a theme install, a feature probe) runs for every
+// consumer of the barrel and takes the whole package into their bundle.
+export { Sparkline, SPARKLINE_ELEMENT } from './sparkline/index.js';

package/src/sparkline/index.d.ts

@@ -0,0 +1,29 @@
+import type { ReactElement } from 'react';
+import type { Style } from 'react-x11/style';
+
+export interface SparklineProps {
+  /** The series. Fewer than two points draws nothing. */
+  data: number[];
+  /** Stroke colour. Falls back to `style.color`, then black. */
+  color?: string;
+  /** Pen width in pixels. Default `1`. */
+  strokeWidth?: number;
+  /** No intrinsic size — give it a width and a height. */
+  style?: Style | Style[];
+}
+
+export declare function Sparkline(props: SparklineProps): ReactElement;
+
+/** The host element name, for apps that would rather write `<sparkline>`. */
+export declare const SPARKLINE_ELEMENT: 'sparkline';
+
+// Importing this module teaches JSX the element too, so `<sparkline>` is a
+// typed tag and not an error. This is the module-augmentation shape
+// react-x11's docs/typescript.md prescribes for a third-party element.
+declare module 'react-x11/jsx-runtime' {
+  namespace JSX {
+    interface IntrinsicElements {
+      sparkline: SparklineProps;
+    }
+  }
+}

package/src/sparkline/index.js

@@ -0,0 +1,50 @@
+// <Sparkline> — a bare line chart, and the worked example of the
+// `registerElement` path this whole package is built on. react-x11's own
+// docs/extending.md illustrates the seam with a `<sparkline>`; this is that
+// element, shipped.
+//
+// **Registration happens when this module is evaluated**, and that is the
+// design, not a shortcut. Nothing in the package registers anything until
+// an app imports the component that needs it, so `sideEffects: false` stays
+// honest: an app that never renders a sparkline ships none of this. Do not
+// move registration up into `../index.js` — that is the one edit that would
+// make the barrel pull every component into every bundle.
+import React from 'react';
+import { registerElement, registeredElements } from 'react-x11/host';
+
+import { ELEMENT, SparklineNode } from './node.js';
+
+// Idempotent on purpose. `registerElement` throws on a second registration
+// without `override`, which is the right default for two *packages* fighting
+// over a name — but an app that ends up with two copies of this one (a
+// version skew in someone's lockfile) should not fail to boot over it.
+if (!registeredElements().includes(ELEMENT)) {
+  registerElement(ELEMENT, {
+    create: (props, app) => new SparklineNode(props, app),
+    // `color` is also a style name. Without declaring it the element throws
+    // on its own props in development and works in production — the worst
+    // shape a bug can have, so react-x11 asks elements to say so.
+    semanticNames: ['data', 'color', 'strokeWidth'],
+    childrenAllowed: false,
+  });
+}
+
+/**
+ * A sparkline. Has no intrinsic size — give it one through `style`, the way
+ * react-x11's own `<canvas>` wants one:
+ *
+ * ```jsx
+ * <Sparkline data={[1, 4, 2, 8]} color="#c0392b"
+ *            style={{ width: 120, height: 40 }} />
+ * ```
+ *
+ * The component is a thin handle on the host element rather than a wrapper
+ * with behaviour of its own: it exists to carry the types, to be the thing
+ * an app imports (and therefore the thing that triggers registration), and
+ * to be the seam if this ever grows props that are not the element's.
+ */
+export function Sparkline(props) {
+  return React.createElement(ELEMENT, props);
+}
+
+export { ELEMENT as SPARKLINE_ELEMENT };

package/src/sparkline/node.js

@@ -0,0 +1,72 @@
+// The retained node behind <sparkline>. `./index.js` is the only module
+// that imports this one, and it is also the module that registers the
+// element — so the pair is reachable exactly when an app imports
+// `Sparkline`, and droppable as a unit when it does not (see AGENTS.md,
+// "Tree-shaking is a constraint, not a nice-to-have").
+import { Node } from 'react-x11/node';
+
+/**
+ * The element name. The registration key, the node's `kind` and the JSX tag
+ * are all this one string — react-x11 rejects a node whose `kind` is
+ * anything but the name it was registered under, because `kind` is what
+ * paint order, queries and the DEV style assertion match on.
+ */
+export const ELEMENT = 'sparkline';
+
+const DEFAULT_COLOR = '#000000';
+
+export class SparklineNode extends Node {
+  constructor(props, app) {
+    super(ELEMENT, props, app);
+  }
+
+  paint(ctx) {
+    // background, border and the clip to this node's rect
+    super.paint(ctx);
+
+    const data = this.props.data;
+    if (!Array.isArray(data) || data.length < 2) return;
+    // The mock backend in `react-x11/test` has no path API. A component
+    // that throws there cannot be tested headlessly, and headless is where
+    // CI runs — so the drawing is skipped rather than attempted.
+    if (typeof ctx.beginPath !== 'function') return;
+
+    const { x, y, width, height } = this.abs;
+    if (width <= 0 || height <= 0) return;
+
+    const lineWidth = this.props.strokeWidth ?? 1;
+    // `super.paint` clipped to `abs`, so a stroke sitting on the top or
+    // bottom edge would be cut in half. Inset by half the pen.
+    const inset = lineWidth / 2;
+    const top = y + inset;
+    const usable = Math.max(0, height - lineWidth);
+
+    let min = Infinity;
+    let max = -Infinity;
+    for (const value of data) {
+      if (value < min) min = value;
+      if (value > max) max = value;
+    }
+    const span = max - min;
+
+    const stepX = width / (data.length - 1);
+
+    ctx.save();
+    ctx.beginPath();
+    for (let i = 0; i < data.length; i++) {
+      const px = x + stepX * i;
+      // A flat series has no span to scale against; draw it down the middle
+      // rather than dividing by zero or pinning it to an edge.
+      const py =
+        span === 0
+          ? y + height / 2
+          : top + usable * (1 - (data[i] - min) / span);
+      if (i === 0) ctx.moveTo(px, py);
+      else ctx.lineTo(px, py);
+    }
+    ctx.lineWidth = lineWidth;
+    ctx.strokeStyle = this.props.color ?? this.style.color ?? DEFAULT_COLOR;
+    ctx.stroke();
+    ctx.restore();
+  }
+}