opentui-responsive 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Yudhistira Arief Wibowo
+
+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,137 @@
+# opentui-responsive
+
+Typed responsive breakpoints for OpenTUI, with a framework-neutral core and a Solid adapter.
+
+## Install
+
+For OpenTUI Solid applications:
+
+```sh
+bun add opentui-responsive @opentui/solid solid-js
+# or
+npm install opentui-responsive @opentui/solid solid-js
+```
+
+Core-only consumers only need `opentui-responsive`.
+
+## Solid
+
+Define mobile-first tiers once, then create a 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,
+  },
+});
+
+const { ResponsiveTUI, useResponsiveTui } = createResponsiveTui(breakpoints);
+
+function App() {
+  return (
+    <ResponsiveTUI>
+      <Content />
+    </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" }`.
+
+Pass an exact `[width, height]` pair to check both axes reactively:
+
+```ts
+breakpoint(["narrow", "tall"]); // boolean
+```
+
+The pair must contain exactly one configured name for each axis, in width-then-height order.
+
+TypeScript rejects names that are not configured for that axis:
+
+```ts
+breakpoint().height === "extra-tall";
+// Type error: "extra-tall" is not a configured height breakpoint
+```
+
+## Tiers
+
+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.
+
+Breakpoint names must be non-empty strings. Thresholds must be unique finite non-negative integers within their axis.
+
+Each axis must include a zero threshold so every terminal dimension has a match:
+
+```ts
+width: { narrow: 0, medium: 60, wide: 100 },
+height: { short: 0, medium: 12, tall: 20 },
+```
+
+Declaration order does not affect matching:
+
+```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:
+
+```ts
+const current = 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 Bun 1.4.0 or later on native Windows arm64.
+
+## Publishing
+
+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.

package/dist/core/index.d.ts

@@ -0,0 +1,27 @@
+export type BreakpointAxis = "width" | "height";
+export type BreakpointScale = Readonly<Record<string, number>>;
+export type BreakpointScales = {
+    readonly width: BreakpointScale;
+    readonly height: BreakpointScale;
+};
+export type BreakpointViewport = {
+    readonly width: number;
+    readonly height: number;
+};
+export type BreakpointMatch<Scales extends BreakpointScales = BreakpointScales> = {
+    readonly [Axis in BreakpointAxis]: Extract<keyof Scales[Axis], string>;
+};
+export type BreakpointPair<Scales extends BreakpointScales = BreakpointScales> = readonly [
+    width: BreakpointMatch<Scales>["width"],
+    height: BreakpointMatch<Scales>["height"]
+];
+export type BreakpointDefinition<Scales extends BreakpointScales = BreakpointScales> = {
+    readonly match: (viewport: BreakpointViewport) => BreakpointMatch<Scales>;
+    readonly matches: (viewport: BreakpointViewport, pair: BreakpointPair<Scales>) => boolean;
+};
+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;
+export declare class ResponsiveTuiConfigurationError extends Error {
+    readonly _tag = "ResponsiveTuiConfigurationError";
+    constructor(message: string);
+}
+export declare const defineBreakpoints: <const Scales extends BreakpointScales>(scales: Scales & Record<Exclude<keyof Scales, BreakpointAxis>, never>) => BreakpointDefinition<Scales>;

package/dist/core/index.js

@@ -0,0 +1,79 @@
+// src/core/index.ts
+class ResponsiveTuiConfigurationError extends Error {
+  _tag = "ResponsiveTuiConfigurationError";
+  constructor(message) {
+    super(message);
+    this.name = this._tag;
+  }
+}
+var defineBreakpoints = (scales) => {
+  const entries = validateScales(scales);
+  const match = (viewport) => ({
+    width: matchScale(viewport.width, entries.width),
+    height: matchScale(viewport.height, entries.height)
+  });
+  return {
+    match,
+    matches: (viewport, pair) => {
+      const current = match(viewport);
+      return current.width === pair[0] && current.height === pair[1];
+    }
+  };
+};
+var breakpointAxes = ["width", "height"];
+var validateScales = (scales) => {
+  if (!isRecord(scales) || Array.isArray(scales)) {
+    throw new ResponsiveTuiConfigurationError("Breakpoint definitions must be an object.");
+  }
+  const unknown = Object.keys(scales).find((key) => !breakpointAxes.includes(key));
+  if (unknown) {
+    throw new ResponsiveTuiConfigurationError(`Unknown breakpoint axis: ${unknown}.`);
+  }
+  return {
+    width: validateScale("width", scales.width),
+    height: validateScale("height", scales.height)
+  };
+};
+var validateScale = (axis, scale) => {
+  if (!isRecord(scale) || Array.isArray(scale)) {
+    throw new ResponsiveTuiConfigurationError(`Breakpoint ${axis} scale must be an object.`);
+  }
+  const entries = Object.entries(scale);
+  if (entries.length === 0) {
+    throw new ResponsiveTuiConfigurationError(`Breakpoint ${axis} scale cannot be empty.`);
+  }
+  const thresholds = new Set;
+  const validated = [];
+  for (const [name, threshold] of entries) {
+    if (name.length === 0) {
+      throw new ResponsiveTuiConfigurationError("Breakpoint names must be non-empty strings.");
+    }
+    if (!isThreshold(threshold)) {
+      throw new ResponsiveTuiConfigurationError("Breakpoint thresholds must be finite non-negative integers.");
+    }
+    if (thresholds.has(threshold)) {
+      throw new ResponsiveTuiConfigurationError(`Breakpoint ${axis} thresholds must be unique.`);
+    }
+    thresholds.add(threshold);
+    validated.push([name, threshold]);
+  }
+  if (!thresholds.has(0)) {
+    throw new ResponsiveTuiConfigurationError(`Breakpoint ${axis} scale must include zero.`);
+  }
+  return validated.sort((left, right) => left[1] - right[1]);
+};
+var matchScale = (value, entries) => {
+  let match = entries[0][0];
+  for (const [name, threshold] of entries) {
+    if (value < threshold)
+      break;
+    match = name;
+  }
+  return match;
+};
+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
+};

package/dist/solid/index.d.ts

@@ -0,0 +1,14 @@
+import { type ParentProps } from "solid-js";
+import type { BreakpointDefinition, BreakpointMatch, BreakpointPair, BreakpointScales } from "../core/index.js";
+export type ResponsiveBreakpointAccessor<Scales extends BreakpointScales = BreakpointScales> = {
+    (): BreakpointMatch<Scales>;
+    (pair: BreakpointPair<Scales>): boolean;
+};
+export declare class ResponsiveTuiProviderError extends Error {
+    readonly _tag = "ResponsiveTuiProviderError";
+    constructor();
+}
+export declare const createResponsiveTui: <const Scales extends BreakpointScales>(breakpoints: BreakpointDefinition<Scales>) => {
+    ResponsiveTUI: (props: ParentProps) => any;
+    useResponsiveTui: () => ResponsiveBreakpointAccessor<Scales>;
+};

package/dist/solid/index.js

@@ -0,0 +1,40 @@
+// src/solid/index.tsx
+import { useTerminalDimensions } from "@opentui/solid";
+import { createContext, createMemo, useContext } from "solid-js";
+
+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();
+  const ResponsiveTUI = (props) => {
+    const dimensions = useTerminalDimensions();
+    const current = createMemo(() => breakpoints.match(dimensions()));
+    const breakpoint = (pair) => pair ? breakpoints.matches(dimensions(), pair) : current();
+    return ResponsiveTuiContext.Provider({
+      get children() {
+        return props.children;
+      },
+      value: breakpoint
+    });
+  };
+  const useResponsiveTui = () => {
+    const breakpoint = useContext(ResponsiveTuiContext);
+    if (!breakpoint) {
+      throw new ResponsiveTuiProviderError;
+    }
+    return breakpoint;
+  };
+  return {
+    ResponsiveTUI,
+    useResponsiveTui
+  };
+};
+export {
+  createResponsiveTui,
+  ResponsiveTuiProviderError
+};

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "opentui-responsive",
+  "version": "0.1.0",
+  "description": "Typed responsive breakpoints for OpenTUI.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itsmeyaw/opentui-responsive.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "default": "./dist/core/index.js"
+    },
+    "./solid": {
+      "types": "./dist/solid/index.d.ts",
+      "import": "./dist/solid/index.js",
+      "default": "./dist/solid/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "accept:node": "node scripts/accept-node-core.mjs && node --experimental-ffi scripts/accept-node-solid.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",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint --deny-warnings .",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@opentui/solid": "0.5.11",
+    "@types/bun": "latest",
+    "oxfmt": "latest",
+    "oxlint": "1.82.0",
+    "publint": "0.3.24",
+    "solid-js": "1.9.12",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "@opentui/solid": "^0.5.11",
+    "solid-js": "1.9.12"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/solid": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "bun": ">=1.3.0",
+    "node": ">=26.4.0"
+  },
+  "packageManager": "bun@1.4.0"
+}