opentui-responsive 0.1.0 → 0.2.1

package/README.md

@@ -1,8 +1,17 @@
-# opentui-responsive
-
-Typed responsive breakpoints for OpenTUI, with a framework-neutral core and a Solid adapter.
-
-## Install
+<div align="center">
+  <h1>opentui-responsive</h1>
+  <p>
+    <a href="https://www.npmjs.com/package/opentui-responsive"><img src="https://img.shields.io/npm/v/opentui-responsive" alt="npm version"></a>
+    <a href="https://github.com/itsmeyaw/opentui-responsive/actions/workflows/ci.yml"><img src="https://github.com/itsmeyaw/opentui-responsive/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+    <a href="https://github.com/itsmeyaw/opentui-responsive/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/opentui-responsive" alt="MIT license"></a>
+  </p>
+  <p>Typed responsive breakpoints for OpenTUI, with a framework-neutral core and React and Solid adapters.</p>
+  <p align="center">
+  <img src="docs/assets/demo.gif" alt="opentui-responsive terminal demo">
+</p>
+</div>
+
+## Installation
 
 For OpenTUI Solid applications:
 
@@ -12,31 +21,42 @@ bun add opentui-responsive @opentui/solid solid-js
 npm install opentui-responsive @opentui/solid solid-js
 ```
 
+For OpenTUI React applications:
+
+```sh
+bun add opentui-responsive @opentui/react react
+# or
+npm install opentui-responsive @opentui/react react
+```
+
 Core-only consumers only need `opentui-responsive`.
 
-## Solid
+## Usage
 
-Define mobile-first tiers once, then create a provider and hook bound to that definition:
+Define mobile-first tiers, then create a Solid provider and hook bound to that definition:
 
 ```tsx
 import { defineBreakpoints } from "opentui-responsive/core";
 import { createResponsiveTui } from "opentui-responsive/solid";
 
 const breakpoints = defineBreakpoints({
-  width: {
-    narrow: 0,
-    medium: 60,
-    wide: 100,
-  },
-  height: {
-    short: 0,
-    medium: 12,
-    tall: 20,
-  },
+  width: { narrow: 0, medium: 60, wide: 100 },
+  height: { short: 0, medium: 16, tall: 28 },
 });
 
 const { ResponsiveTUI, useResponsiveTui } = createResponsiveTui(breakpoints);
 
+function Content() {
+  const breakpoint = useResponsiveTui();
+
+  return (
+    <box flexDirection={breakpoint().width === "wide" ? "row" : "column"}>
+      <text>{`${breakpoint().width}/${breakpoint().height}`}</text>
+      <text>{breakpoint(["wide", "tall"]) ? "Full layout" : "Compact layout"}</text>
+    </box>
+  );
+}
+
 function App() {
   return (
     <ResponsiveTUI>
@@ -44,94 +64,63 @@ function App() {
     </ResponsiveTUI>
   );
 }
-
-function Content() {
-  const breakpoint = useResponsiveTui();
-  return <text>{`${breakpoint().width}/${breakpoint().height}`}</text>;
-}
 ```
 
-`useResponsiveTui()` returns a Solid accessor. Each axis has its own inferred name union and updates when that terminal dimension crosses a configured threshold. In this example, width is `"narrow" | "medium" | "wide"`, height is `"short" | "medium" | "tall"`, and a `120 x 10` terminal returns `{ width: "wide", height: "short" }`.
+`useResponsiveTui()` updates when the terminal crosses a configured threshold. Its accessor returns the current width and height names, or accepts an exact `[width, height]` pair and returns whether both axes match.
 
-Pass an exact `[width, height]` pair to check both axes reactively:
+Run `bun run demo` from the package directory to try the Solid example. Resize the terminal to see its layout respond.
 
-```ts
-breakpoint(["narrow", "tall"]); // boolean
-```
+The React adapter has the same factory, provider, hook, and inferred breakpoint types; import `createResponsiveTui` from `opentui-responsive/react` instead.
 
-The pair must contain exactly one configured name for each axis, in width-then-height order.
+## API Reference
 
-TypeScript rejects names that are not configured for that axis:
+### `opentui-responsive/core`
 
-```ts
-breakpoint().height === "extra-tall";
-// Type error: "extra-tall" is not a configured height breakpoint
-```
-
-## Tiers
+| API                                  | Description                                                                          |
+| ------------------------------------ | ------------------------------------------------------------------------------------ |
+| `defineBreakpoints(scales)`          | Validates width and height scales and returns typed `match` and `matches` functions. |
+| `definition.match(viewport)`         | Returns the highest inclusive breakpoint reached on each axis.                       |
+| `definition.matches(viewport, pair)` | Tests an exact `[width, height]` breakpoint pair.                                    |
+| `BreakpointOf<Input, Axis>`          | Extracts the inferred breakpoint-name union for one axis.                            |
+| `BreakpointAxis`                     | The `"width" \| "height"` axis union.                                                |
+| `BreakpointScale`                    | A map of breakpoint names to minimum terminal-cell thresholds.                       |
+| `BreakpointScales`                   | The width and height scale configuration.                                            |
+| `BreakpointViewport`                 | Explicit width and height dimensions to match.                                       |
+| `BreakpointMatch`                    | The matched breakpoint name for each axis.                                           |
+| `BreakpointPair`                     | An exact breakpoint pair in width-then-height order.                                 |
+| `BreakpointDefinition`               | The typed result of `defineBreakpoints`.                                             |
+| `ResponsiveTuiConfigurationError`    | Thrown when breakpoint scales are invalid.                                           |
 
-Width and height define independent sets of inclusive minimum thresholds in terminal cells. Each axis is matched to its highest satisfied threshold, so the number and names of options can differ between axes.
+### `opentui-responsive/solid` and `opentui-responsive/react`
 
-Breakpoint names must be non-empty strings. Thresholds must be unique finite non-negative integers within their axis.
+| API                               | Description                                                                        |
+| --------------------------------- | ---------------------------------------------------------------------------------- |
+| `createResponsiveTui(definition)` | Creates a framework-specific `ResponsiveTUI` provider and `useResponsiveTui` hook. |
+| `ResponsiveTUI`                   | Tracks terminal dimensions and provides the current breakpoint accessor.           |
+| `useResponsiveTui()`              | Reads the accessor from the nearest generated provider.                            |
+| `ResponsiveBreakpointAccessor`    | Reads the current match or tests an exact breakpoint pair.                         |
+| `ResponsiveTuiProviderError`      | Thrown when the generated hook is called outside its provider.                     |
 
-Each axis must include a zero threshold so every terminal dimension has a match:
+## Breakpoint Behavior
 
-```ts
-width: { narrow: 0, medium: 60, wide: 100 },
-height: { short: 0, medium: 12, tall: 20 },
-```
+Width and height use independent sets of inclusive minimum thresholds measured in terminal cells. Each axis must contain a zero threshold so every terminal size has a match. Names must be non-empty, and thresholds must be unique finite non-negative integers within their axis.
 
-Declaration order does not affect matching:
+Declaration order does not affect matching. Each axis selects its highest satisfied threshold:
 
 ```ts
-width: { wide: 100, narrow: 0, medium: 60 },
-```
-
-Invalid definitions throw `ResponsiveTuiConfigurationError` during configuration. Calling a generated hook outside its provider throws `ResponsiveTuiProviderError`.
-
-Use breakpoints for discrete layout modes. Keep continuous measurements such as progress-bar width and available list height on OpenTUI's `useTerminalDimensions()`.
-
-## Core
-
-The core definition has no framework dependencies and can match explicit dimensions directly:
+const breakpoints = defineBreakpoints({
+  width: { wide: 100, narrow: 0, medium: 60 },
+  height: { tall: 28, short: 0, medium: 16 },
+});
 
-```ts
-const current = breakpoints.match({ width: 120, height: 10 });
+breakpoints.match({ width: 120, height: 10 });
 // { width: "wide", height: "short" }
-
-const exact = breakpoints.matches({ width: 120, height: 10 }, ["wide", "short"]);
-// true
-```
-
-Extract an axis's inferred name union with `BreakpointOf`:
-
-```ts
-type WidthBreakpoint = BreakpointOf<typeof breakpoints, "width">;
-type HeightBreakpoint = BreakpointOf<typeof breakpoints, "height">;
 ```
 
-## Packaging
-
-The package is ESM-only. `opentui-responsive/core` and `opentui-responsive/solid` are separate package entrypoints, and the package is marked side-effect free so modern bundlers can remove unused exports. Importing `/core` does not load Solid or OpenTUI.
-
-## Runtime support
-
-The package supports Bun 1.3.0 or later and Node.js 26.4.0 or later. Node.js applications must use ESM. CommonJS `require()` is not supported.
-
-The `/core` entrypoint is pure JavaScript and does not require native FFI:
-
-```sh
-node core-example.mjs
-```
-
-The `/solid` entrypoint inherits OpenTUI's native runtime requirements. Start Node.js applications that use it with:
-
-```sh
-node --experimental-ffi app.mjs
-```
+Use breakpoints for discrete layout modes. Keep continuous measurements such as progress-bar width and available list height on OpenTUI's `useTerminalDimensions()`.
 
-Use Bun 1.4.0 or later on native Windows arm64.
+## Runtime Support
 
-## Publishing
+The package is ESM-only and supports Bun 1.3.0 or later and Node.js 26.4.0 or later. CommonJS `require()` is not supported.
 
-Publishing a GitHub release whose tag matches the package version triggers `.github/workflows/publish.yml`. Configure npm trusted publishing for the `itsmeyaw/opentui-responsive` repository, the `publish.yml` workflow, and direct `npm publish` access; no `NPM_TOKEN` secret is used.
+The `/core` entrypoint is pure JavaScript and does not require native FFI. The `/react` and `/solid` entrypoints inherit OpenTUI's native runtime requirements; Node.js applications using an adapter must start with `node --experimental-ffi app.mjs`. Use Bun 1.4.0 or later on native Windows arm64.

package/dist/core/index.d.ts

@@ -1,27 +1,42 @@
+/** A terminal dimension used to select a breakpoint. */
 export type BreakpointAxis = "width" | "height";
+/** Named inclusive minimum thresholds for one terminal dimension. */
 export type BreakpointScale = Readonly<Record<string, number>>;
+/** Independent breakpoint scales for terminal width and height. */
 export type BreakpointScales = {
     readonly width: BreakpointScale;
     readonly height: BreakpointScale;
 };
+/** Terminal dimensions in cells. */
 export type BreakpointViewport = {
     readonly width: number;
     readonly height: number;
 };
+/** The breakpoint name matched on each axis. */
 export type BreakpointMatch<Scales extends BreakpointScales = BreakpointScales> = {
     readonly [Axis in BreakpointAxis]: Extract<keyof Scales[Axis], string>;
 };
+/** An exact breakpoint pair in width-then-height order. */
 export type BreakpointPair<Scales extends BreakpointScales = BreakpointScales> = readonly [
     width: BreakpointMatch<Scales>["width"],
     height: BreakpointMatch<Scales>["height"]
 ];
+/** A validated breakpoint definition that matches explicit terminal dimensions. */
 export type BreakpointDefinition<Scales extends BreakpointScales = BreakpointScales> = {
+    /** Returns the highest inclusive breakpoint reached on each axis. */
     readonly match: (viewport: BreakpointViewport) => BreakpointMatch<Scales>;
+    /** Tests whether a viewport matches an exact width and height pair. */
     readonly matches: (viewport: BreakpointViewport, pair: BreakpointPair<Scales>) => boolean;
 };
+/** Extracts the configured breakpoint-name union for one axis. */
 export type BreakpointOf<Input, Axis extends BreakpointAxis> = Input extends BreakpointDefinition<infer Scales> ? Extract<keyof Scales[Axis], string> : Input extends BreakpointScales ? Extract<keyof Input[Axis], string> : never;
+/** Thrown when breakpoint scales cannot produce a valid definition. */
 export declare class ResponsiveTuiConfigurationError extends Error {
     readonly _tag = "ResponsiveTuiConfigurationError";
     constructor(message: string);
 }
+/**
+ * Creates a typed breakpoint definition from inclusive width and height thresholds.
+ * Each axis must contain a zero threshold.
+ */
 export declare const defineBreakpoints: <const Scales extends BreakpointScales>(scales: Scales & Record<Exclude<keyof Scales, BreakpointAxis>, never>) => BreakpointDefinition<Scales>;

package/dist/core/index.js

@@ -74,6 +74,6 @@ var matchScale = (value, entries) => {
 var isRecord = (value) => typeof value === "object" && value !== null;
 var isThreshold = (value) => typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
 export {
-  defineBreakpoints,
-  ResponsiveTuiConfigurationError
+  ResponsiveTuiConfigurationError,
+  defineBreakpoints
 };

package/dist/react/index.d.ts

@@ -0,0 +1,17 @@
+import { type PropsWithChildren } from "react";
+import type { BreakpointDefinition, BreakpointMatch, BreakpointPair, BreakpointScales } from "../core/index.js";
+/** A React accessor that reads or tests the current breakpoint pair. */
+export type ResponsiveBreakpointAccessor<Scales extends BreakpointScales = BreakpointScales> = {
+    (): BreakpointMatch<Scales>;
+    (pair: BreakpointPair<Scales>): boolean;
+};
+/** Thrown when a responsive hook is used outside its generated React provider. */
+export declare class ResponsiveTuiProviderError extends Error {
+    readonly _tag = "ResponsiveTuiProviderError";
+    constructor();
+}
+/** Creates a React provider and hook bound to one breakpoint definition. */
+export declare const createResponsiveTui: <const Scales extends BreakpointScales>(breakpoints: BreakpointDefinition<Scales>) => {
+    ResponsiveTUI: (props: PropsWithChildren) => import("react").FunctionComponentElement<import("react").ProviderProps<ResponsiveBreakpointAccessor<Scales> | undefined>>;
+    useResponsiveTui: () => ResponsiveBreakpointAccessor<Scales>;
+};

package/dist/react/index.js

@@ -0,0 +1,31 @@
+// src/react/index.ts
+import { useTerminalDimensions } from "@opentui/react";
+import { createContext, createElement, useContext } from "react";
+
+class ResponsiveTuiProviderError extends Error {
+  _tag = "ResponsiveTuiProviderError";
+  constructor() {
+    super("useResponsiveTui must be used within a ResponsiveTUI");
+    this.name = this._tag;
+  }
+}
+var createResponsiveTui = (breakpoints) => {
+  const ResponsiveTuiContext = createContext(undefined);
+  const ResponsiveTUI = (props) => {
+    const dimensions = useTerminalDimensions();
+    const breakpoint = (pair) => pair ? breakpoints.matches(dimensions, pair) : breakpoints.match(dimensions);
+    return createElement(ResponsiveTuiContext.Provider, { value: breakpoint }, props.children);
+  };
+  const useResponsiveTui = () => {
+    const breakpoint = useContext(ResponsiveTuiContext);
+    if (!breakpoint) {
+      throw new ResponsiveTuiProviderError;
+    }
+    return breakpoint;
+  };
+  return { ResponsiveTUI, useResponsiveTui };
+};
+export {
+  ResponsiveTuiProviderError,
+  createResponsiveTui
+};

package/dist/solid/index.d.ts

@@ -1,13 +1,16 @@
 import { type ParentProps } from "solid-js";
 import type { BreakpointDefinition, BreakpointMatch, BreakpointPair, BreakpointScales } from "../core/index.js";
+/** A reactive Solid accessor that reads or tests the current breakpoint pair. */
 export type ResponsiveBreakpointAccessor<Scales extends BreakpointScales = BreakpointScales> = {
     (): BreakpointMatch<Scales>;
     (pair: BreakpointPair<Scales>): boolean;
 };
+/** Thrown when a responsive hook is used outside its generated Solid provider. */
 export declare class ResponsiveTuiProviderError extends Error {
     readonly _tag = "ResponsiveTuiProviderError";
     constructor();
 }
+/** Creates a Solid provider and hook bound to one breakpoint definition. */
 export declare const createResponsiveTui: <const Scales extends BreakpointScales>(breakpoints: BreakpointDefinition<Scales>) => {
     ResponsiveTUI: (props: ParentProps) => any;
     useResponsiveTui: () => ResponsiveBreakpointAccessor<Scales>;

package/dist/solid/index.js

@@ -1,4 +1,4 @@
-// src/solid/index.tsx
+// src/solid/index.ts
 import { useTerminalDimensions } from "@opentui/solid";
 import { createContext, createMemo, useContext } from "solid-js";
 
@@ -29,12 +29,9 @@ var createResponsiveTui = (breakpoints) => {
     }
     return breakpoint;
   };
-  return {
-    ResponsiveTUI,
-    useResponsiveTui
-  };
+  return { ResponsiveTUI, useResponsiveTui };
 };
 export {
-  createResponsiveTui,
-  ResponsiveTuiProviderError
+  ResponsiveTuiProviderError,
+  createResponsiveTui
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentui-responsive",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Typed responsive breakpoints for OpenTUI.",
   "license": "MIT",
   "repository": {
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist",
+    "docs/assets/demo.gif",
     "README.md",
     "LICENSE"
   ],
@@ -24,16 +25,23 @@
       "types": "./dist/solid/index.d.ts",
       "import": "./dist/solid/index.js",
       "default": "./dist/solid/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "accept:node": "node scripts/accept-node-core.mjs && node --experimental-ffi scripts/accept-node-solid.mjs",
+    "accept:node": "node scripts/accept-node-core.mjs && node --experimental-ffi scripts/accept-node-solid.mjs && node --experimental-ffi scripts/accept-node-react.mjs",
     "build": "bun build.ts && tsc -p tsconfig.build.json",
     "check": "bun run format:check && bun run lint && bun run typecheck && bun test && bun run build && bun run check:package && bun run accept:node",
     "check:package": "bun package-check.ts && publint --strict && attw --pack . --profile esm-only",
+    "demo": "bun --preload @opentui/solid/preload examples/solid.tsx",
+    "demo:react": "bun examples/react.tsx",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "lint": "oxlint --deny-warnings .",
@@ -43,22 +51,34 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
+    "@opentui/core": "0.5.11",
+    "@opentui/react": "0.5.11",
     "@opentui/solid": "0.5.11",
     "@types/bun": "latest",
+    "@types/react": "19.2.0",
     "oxfmt": "latest",
     "oxlint": "1.82.0",
     "publint": "0.3.24",
+    "react": "19.2.0",
     "solid-js": "1.9.12",
     "typescript": "5.9.3"
   },
   "peerDependencies": {
+    "@opentui/react": "^0.5.11",
     "@opentui/solid": "^0.5.11",
+    "react": ">=19.2.0",
     "solid-js": "1.9.12"
   },
   "peerDependenciesMeta": {
+    "@opentui/react": {
+      "optional": true
+    },
     "@opentui/solid": {
       "optional": true
     },
+    "react": {
+      "optional": true
+    },
     "solid-js": {
       "optional": true
     }