opentui-responsive 0.2.4 → 0.2.6

package/README.md

@@ -5,7 +5,7 @@
     <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>Typed responsive breakpoints for OpenTUI React and Solid applications.</p>
   <p align="center">
   <img src="https://raw.githubusercontent.com/itsmeyaw/opentui-responsive/main/docs/assets/demo.gif" alt="opentui-responsive terminal demo">
 </p>
@@ -29,39 +29,59 @@ bun add opentui-responsive @opentui/react react
 npm install opentui-responsive @opentui/react react
 ```
 
-Core-only consumers only need `opentui-responsive`.
+Framework adapter authors can use the framework-neutral `opentui-responsive/core` entrypoint.
 
 ## Usage
 
-Define breakpoint tiers, then create a provider and hook bound to that definition:
+Create the responsive provider in your layout, then use its hook directly in child components:
+
+`src/layout.tsx`
 
 ```tsx
-import { defineBreakpoints } from "opentui-responsive/core";
 import { createResponsiveTui } from "opentui-responsive/solid";
+import type { ParentProps } from "solid-js";
 
-const breakpoints = defineBreakpoints({
+export const { ResponsiveTUI, useResponsiveTui } = createResponsiveTui({
   width: { narrow: 0, medium: 60, wide: 100 },
   height: { short: 0, medium: 16, tall: 28 },
 });
 
-const { ResponsiveTUI, useResponsiveTui } = createResponsiveTui(breakpoints);
+export function Layout(props: ParentProps) {
+  return <ResponsiveTUI>{props.children}</ResponsiveTUI>;
+}
+```
+
+`src/content.tsx`
+
+```tsx
+import { useResponsiveTui } from "./layout.tsx";
 
-function Content() {
+export function Content() {
   const breakpoint = useResponsiveTui();
+  // You can use it to directly check [width, height] breakpoint
+  const isWideAndTall = breakpoint(["wide", "tall"]);
 
   return (
+    // Or you can get the current width and height breakpoint
     <box flexDirection={breakpoint().width === "wide" ? "row" : "column"}>
       <text>{`${breakpoint().width}/${breakpoint().height}`}</text>
-      <text>{breakpoint(["wide", "tall"]) ? "Full layout" : "Compact layout"}</text>
+      <text>{isWideAndTall ? "Full layout" : "Compact layout"}</text>
     </box>
   );
 }
+```
+
+`src/app.tsx`
+
+```tsx
+import { Content } from "./content.tsx";
+import { Layout } from "./layout.tsx";
 
-function App() {
+export function App() {
   return (
-    <ResponsiveTUI>
+    <Layout>
       <Content />
-    </ResponsiveTUI>
+    </Layout>
   );
 }
 ```
@@ -70,52 +90,39 @@ function App() {
 
 Run `bun run demo` from the package directory to try the Solid example. Resize the terminal to see its layout respond.
 
-The React adapter has the same factory, provider, hook, and inferred breakpoint types; import `createResponsiveTui` from `opentui-responsive/react` instead.
+The React adapter has the same factory, provider, hook, and inferred breakpoint types; import `createResponsiveTui` from `opentui-responsive/react` instead. Use `PropsWithChildren` for the layout's props.
 
 ## API Reference
 
-### `opentui-responsive/core`
+### `opentui-responsive/solid` and `opentui-responsive/react`
 
-| 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.                                           |
+| API                               | Description                                                                              |
+| --------------------------------- | ---------------------------------------------------------------------------------------- |
+| `createResponsiveTui(scales)`     | Validates the scales and creates a `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.                               |
+| `ResponsiveTuiConfigurationError` | Thrown when the supplied breakpoint scales are invalid.                                  |
+| `ResponsiveTuiProviderError`      | Thrown when the generated hook is called outside its provider.                           |
 
-### `opentui-responsive/solid` and `opentui-responsive/react`
+### `opentui-responsive/core`
+
+For implementing another framework adapter, not application setup:
 
-| 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.                     |
+| API                                  | Description                                                                |
+| ------------------------------------ | -------------------------------------------------------------------------- |
+| `createBreakpointDefinition(scales)` | Validates scales and creates `match` and `matches` helpers for an adapter. |
+| `BreakpointDefinition`               | The typed breakpoint matcher returned by `createBreakpointDefinition`.     |
+| `BreakpointScales`                   | The width and height scale configuration.                                  |
+| `BreakpointMatch`                    | The matched breakpoint name for each axis.                                 |
+| `BreakpointPair`                     | An exact breakpoint pair in width-then-height order.                       |
+| `ResponsiveTuiConfigurationError`    | Thrown when supplied breakpoint scales are invalid.                        |
 
 ## Breakpoint Behavior
 
 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. Each axis selects its highest satisfied threshold:
-
-```ts
-const breakpoints = defineBreakpoints({
-  width: { wide: 100, narrow: 0, medium: 60 },
-  height: { tall: 28, short: 0, medium: 16 },
-});
-
-breakpoints.match({ width: 120, height: 10 });
-// { width: "wide", height: "short" }
-```
+Declaration order does not affect matching. Each axis selects its highest satisfied threshold.
 
 Use breakpoints for discrete layout modes. Keep continuous measurements such as progress-bar width and available list height on OpenTUI's `useTerminalDimensions()`.
 

package/dist/core/breakpoints.d.ts

@@ -0,0 +1,35 @@
+/** 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 matcher for framework adapter implementations. */
+export type BreakpointDefinition<Scales extends BreakpointScales = BreakpointScales> = {
+    readonly match: (viewport: BreakpointViewport) => BreakpointMatch<Scales>;
+    readonly matches: (viewport: BreakpointViewport, pair: BreakpointPair<Scales>) => boolean;
+};
+/** Thrown when breakpoint scales cannot produce a valid definition. */
+export declare class ResponsiveTuiConfigurationError extends Error {
+    readonly _tag = "ResponsiveTuiConfigurationError";
+    constructor(message: string);
+}
+/** Creates a validated breakpoint matcher for the framework adapters. */
+export declare const createBreakpointDefinition: <const Scales extends BreakpointScales>(scales: Scales & Record<Exclude<keyof Scales, BreakpointAxis>, never>) => BreakpointDefinition<Scales>;

package/dist/core/index.d.ts

@@ -1,42 +1 @@
-/** 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>;
+export * from "./breakpoints.js";

package/dist/core/index.js

@@ -1,4 +1,4 @@
-// src/core/index.ts
+// src/core/breakpoints.ts
 class ResponsiveTuiConfigurationError extends Error {
   _tag = "ResponsiveTuiConfigurationError";
   constructor(message) {
@@ -6,7 +6,7 @@ class ResponsiveTuiConfigurationError extends Error {
     this.name = this._tag;
   }
 }
-var defineBreakpoints = (scales) => {
+var createBreakpointDefinition = (scales) => {
   const entries = validateScales(scales);
   const match = (viewport) => ({
     width: matchScale(viewport.width, entries.width),
@@ -75,5 +75,5 @@ var isRecord = (value) => typeof value === "object" && value !== null;
 var isThreshold = (value) => typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
 export {
   ResponsiveTuiConfigurationError,
-  defineBreakpoints
+  createBreakpointDefinition
 };

package/dist/react/index.d.ts

@@ -1,5 +1,6 @@
 import { type PropsWithChildren } from "react";
-import type { BreakpointDefinition, BreakpointMatch, BreakpointPair, BreakpointScales } from "../core/index.js";
+import { type BreakpointMatch, type BreakpointPair, type BreakpointScales } from "../core/index.js";
+export { ResponsiveTuiConfigurationError } from "../core/index.js";
 /** A React accessor that reads or tests the current breakpoint pair. */
 export type ResponsiveBreakpointAccessor<Scales extends BreakpointScales = BreakpointScales> = {
     (): BreakpointMatch<Scales>;
@@ -11,7 +12,7 @@ export declare class ResponsiveTuiProviderError extends Error {
     constructor();
 }
 /** Creates a React provider and hook bound to one breakpoint definition. */
-export declare const createResponsiveTui: <const Scales extends BreakpointScales>(breakpoints: BreakpointDefinition<Scales>) => {
+export declare const createResponsiveTui: <const Scales extends BreakpointScales>(scales: Scales & Record<Exclude<keyof Scales, "width" | "height">, never>) => {
     ResponsiveTUI: (props: PropsWithChildren) => import("react").FunctionComponentElement<import("react").ProviderProps<ResponsiveBreakpointAccessor<Scales> | undefined>>;
     useResponsiveTui: () => ResponsiveBreakpointAccessor<Scales>;
 };

package/dist/react/index.js

@@ -2,6 +2,83 @@
 import { useTerminalDimensions } from "@opentui/react";
 import { createContext, createElement, useContext } from "react";
 
+// src/core/breakpoints.ts
+class ResponsiveTuiConfigurationError extends Error {
+  _tag = "ResponsiveTuiConfigurationError";
+  constructor(message) {
+    super(message);
+    this.name = this._tag;
+  }
+}
+var createBreakpointDefinition = (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;
+
+// src/react/index.ts
 class ResponsiveTuiProviderError extends Error {
   _tag = "ResponsiveTuiProviderError";
   constructor() {
@@ -9,7 +86,8 @@ class ResponsiveTuiProviderError extends Error {
     this.name = this._tag;
   }
 }
-var createResponsiveTui = (breakpoints) => {
+var createResponsiveTui = (scales) => {
+  const breakpoints = createBreakpointDefinition(scales);
   const ResponsiveTuiContext = createContext(undefined);
   const ResponsiveTUI = (props) => {
     const dimensions = useTerminalDimensions();
@@ -26,6 +104,7 @@ var createResponsiveTui = (breakpoints) => {
   return { ResponsiveTUI, useResponsiveTui };
 };
 export {
+  ResponsiveTuiConfigurationError,
   ResponsiveTuiProviderError,
   createResponsiveTui
 };

package/dist/solid/index.d.ts

@@ -1,5 +1,6 @@
 import { type ParentProps } from "solid-js";
-import type { BreakpointDefinition, BreakpointMatch, BreakpointPair, BreakpointScales } from "../core/index.js";
+import { type BreakpointMatch, type BreakpointPair, type BreakpointScales } from "../core/index.js";
+export { ResponsiveTuiConfigurationError } 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>;
@@ -11,7 +12,7 @@ export declare class ResponsiveTuiProviderError extends Error {
     constructor();
 }
 /** Creates a Solid provider and hook bound to one breakpoint definition. */
-export declare const createResponsiveTui: <const Scales extends BreakpointScales>(breakpoints: BreakpointDefinition<Scales>) => {
+export declare const createResponsiveTui: <const Scales extends BreakpointScales>(scales: Scales & Record<Exclude<keyof Scales, "width" | "height">, never>) => {
     ResponsiveTUI: (props: ParentProps) => any;
     useResponsiveTui: () => ResponsiveBreakpointAccessor<Scales>;
 };

package/dist/solid/index.js

@@ -2,6 +2,83 @@
 import { useTerminalDimensions } from "@opentui/solid";
 import { createContext, createMemo, useContext } from "solid-js";
 
+// src/core/breakpoints.ts
+class ResponsiveTuiConfigurationError extends Error {
+  _tag = "ResponsiveTuiConfigurationError";
+  constructor(message) {
+    super(message);
+    this.name = this._tag;
+  }
+}
+var createBreakpointDefinition = (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;
+
+// src/solid/index.ts
 class ResponsiveTuiProviderError extends Error {
   _tag = "ResponsiveTuiProviderError";
   constructor() {
@@ -9,7 +86,8 @@ class ResponsiveTuiProviderError extends Error {
     this.name = this._tag;
   }
 }
-var createResponsiveTui = (breakpoints) => {
+var createResponsiveTui = (scales) => {
+  const breakpoints = createBreakpointDefinition(scales);
   const ResponsiveTuiContext = createContext();
   const ResponsiveTUI = (props) => {
     const dimensions = useTerminalDimensions();
@@ -32,6 +110,7 @@ var createResponsiveTui = (breakpoints) => {
   return { ResponsiveTUI, useResponsiveTui };
 };
 export {
+  ResponsiveTuiConfigurationError,
   ResponsiveTuiProviderError,
   createResponsiveTui
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentui-responsive",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Typed responsive breakpoints for OpenTUI.",
   "license": "MIT",
   "repository": {