@ariaui/radius 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,305 @@
+/**
+ * A single radius value.
+ *
+ * The original unit is preserved; conversion to other units is on-demand
+ * via the format module.
+ */
+interface RadiusValue {
+    /** Numeric value in the original unit */
+    readonly value: number;
+    /** CSS unit */
+    readonly unit: "px" | "rem" | "%";
+    /** Original authored string, e.g. `"8px"`, `"0.5rem"` */
+    readonly original: string;
+}
+/**
+ * Per-corner radii (CSS `border-radius` longhand).
+ */
+interface CornerRadii {
+    readonly topLeft: RadiusValue;
+    readonly topRight: RadiusValue;
+    readonly bottomRight: RadiusValue;
+    readonly bottomLeft: RadiusValue;
+}
+/** Corner position names. */
+type Corner = "topLeft" | "topRight" | "bottomRight" | "bottomLeft";
+/**
+ * Named radius scale levels matching `@ariaui/tokens`.
+ */
+type RadiusLevel = "none" | "xxs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "full";
+/** A radius scale: level name → value mapping. */
+type RadiusScale = Record<string, RadiusValue>;
+/** Breakpoint name → pixel value. */
+type Breakpoints = Record<string, number>;
+/** Responsive radius: default + optional breakpoint overrides. */
+interface ResponsiveRadius {
+    readonly default: RadiusValue;
+    readonly breakpoints: Record<string, RadiusValue>;
+}
+
+/**
+ * Parse a single CSS radius value string into a `RadiusValue`.
+ *
+ * Accepts `px`, `rem`, and `%` units. Plain numbers are treated as `px`.
+ *
+ * @example
+ * parseRadius("8px")    → { value: 8, unit: "px", original: "8px" }
+ * parseRadius("0.5rem") → { value: 0.5, unit: "rem", original: "0.5rem" }
+ * parseRadius(8)        → { value: 8, unit: "px", original: "8px" }
+ */
+declare function parseRadius(input: string | number): RadiusValue;
+/**
+ * Parse a CSS `border-radius` shorthand into per-corner `CornerRadii`.
+ *
+ * Follows CSS shorthand rules:
+ * - 1 value: all corners
+ * - 2 values: top-left/bottom-right, top-right/bottom-left
+ * - 3 values: top-left, top-right/bottom-left, bottom-right
+ * - 4 values: top-left, top-right, bottom-right, bottom-left
+ *
+ * Does **not** support the `x / y` elliptical radius syntax.
+ *
+ * @example
+ * parseCorners("8px")                → all corners 8px
+ * parseCorners("8px 4px")            → TL/BR=8, TR/BL=4
+ * parseCorners("8px 4px 2px 0px")    → TL=8, TR=4, BR=2, BL=0
+ */
+declare function parseCorners(input: string): CornerRadii;
+
+/**
+ * Create a linear radius scale.
+ *
+ * Generates `count` steps starting from `base`, incrementing by `step`.
+ * Steps are named `"0"`, `"1"`, `"2"`, etc.
+ *
+ * @example
+ * createLinearScale(0, 4, 6)
+ * // → { "0": 0px, "1": 4px, "2": 8px, "3": 12px, "4": 16px, "5": 20px }
+ */
+declare function createLinearScale(base?: number, step?: number, count?: number): RadiusScale;
+/**
+ * Create a radius scale from explicit named values.
+ *
+ * @example
+ * createScale({ none: 0, sm: 4, md: 8, lg: 12, full: "9999px" })
+ */
+declare function createScale(values: Record<string, number | string>): RadiusScale;
+/**
+ * Scale all values in a radius scale by a factor.
+ *
+ * @example
+ * scaleBy(scale, 1.5)  // 50% larger radii
+ */
+declare function scaleBy(scale: RadiusScale, factor: number): RadiusScale;
+/**
+ * Clamp all values in a scale to a [min, max] range.
+ *
+ * Values are clamped in their original unit.
+ */
+declare function clampScale(scale: RadiusScale, min: number, max: number): RadiusScale;
+/**
+ * Get level names sorted by value (ascending).
+ */
+declare function sortedLevels(scale: RadiusScale): string[];
+/**
+ * Step to the next or previous level in a scale.
+ *
+ * Levels are ordered by value. Returns the current level if at a boundary.
+ */
+declare function stepRadius(scale: RadiusScale, current: string, direction: "up" | "down"): string;
+
+/**
+ * Create uniform corners (all four corners the same).
+ *
+ * @example
+ * uniformCorners("8px")
+ * uniformCorners(8)
+ * uniformCorners({ value: 8, unit: "px", original: "8px" })
+ */
+declare function uniformCorners(radius: RadiusValue | string | number): CornerRadii;
+/**
+ * Set a single corner, returning new CornerRadii.
+ *
+ * @example
+ * setCorner(corners, "topLeft", "12px")
+ */
+declare function setCorner(corners: CornerRadii, corner: Corner, value: RadiusValue | string | number): CornerRadii;
+/**
+ * Set both top corners.
+ */
+declare function setTop(corners: CornerRadii, value: RadiusValue | string | number): CornerRadii;
+/**
+ * Set both bottom corners.
+ */
+declare function setBottom(corners: CornerRadii, value: RadiusValue | string | number): CornerRadii;
+/**
+ * Set both left corners.
+ */
+declare function setLeft(corners: CornerRadii, value: RadiusValue | string | number): CornerRadii;
+/**
+ * Set both right corners.
+ */
+declare function setRight(corners: CornerRadii, value: RadiusValue | string | number): CornerRadii;
+/**
+ * Round only the specified corners; all others are set to 0.
+ *
+ * @example
+ * roundCorners("12px", "topLeft", "topRight")
+ * // → TL=12px, TR=12px, BR=0px, BL=0px
+ */
+declare function roundCorners(radius: RadiusValue | string | number, ...corners: Corner[]): CornerRadii;
+
+/**
+ * Calculate the inner radius for a nested element.
+ *
+ * When a rounded parent has padding/gap, the child needs a smaller radius
+ * to visually match the parent's curve: `inner = outer - gap`.
+ *
+ * Result is clamped to ≥ 0 (except for `9999px` pill shapes, where
+ * the subtraction still yields a huge value = still pill).
+ *
+ * @param outer - Outer (parent) radius
+ * @param gap   - Gap between parent and child edges (in the same unit as outer)
+ *
+ * @example
+ * innerRadius("12px", 4)  → { value: 8, unit: "px", original: "8px" }
+ * innerRadius("9999px", 8) → { value: 9991, unit: "px", original: "9991px" }
+ * innerRadius("4px", 8)   → { value: 0, unit: "px", original: "0px" }
+ */
+declare function innerRadius(outer: RadiusValue | string | number, gap: number): RadiusValue;
+/**
+ * Calculate inner corners from outer corners and a uniform gap.
+ *
+ * Each corner's radius is reduced by `gap`, clamped to ≥ 0.
+ *
+ * @example
+ * innerCorners(outerCorners, 8)
+ */
+declare function innerCorners(outer: CornerRadii, gap: number): CornerRadii;
+/**
+ * Calculate the gap needed to achieve a desired inner radius.
+ *
+ * `gap = outer.value - inner.value` (clamped to ≥ 0).
+ */
+declare function requiredGap(outer: RadiusValue | string | number, inner: RadiusValue | string | number): number;
+/**
+ * Suggest matching radii for a parent-child nesting pair.
+ *
+ * @param outerRadius - Desired outer radius in px
+ * @param gap         - Padding/gap between parent and child
+ *
+ * @returns `{ outer, inner }` — both as `RadiusValue`
+ *
+ * @example
+ * nestingPair(12, 8) → { outer: 12px, inner: 4px }
+ * nestingPair(6, 8)  → { outer: 6px, inner: 0px }
+ */
+declare function nestingPair(outerRadius: number, gap: number): {
+    outer: RadiusValue;
+    inner: RadiusValue;
+};
+
+/**
+ * Default breakpoints matching Tailwind CSS v4 defaults.
+ */
+declare const BREAKPOINTS: Breakpoints;
+/**
+ * Create a responsive radius from a config map.
+ *
+ * The `"default"` key is required; other keys must match breakpoint names.
+ *
+ * @example
+ * responsiveRadius({ default: "4px", md: "8px", lg: "12px" })
+ * responsiveRadius({ default: 4, md: 8, lg: 12 })
+ */
+declare function responsiveRadius(config: Record<string, string | number>, breakpoints?: Breakpoints): ResponsiveRadius;
+/**
+ * Scale down a radius for mobile viewports.
+ *
+ * @param value  - Original radius
+ * @param factor - Scale factor (default 0.75)
+ *
+ * @example
+ * mobileRadius(parseRadius("12px"))         → { value: 9, ... }
+ * mobileRadius(parseRadius("12px"), 0.5)    → { value: 6, ... }
+ */
+declare function mobileRadius(value: RadiusValue, factor?: number): RadiusValue;
+/**
+ * Get the sorted breakpoint entries from a `ResponsiveRadius`,
+ * ordered by viewport width (ascending).
+ */
+declare function sortedBreakpoints(responsive: ResponsiveRadius, breakpoints?: Breakpoints): Array<[string, number, RadiusValue]>;
+
+/**
+ * Format a `RadiusValue` as a CSS value string in its original unit.
+ *
+ * @example
+ * toCSS(parseRadius("8px"))    → "8px"
+ * toCSS(parseRadius("0.5rem")) → "0.5rem"
+ */
+declare function toCSS(value: RadiusValue): string;
+/**
+ * Convert a `RadiusValue` to rem.
+ *
+ * @param base - Root font size in px (default 16)
+ *
+ * @example
+ * toRem(parseRadius("8px"))        → "0.5rem"
+ * toRem(parseRadius("0.5rem"))     → "0.5rem"
+ * toRem(parseRadius("24px"), 16)   → "1.5rem"
+ */
+declare function toRem(value: RadiusValue, base?: number): string;
+/**
+ * Convert a `RadiusValue` to px.
+ *
+ * @param base - Root font size in px (default 16, used for rem → px)
+ */
+declare function toPx(value: RadiusValue, base?: number): string;
+/**
+ * Format `CornerRadii` as a CSS `border-radius` shorthand.
+ *
+ * Uses the most compact shorthand form possible.
+ *
+ * @example
+ * toCSSShorthand(uniformCorners(8))     → "8px"
+ * toCSSShorthand(corners)               → "8px 4px 2px 0px"
+ */
+declare function toCSSShorthand(corners: CornerRadii): string;
+/**
+ * Format `CornerRadii` as React `CSSProperties`.
+ *
+ * @example
+ * toCSSProperties(corners)
+ * // → { borderTopLeftRadius: "8px", borderTopRightRadius: "4px", ... }
+ */
+declare function toCSSProperties(corners: CornerRadii): Record<string, string>;
+/**
+ * Format `CornerRadii` as a CSS declaration block.
+ *
+ * Uses shorthand when possible.
+ */
+declare function toCSSDeclaration(corners: CornerRadii): string;
+/**
+ * Format a `RadiusValue` as a Tailwind CSS `rounded-[...]` class.
+ *
+ * @example
+ * toTailwindClass(parseRadius("8px")) → "rounded-[8px]"
+ */
+declare function toTailwindClass(value: RadiusValue): string;
+/**
+ * Format `CornerRadii` as Tailwind per-corner classes.
+ *
+ * @example
+ * toTailwindCorners(corners)
+ * // → "rounded-tl-[8px] rounded-tr-[4px] rounded-br-[2px] rounded-bl-[0px]"
+ */
+declare function toTailwindCorners(corners: CornerRadii): string;
+/**
+ * Generate a CSS `var()` reference for a token radius level.
+ *
+ * @example
+ * toCSSVar("md") → "var(--radius-md)"
+ */
+declare function toCSSVar(level: string): string;
+
+export { BREAKPOINTS, type Breakpoints, type Corner, type CornerRadii, type RadiusLevel, type RadiusScale, type RadiusValue, type ResponsiveRadius, clampScale, createLinearScale, createScale, innerCorners, innerRadius, mobileRadius, nestingPair, parseCorners, parseRadius, requiredGap, responsiveRadius, roundCorners, scaleBy, setBottom, setCorner, setLeft, setRight, setTop, sortedBreakpoints, sortedLevels, stepRadius, toCSS, toCSSDeclaration, toCSSProperties, toCSSShorthand, toCSSVar, toPx, toRem, toTailwindClass, toTailwindCorners, uniformCorners };

package/dist/index.js

@@ -0,0 +1,68 @@
+import {
+  BREAKPOINTS,
+  clampScale,
+  createLinearScale,
+  createScale,
+  innerCorners,
+  innerRadius,
+  mobileRadius,
+  nestingPair,
+  parseCorners,
+  parseRadius,
+  requiredGap,
+  responsiveRadius,
+  roundCorners,
+  scaleBy,
+  setBottom,
+  setCorner,
+  setLeft,
+  setRight,
+  setTop,
+  sortedBreakpoints,
+  sortedLevels,
+  stepRadius,
+  toCSS,
+  toCSSDeclaration,
+  toCSSProperties,
+  toCSSShorthand,
+  toCSSVar,
+  toPx,
+  toRem,
+  toTailwindClass,
+  toTailwindCorners,
+  uniformCorners
+} from "./chunk-3Y6IG3UW.js";
+export {
+  BREAKPOINTS,
+  clampScale,
+  createLinearScale,
+  createScale,
+  innerCorners,
+  innerRadius,
+  mobileRadius,
+  nestingPair,
+  parseCorners,
+  parseRadius,
+  requiredGap,
+  responsiveRadius,
+  roundCorners,
+  scaleBy,
+  setBottom,
+  setCorner,
+  setLeft,
+  setRight,
+  setTop,
+  sortedBreakpoints,
+  sortedLevels,
+  stepRadius,
+  toCSS,
+  toCSSDeclaration,
+  toCSSProperties,
+  toCSSShorthand,
+  toCSSVar,
+  toPx,
+  toRem,
+  toTailwindClass,
+  toTailwindCorners,
+  uniformCorners
+};