opentui-responsive 0.4.0 → 0.5.0

package/README.md

@@ -58,17 +58,15 @@ export function Layout(props: ParentProps) {
 import { useBreakpoint } from "./layout.tsx";
 
 export function Content() {
-  const breakpoint = useBreakpoint();
-  // You can use it to directly check [width, height] breakpoint
-  const isWideAndTall = breakpoint(["wide", "tall"]);
-  // Compare one axis, or compare both axes with AND semantics
-  const isMediumOrWider = breakpoint.atLeast("width", "medium");
-  const hasMediumViewport = breakpoint.atLeast(["medium", "medium"]);
+  const [width, height, viewport] = useBreakpoint();
+  // Each accessor can be named for its local use.
+  const isWideAndTall = viewport(["wide", "tall"]);
+  const isMediumOrWider = width.atLeast("medium");
+  const hasMediumViewport = viewport.atLeast(["medium", "medium"]);
 
   return (
-    // Or you can get the current width and height breakpoint
-    <box flexDirection={breakpoint().width === "wide" ? "row" : "column"}>
-      <text>{`${breakpoint().width}/${breakpoint().height}`}</text>
+    <box flexDirection={width() === "wide" ? "row" : "column"}>
+      <text>{`${width()}/${height()}`}</text>
       <text>
         {isWideAndTall || (isMediumOrWider && hasMediumViewport) ? "Full layout" : "Compact layout"}
       </text>
@@ -92,14 +90,19 @@ export function App() {
 }
 ```
 
-`useBreakpoint()` updates when the terminal crosses a configured threshold. Its accessor returns the current width and height names, accepts an exact `[width, height]` pair, and provides named relation methods. Relation methods accept either an axis and name or a pair; pair comparisons return true only when both axes satisfy the relation.
+`useBreakpoint()` updates when the terminal crosses a configured threshold. It returns `[width, height, viewport]`, letting each caller choose local names while keeping breakpoint names scoped to their axis. Width and height accept one breakpoint name; viewport accepts a `[width, height]` pair. Viewport pair comparisons return true only when both axes satisfy the relation.
 
 ```tsx
-breakpoint.below("width", "medium");
-breakpoint.atMost(["medium", "tall"]);
-breakpoint.only("height", "short");
-breakpoint.atLeast(["medium", "medium"]);
-breakpoint.above("width", "medium");
+const [width, height, viewport] = useBreakpoint();
+
+width.below("medium");
+viewport.atMost(["medium", "tall"]);
+height.only("short");
+viewport.atLeast(["medium", "medium"]);
+width.above("medium");
+
+const [sidebarWidth] = useBreakpoint();
+const [, , layoutViewport] = useBreakpoint();
 ```
 
 Run `bun run demo` from the package directory to try the Solid example. Resize the terminal to see its layout respond.
@@ -110,15 +113,16 @@ The React adapter has the same factory, provider, hook, and inferred breakpoint
 
 ### `opentui-responsive/solid` and `opentui-responsive/react`
 
-| API                                   | Description                                                                           |
-| ------------------------------------- | ------------------------------------------------------------------------------------- |
-| `createResponsiveTui(scales)`         | Validates the scales and creates a `ResponsiveTUI` provider and `useBreakpoint` hook. |
-| `ResponsiveTUI`                       | Tracks terminal dimensions and provides the current breakpoint accessor.              |
-| `useBreakpoint()`                     | Reads the accessor from the nearest generated provider.                               |
-| `ResponsiveBreakpointAccessor`        | Reads the current match or tests exact and relative breakpoint positions.             |
-| `ResponsiveBreakpointRelationMatcher` | Tests one axis or an AND-combined width and height pair.                              |
-| `ResponsiveTuiConfigurationError`     | Thrown when the supplied breakpoint scales are invalid.                               |
-| `ResponsiveTuiProviderError`          | Thrown when the generated hook is called outside its provider.                        |
+| API                                    | Description                                                                           |
+| -------------------------------------- | ------------------------------------------------------------------------------------- |
+| `createResponsiveTui(scales)`          | Validates the scales and creates a `ResponsiveTUI` provider and `useBreakpoint` hook. |
+| `ResponsiveTUI`                        | Tracks terminal dimensions and provides the current breakpoint accessor.              |
+| `useBreakpoint()`                      | Reads `[width, height, viewport]` from the nearest generated provider.                |
+| `ResponsiveBreakpointAccessor`         | The readonly `[width, height, viewport]` accessor tuple.                              |
+| `ResponsiveBreakpointAxisAccessor`     | Reads or compares one axis using that axis's breakpoint names.                        |
+| `ResponsiveBreakpointViewportAccessor` | Reads or compares the complete viewport using `[width, height]` pairs.                |
+| `ResponsiveTuiConfigurationError`      | Thrown when the supplied breakpoint scales are invalid.                               |
+| `ResponsiveTuiProviderError`           | Thrown when the generated hook is called outside its provider.                        |
 
 ### `opentui-responsive/core`
 
@@ -140,7 +144,7 @@ Width and height use independent sets of inclusive minimum thresholds measured i
 
 Declaration order does not affect matching. Each axis selects its highest satisfied threshold.
 
-Relation methods compare complete tiers rather than their raw threshold values. Given `width: { narrow: 0, medium: 60, wide: 100 }`, `atMost("width", "medium")` matches widths from `0` through `99`.
+Relation methods compare complete tiers rather than their raw threshold values. Given `width: { narrow: 0, medium: 60, wide: 100 }`, `width.atMost("medium")` matches widths from `0` through `99`.
 
 | Method    | Tier relation |
 | --------- | ------------- |
@@ -150,7 +154,7 @@ Relation methods compare complete tiers rather than their raw threshold values.
 | `atLeast` | `>=`          |
 | `above`   | `>`           |
 
-Each method accepts `(axis, name)` for a single-axis comparison or `[width, height]` for a two-axis comparison. Two-axis comparisons use AND semantics. Calling `breakpoint.only(["wide", "tall"])` is equivalent to calling `breakpoint(["wide", "tall"])`.
+Width and height relation methods each accept a name from their own scale. Viewport relation methods accept `[width, height]` pairs and use AND semantics. Calling `viewport.only(["wide", "tall"])` is equivalent to calling `viewport(["wide", "tall"])`. The `/core` relation matchers retain `(viewport, axis, name)` and `(viewport, [width, height])` forms for adapter implementations.
 
 Use breakpoints for discrete layout modes. Keep continuous measurements such as progress-bar width and available list height on OpenTUI's `useTerminalDimensions()`.
 

package/dist/react/index.d.ts

@@ -1,21 +1,36 @@
 import { type PropsWithChildren } from "react";
 import { createBreakpointDefinition, type BreakpointAxis, type BreakpointMatch, type BreakpointPair, type BreakpointScales } from "../core/index.js";
 export { ResponsiveTuiConfigurationError } from "../core/index.js";
-/** A React breakpoint relation test for one axis or both axes. */
-export type ResponsiveBreakpointRelationMatcher<Scales extends BreakpointScales = BreakpointScales> = {
-    <Axis extends BreakpointAxis>(axis: Axis, name: BreakpointMatch<Scales>[Axis]): boolean;
-    (pair: BreakpointPair<Scales>): boolean;
+/** A React breakpoint relation test for one axis. */
+export type ResponsiveBreakpointAxisRelationMatcher<Scales extends BreakpointScales = BreakpointScales, Axis extends BreakpointAxis = BreakpointAxis> = {
+    (name: BreakpointMatch<Scales>[Axis]): boolean;
+};
+/** A React accessor that reads or tests one breakpoint axis. */
+export type ResponsiveBreakpointAxisAccessor<Scales extends BreakpointScales = BreakpointScales, Axis extends BreakpointAxis = BreakpointAxis> = {
+    (): BreakpointMatch<Scales>[Axis];
+    (name: BreakpointMatch<Scales>[Axis]): boolean;
+    readonly below: ResponsiveBreakpointAxisRelationMatcher<Scales, Axis>;
+    readonly atMost: ResponsiveBreakpointAxisRelationMatcher<Scales, Axis>;
+    readonly only: ResponsiveBreakpointAxisRelationMatcher<Scales, Axis>;
+    readonly atLeast: ResponsiveBreakpointAxisRelationMatcher<Scales, Axis>;
+    readonly above: ResponsiveBreakpointAxisRelationMatcher<Scales, Axis>;
 };
-/** A React accessor that reads or tests the current breakpoint pair. */
-export type ResponsiveBreakpointAccessor<Scales extends BreakpointScales = BreakpointScales> = {
+/** A React accessor that reads or tests the complete breakpoint viewport. */
+export type ResponsiveBreakpointViewportAccessor<Scales extends BreakpointScales = BreakpointScales> = {
     (): BreakpointMatch<Scales>;
     (pair: BreakpointPair<Scales>): boolean;
-    readonly below: ResponsiveBreakpointRelationMatcher<Scales>;
-    readonly atMost: ResponsiveBreakpointRelationMatcher<Scales>;
-    readonly only: ResponsiveBreakpointRelationMatcher<Scales>;
-    readonly atLeast: ResponsiveBreakpointRelationMatcher<Scales>;
-    readonly above: ResponsiveBreakpointRelationMatcher<Scales>;
+    readonly below: (pair: BreakpointPair<Scales>) => boolean;
+    readonly atMost: (pair: BreakpointPair<Scales>) => boolean;
+    readonly only: (pair: BreakpointPair<Scales>) => boolean;
+    readonly atLeast: (pair: BreakpointPair<Scales>) => boolean;
+    readonly above: (pair: BreakpointPair<Scales>) => boolean;
 };
+/** React breakpoint accessors in width, height, then viewport order. */
+export type ResponsiveBreakpointAccessor<Scales extends BreakpointScales = BreakpointScales> = readonly [
+    width: ResponsiveBreakpointAxisAccessor<Scales, "width">,
+    height: ResponsiveBreakpointAxisAccessor<Scales, "height">,
+    viewport: ResponsiveBreakpointViewportAccessor<Scales>
+];
 /** Thrown when a responsive hook is used outside its generated React provider. */
 export declare class ResponsiveTuiProviderError extends Error {
     readonly _tag = "ResponsiveTuiProviderError";

package/dist/react/index.js

@@ -123,14 +123,16 @@ var createResponsiveTui = (scales) => {
   const ResponsiveTuiContext = createContext(undefined);
   const ResponsiveTUI = (props) => {
     const dimensions = useTerminalDimensions();
-    const bind = (relation) => bindRelation(() => dimensions, relation);
-    const breakpoint = Object.assign((pair) => pair ? breakpoints.matches(dimensions, pair) : breakpoints.match(dimensions), {
-      below: bind(breakpoints.below),
-      atMost: bind(breakpoints.atMost),
-      only: bind(breakpoints.only),
-      atLeast: bind(breakpoints.atLeast),
-      above: bind(breakpoints.above)
+    const width = bindAxisAccessor("width", () => dimensions, breakpoints);
+    const height = bindAxisAccessor("height", () => dimensions, breakpoints);
+    const viewport = Object.assign((pair) => pair ? breakpoints.matches(dimensions, pair) : breakpoints.match(dimensions), {
+      below: bindViewportRelation(() => dimensions, breakpoints.below),
+      atMost: bindViewportRelation(() => dimensions, breakpoints.atMost),
+      only: bindViewportRelation(() => dimensions, breakpoints.only),
+      atLeast: bindViewportRelation(() => dimensions, breakpoints.atLeast),
+      above: bindViewportRelation(() => dimensions, breakpoints.above)
     });
+    const breakpoint = [width, height, viewport];
     return createElement(ResponsiveTuiContext.Provider, { value: breakpoint }, props.children);
   };
   const useBreakpoint = () => {
@@ -142,12 +144,15 @@ var createResponsiveTui = (scales) => {
   };
   return { ResponsiveTUI, useBreakpoint };
 };
-var bindRelation = (viewport, relation) => (axisOrPair, name) => {
-  if (typeof axisOrPair !== "string") {
-    return relation(viewport(), axisOrPair);
-  }
-  return relation(viewport(), axisOrPair, name);
-};
+var bindAxisAccessor = (axis, viewport, breakpoints) => Object.assign((name) => name === undefined ? breakpoints.match(viewport())[axis] : breakpoints.only(viewport(), axis, name), {
+  below: bindAxisRelation(axis, viewport, breakpoints.below),
+  atMost: bindAxisRelation(axis, viewport, breakpoints.atMost),
+  only: bindAxisRelation(axis, viewport, breakpoints.only),
+  atLeast: bindAxisRelation(axis, viewport, breakpoints.atLeast),
+  above: bindAxisRelation(axis, viewport, breakpoints.above)
+});
+var bindAxisRelation = (axis, viewport, relation) => (name) => relation(viewport(), axis, name);
+var bindViewportRelation = (viewport, relation) => (pair) => relation(viewport(), pair);
 export {
   ResponsiveTuiConfigurationError,
   ResponsiveTuiProviderError,

package/dist/solid/index.d.ts

@@ -1,21 +1,36 @@
 import { type ParentProps } from "solid-js";
 import { createBreakpointDefinition, type BreakpointAxis, type BreakpointMatch, type BreakpointPair, type BreakpointScales } from "../core/index.js";
 export { ResponsiveTuiConfigurationError } from "../core/index.js";
-/** A reactive Solid breakpoint relation test for one axis or both axes. */
-export type ResponsiveBreakpointRelationMatcher<Scales extends BreakpointScales = BreakpointScales> = {
-    <Axis extends BreakpointAxis>(axis: Axis, name: BreakpointMatch<Scales>[Axis]): boolean;
-    (pair: BreakpointPair<Scales>): boolean;
+/** A reactive Solid breakpoint relation test for one axis. */
+export type ResponsiveBreakpointAxisRelationMatcher<Scales extends BreakpointScales = BreakpointScales, Axis extends BreakpointAxis = BreakpointAxis> = {
+    (name: BreakpointMatch<Scales>[Axis]): boolean;
+};
+/** A reactive Solid accessor that reads or tests one breakpoint axis. */
+export type ResponsiveBreakpointAxisAccessor<Scales extends BreakpointScales = BreakpointScales, Axis extends BreakpointAxis = BreakpointAxis> = {
+    (): BreakpointMatch<Scales>[Axis];
+    (name: BreakpointMatch<Scales>[Axis]): boolean;
+    readonly below: ResponsiveBreakpointAxisRelationMatcher<Scales, Axis>;
+    readonly atMost: ResponsiveBreakpointAxisRelationMatcher<Scales, Axis>;
+    readonly only: ResponsiveBreakpointAxisRelationMatcher<Scales, Axis>;
+    readonly atLeast: ResponsiveBreakpointAxisRelationMatcher<Scales, Axis>;
+    readonly above: ResponsiveBreakpointAxisRelationMatcher<Scales, Axis>;
 };
-/** A reactive Solid accessor that reads or tests the current breakpoint pair. */
-export type ResponsiveBreakpointAccessor<Scales extends BreakpointScales = BreakpointScales> = {
+/** A reactive Solid accessor that reads or tests the complete breakpoint viewport. */
+export type ResponsiveBreakpointViewportAccessor<Scales extends BreakpointScales = BreakpointScales> = {
     (): BreakpointMatch<Scales>;
     (pair: BreakpointPair<Scales>): boolean;
-    readonly below: ResponsiveBreakpointRelationMatcher<Scales>;
-    readonly atMost: ResponsiveBreakpointRelationMatcher<Scales>;
-    readonly only: ResponsiveBreakpointRelationMatcher<Scales>;
-    readonly atLeast: ResponsiveBreakpointRelationMatcher<Scales>;
-    readonly above: ResponsiveBreakpointRelationMatcher<Scales>;
+    readonly below: (pair: BreakpointPair<Scales>) => boolean;
+    readonly atMost: (pair: BreakpointPair<Scales>) => boolean;
+    readonly only: (pair: BreakpointPair<Scales>) => boolean;
+    readonly atLeast: (pair: BreakpointPair<Scales>) => boolean;
+    readonly above: (pair: BreakpointPair<Scales>) => boolean;
 };
+/** Reactive Solid breakpoint accessors in width, height, then viewport order. */
+export type ResponsiveBreakpointAccessor<Scales extends BreakpointScales = BreakpointScales> = readonly [
+    width: ResponsiveBreakpointAxisAccessor<Scales, "width">,
+    height: ResponsiveBreakpointAxisAccessor<Scales, "height">,
+    viewport: ResponsiveBreakpointViewportAccessor<Scales>
+];
 /** Thrown when a responsive hook is used outside its generated Solid provider. */
 export declare class ResponsiveTuiProviderError extends Error {
     readonly _tag = "ResponsiveTuiProviderError";

package/dist/solid/index.js

@@ -1,6 +1,6 @@
 // src/solid/index.ts
 import { useTerminalDimensions } from "@opentui/solid";
-import { createContext, createMemo, useContext } from "solid-js";
+import { createContext, useContext } from "solid-js";
 
 // src/core/breakpoints.ts
 class ResponsiveTuiConfigurationError extends Error {
@@ -123,15 +123,16 @@ var createResponsiveTui = (scales) => {
   const ResponsiveTuiContext = createContext();
   const ResponsiveTUI = (props) => {
     const dimensions = useTerminalDimensions();
-    const current = createMemo(() => breakpoints.match(dimensions()));
-    const bind = (relation) => bindRelation(dimensions, relation);
-    const breakpoint = Object.assign((pair) => pair ? breakpoints.matches(dimensions(), pair) : current(), {
-      below: bind(breakpoints.below),
-      atMost: bind(breakpoints.atMost),
-      only: bind(breakpoints.only),
-      atLeast: bind(breakpoints.atLeast),
-      above: bind(breakpoints.above)
+    const width = bindAxisAccessor("width", dimensions, breakpoints);
+    const height = bindAxisAccessor("height", dimensions, breakpoints);
+    const viewport = Object.assign((pair) => pair ? breakpoints.matches(dimensions(), pair) : breakpoints.match(dimensions()), {
+      below: bindViewportRelation(dimensions, breakpoints.below),
+      atMost: bindViewportRelation(dimensions, breakpoints.atMost),
+      only: bindViewportRelation(dimensions, breakpoints.only),
+      atLeast: bindViewportRelation(dimensions, breakpoints.atLeast),
+      above: bindViewportRelation(dimensions, breakpoints.above)
     });
+    const breakpoint = [width, height, viewport];
     return ResponsiveTuiContext.Provider({
       get children() {
         return props.children;
@@ -148,12 +149,15 @@ var createResponsiveTui = (scales) => {
   };
   return { ResponsiveTUI, useBreakpoint };
 };
-var bindRelation = (viewport, relation) => (axisOrPair, name) => {
-  if (typeof axisOrPair !== "string") {
-    return relation(viewport(), axisOrPair);
-  }
-  return relation(viewport(), axisOrPair, name);
-};
+var bindAxisAccessor = (axis, viewport, breakpoints) => Object.assign((name) => name === undefined ? breakpoints.match(viewport())[axis] : breakpoints.only(viewport(), axis, name), {
+  below: bindAxisRelation(axis, viewport, breakpoints.below),
+  atMost: bindAxisRelation(axis, viewport, breakpoints.atMost),
+  only: bindAxisRelation(axis, viewport, breakpoints.only),
+  atLeast: bindAxisRelation(axis, viewport, breakpoints.atLeast),
+  above: bindAxisRelation(axis, viewport, breakpoints.above)
+});
+var bindAxisRelation = (axis, viewport, relation) => (name) => relation(viewport(), axis, name);
+var bindViewportRelation = (viewport, relation) => (pair) => relation(viewport(), pair);
 export {
   ResponsiveTuiConfigurationError,
   ResponsiveTuiProviderError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentui-responsive",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Typed responsive breakpoints for OpenTUI.",
   "keywords": [
     "breakpoints",