opentui-responsive 0.3.1 → 0.4.0

package/README.md

@@ -61,12 +61,17 @@ 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"]);
 
   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>{isWideAndTall ? "Full layout" : "Compact layout"}</text>
+      <text>
+        {isWideAndTall || (isMediumOrWider && hasMediumViewport) ? "Full layout" : "Compact layout"}
+      </text>
     </box>
   );
 }
@@ -87,7 +92,15 @@ export function App() {
 }
 ```
 
-`useBreakpoint()` 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.
+`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.
+
+```tsx
+breakpoint.below("width", "medium");
+breakpoint.atMost(["medium", "tall"]);
+breakpoint.only("height", "short");
+breakpoint.atLeast(["medium", "medium"]);
+breakpoint.above("width", "medium");
+```
 
 Run `bun run demo` from the package directory to try the Solid example. Resize the terminal to see its layout respond.
 
@@ -97,14 +110,15 @@ 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 an exact breakpoint 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 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.                        |
 
 ### `opentui-responsive/core`
 
@@ -117,6 +131,7 @@ For implementing another framework adapter, not application setup:
 | `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.                       |
+| `BreakpointRelationMatcher`          | Tests one axis or an AND-combined pair against a named relation.           |
 | `ResponsiveTuiConfigurationError`    | Thrown when supplied breakpoint scales are invalid.                        |
 
 ## Breakpoint Behavior
@@ -125,6 +140,18 @@ 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`.
+
+| Method    | Tier relation |
+| --------- | ------------- |
+| `below`   | `<`           |
+| `atMost`  | `<=`          |
+| `only`    | `===`         |
+| `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"])`.
+
 Use breakpoints for discrete layout modes. Keep continuous measurements such as progress-bar width and available list height on OpenTUI's `useTerminalDimensions()`.
 
 ## Runtime Support

package/dist/core/breakpoints.d.ts

@@ -24,10 +24,20 @@ export type BreakpointPair<Scales extends BreakpointScales = BreakpointScales> =
     width: BreakpointMatch<Scales>["width"],
     height: BreakpointMatch<Scales>["height"]
 ];
+/** Tests one axis or both axes against a named breakpoint relation. */
+export type BreakpointRelationMatcher<Scales extends BreakpointScales = BreakpointScales> = {
+    <Axis extends BreakpointAxis>(viewport: BreakpointViewport, axis: Axis, name: BreakpointMatch<Scales>[Axis]): boolean;
+    (viewport: BreakpointViewport, pair: BreakpointPair<Scales>): boolean;
+};
 /** 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;
+    readonly below: BreakpointRelationMatcher<Scales>;
+    readonly atMost: BreakpointRelationMatcher<Scales>;
+    readonly only: BreakpointRelationMatcher<Scales>;
+    readonly atLeast: BreakpointRelationMatcher<Scales>;
+    readonly above: BreakpointRelationMatcher<Scales>;
 };
 /** Thrown when breakpoint scales cannot produce a valid definition. */
 export declare class ResponsiveTuiConfigurationError extends Error {

package/dist/core/index.js

@@ -12,12 +12,19 @@ var createBreakpointDefinition = (scales) => {
     width: matchScale(viewport.width, entries.width),
     height: matchScale(viewport.height, entries.height)
   });
+  const below = createRelationMatcher(entries, "below");
+  const atMost = createRelationMatcher(entries, "atMost");
+  const only = createRelationMatcher(entries, "only");
+  const atLeast = createRelationMatcher(entries, "atLeast");
+  const above = createRelationMatcher(entries, "above");
   return {
     match,
-    matches: (viewport, pair) => {
-      const current = match(viewport);
-      return current.width === pair[0] && current.height === pair[1];
-    }
+    matches: (viewport, pair) => only(viewport, pair),
+    below,
+    atMost,
+    only,
+    atLeast,
+    above
   };
 };
 var breakpointAxes = ["width", "height"];
@@ -63,14 +70,39 @@ var validateScale = (axis, scale) => {
   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)
+  return entries[matchScaleIndex(value, entries)][0];
+};
+var matchScaleIndex = (value, entries) => {
+  let match = 0;
+  for (let index = 1;index < entries.length; index += 1) {
+    if (value < entries[index][1])
       break;
-    match = name;
+    match = index;
   }
   return match;
 };
+var createRelationMatcher = (entries, relation) => (viewport, axisOrPair, name) => {
+  if (Array.isArray(axisOrPair)) {
+    return matchesRelation(viewport.width, entries.width, axisOrPair[0], relation) && matchesRelation(viewport.height, entries.height, axisOrPair[1], relation);
+  }
+  const axis = axisOrPair;
+  return matchesRelation(viewport[axis], entries[axis], name, relation);
+};
+var matchesRelation = (value, entries, name, relation) => {
+  const target = entries.findIndex(([entryName]) => entryName === name);
+  if (target === -1)
+    return false;
+  const current = matchScaleIndex(value, entries);
+  if (relation === "below")
+    return current < target;
+  if (relation === "atMost")
+    return current <= target;
+  if (relation === "only")
+    return current === target;
+  if (relation === "atLeast")
+    return current >= target;
+  return current > target;
+};
 var isRecord = (value) => typeof value === "object" && value !== null;
 var isThreshold = (value) => typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
 export {

package/dist/react/index.d.ts

@@ -1,10 +1,20 @@
 import { type PropsWithChildren } from "react";
-import { createBreakpointDefinition, type BreakpointMatch, type BreakpointPair, type BreakpointScales } from "../core/index.js";
+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 accessor that reads or tests the current breakpoint pair. */
 export type ResponsiveBreakpointAccessor<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>;
 };
 /** Thrown when a responsive hook is used outside its generated React provider. */
 export declare class ResponsiveTuiProviderError extends Error {

package/dist/react/index.js

@@ -16,12 +16,19 @@ var createBreakpointDefinition = (scales) => {
     width: matchScale(viewport.width, entries.width),
     height: matchScale(viewport.height, entries.height)
   });
+  const below = createRelationMatcher(entries, "below");
+  const atMost = createRelationMatcher(entries, "atMost");
+  const only = createRelationMatcher(entries, "only");
+  const atLeast = createRelationMatcher(entries, "atLeast");
+  const above = createRelationMatcher(entries, "above");
   return {
     match,
-    matches: (viewport, pair) => {
-      const current = match(viewport);
-      return current.width === pair[0] && current.height === pair[1];
-    }
+    matches: (viewport, pair) => only(viewport, pair),
+    below,
+    atMost,
+    only,
+    atLeast,
+    above
   };
 };
 var breakpointAxes = ["width", "height"];
@@ -67,14 +74,39 @@ var validateScale = (axis, scale) => {
   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)
+  return entries[matchScaleIndex(value, entries)][0];
+};
+var matchScaleIndex = (value, entries) => {
+  let match = 0;
+  for (let index = 1;index < entries.length; index += 1) {
+    if (value < entries[index][1])
       break;
-    match = name;
+    match = index;
   }
   return match;
 };
+var createRelationMatcher = (entries, relation) => (viewport, axisOrPair, name) => {
+  if (Array.isArray(axisOrPair)) {
+    return matchesRelation(viewport.width, entries.width, axisOrPair[0], relation) && matchesRelation(viewport.height, entries.height, axisOrPair[1], relation);
+  }
+  const axis = axisOrPair;
+  return matchesRelation(viewport[axis], entries[axis], name, relation);
+};
+var matchesRelation = (value, entries, name, relation) => {
+  const target = entries.findIndex(([entryName]) => entryName === name);
+  if (target === -1)
+    return false;
+  const current = matchScaleIndex(value, entries);
+  if (relation === "below")
+    return current < target;
+  if (relation === "atMost")
+    return current <= target;
+  if (relation === "only")
+    return current === target;
+  if (relation === "atLeast")
+    return current >= target;
+  return current > target;
+};
 var isRecord = (value) => typeof value === "object" && value !== null;
 var isThreshold = (value) => typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
 
@@ -91,7 +123,14 @@ var createResponsiveTui = (scales) => {
   const ResponsiveTuiContext = createContext(undefined);
   const ResponsiveTUI = (props) => {
     const dimensions = useTerminalDimensions();
-    const breakpoint = (pair) => pair ? breakpoints.matches(dimensions, pair) : breakpoints.match(dimensions);
+    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)
+    });
     return createElement(ResponsiveTuiContext.Provider, { value: breakpoint }, props.children);
   };
   const useBreakpoint = () => {
@@ -103,6 +142,12 @@ 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);
+};
 export {
   ResponsiveTuiConfigurationError,
   ResponsiveTuiProviderError,

package/dist/solid/index.d.ts

@@ -1,10 +1,20 @@
 import { type ParentProps } from "solid-js";
-import { createBreakpointDefinition, type BreakpointMatch, type BreakpointPair, type BreakpointScales } from "../core/index.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 accessor that reads or tests the current breakpoint pair. */
 export type ResponsiveBreakpointAccessor<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>;
 };
 /** Thrown when a responsive hook is used outside its generated Solid provider. */
 export declare class ResponsiveTuiProviderError extends Error {

package/dist/solid/index.js

@@ -16,12 +16,19 @@ var createBreakpointDefinition = (scales) => {
     width: matchScale(viewport.width, entries.width),
     height: matchScale(viewport.height, entries.height)
   });
+  const below = createRelationMatcher(entries, "below");
+  const atMost = createRelationMatcher(entries, "atMost");
+  const only = createRelationMatcher(entries, "only");
+  const atLeast = createRelationMatcher(entries, "atLeast");
+  const above = createRelationMatcher(entries, "above");
   return {
     match,
-    matches: (viewport, pair) => {
-      const current = match(viewport);
-      return current.width === pair[0] && current.height === pair[1];
-    }
+    matches: (viewport, pair) => only(viewport, pair),
+    below,
+    atMost,
+    only,
+    atLeast,
+    above
   };
 };
 var breakpointAxes = ["width", "height"];
@@ -67,14 +74,39 @@ var validateScale = (axis, scale) => {
   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)
+  return entries[matchScaleIndex(value, entries)][0];
+};
+var matchScaleIndex = (value, entries) => {
+  let match = 0;
+  for (let index = 1;index < entries.length; index += 1) {
+    if (value < entries[index][1])
       break;
-    match = name;
+    match = index;
   }
   return match;
 };
+var createRelationMatcher = (entries, relation) => (viewport, axisOrPair, name) => {
+  if (Array.isArray(axisOrPair)) {
+    return matchesRelation(viewport.width, entries.width, axisOrPair[0], relation) && matchesRelation(viewport.height, entries.height, axisOrPair[1], relation);
+  }
+  const axis = axisOrPair;
+  return matchesRelation(viewport[axis], entries[axis], name, relation);
+};
+var matchesRelation = (value, entries, name, relation) => {
+  const target = entries.findIndex(([entryName]) => entryName === name);
+  if (target === -1)
+    return false;
+  const current = matchScaleIndex(value, entries);
+  if (relation === "below")
+    return current < target;
+  if (relation === "atMost")
+    return current <= target;
+  if (relation === "only")
+    return current === target;
+  if (relation === "atLeast")
+    return current >= target;
+  return current > target;
+};
 var isRecord = (value) => typeof value === "object" && value !== null;
 var isThreshold = (value) => typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
 
@@ -92,7 +124,14 @@ var createResponsiveTui = (scales) => {
   const ResponsiveTUI = (props) => {
     const dimensions = useTerminalDimensions();
     const current = createMemo(() => breakpoints.match(dimensions()));
-    const breakpoint = (pair) => pair ? breakpoints.matches(dimensions(), pair) : current();
+    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)
+    });
     return ResponsiveTuiContext.Provider({
       get children() {
         return props.children;
@@ -109,6 +148,12 @@ 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);
+};
 export {
   ResponsiveTuiConfigurationError,
   ResponsiveTuiProviderError,

package/package.json

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