@kalink-ui/seedly 0.29.1 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @kalink-ui/seedly
 
+## 0.30.0
+
+### Minor Changes
+
+- e257be4: feat(styles): add dynamic fluid scale helpers
+
+  New
+  - `getInterpolationFor(value, options)`: per-value exponential mapping from a mobile range to a desktop range.
+  - `toFluidClamp([min, max], options)`: build a viewport-based CSS `clamp()` with `interpolateFrom`/`interpolateTo` (defaults `23.5` and `80`).
+  - `toFluidClampFor(value, options)`: convenience to compute the mapped max and format a `clamp()` in one step.
+
+  Updates
+  - Storybook theme now uses the new helpers and no longer depends on an interpolation variable.
+
+  Usage
+
+  ```ts
+  import {
+    getInterpolationFor,
+    toFluidClampFor,
+  } from '@kalink-ui/seedly/styles';
+
+  const mapped = getInterpolationFor(12, {
+    lowMin: 12,
+    lowMax: 64,
+    highMin: 12,
+    highMax: 200,
+    exponent: 2,
+    rounding: 'none',
+  });
+
+  const clamp = toFluidClampFor(12, {
+    lowMin: 12,
+    lowMax: 64,
+    highMin: 12,
+    highMax: 200,
+    exponent: 2,
+    rounding: 'none',
+    // optional overrides
+    interpolateFrom: 23.5,
+    interpolateTo: 80,
+  });
+  ```
+
 ## 0.29.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalink-ui/seedly",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "description": "A set of components for building UIs with React and TypeScript",
   "sideEffects": false,
   "license": "MIT",
@@ -43,8 +43,8 @@
     "vite": "^6.3.5",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.2.3",
-    "@kalink-ui/eslint-config": "0.10.0",
-    "@kalink-ui/typescript-config": "0.4.0"
+    "@kalink-ui/typescript-config": "0.4.0",
+    "@kalink-ui/eslint-config": "0.10.0"
   },
   "peerDependencies": {
     "@vanilla-extract/css": "^1.17.1",

package/src/styles/index.ts

@@ -34,3 +34,13 @@ export {
 } from './responsive';
 
 export { breakpoints, screen, type BreakpointKey } from './breakpoints';
+
+export {
+  getInterpolationFor,
+  toFluidClamp,
+  toFluidClampFor,
+  type Interval,
+  type ExponentialScaleOptions,
+  type DynamicInterpolationOptions,
+  type FluidClampOptions,
+} from './scale';

package/src/styles/scale.ts

@@ -0,0 +1,149 @@
+export type Interval = [number, number];
+
+/**
+ * Common easing/rounding options used by the interpolation helpers.
+ * Note: `minStep` is ignored in single-value mapping but kept for backward
+ * compatibility of the public types.
+ */
+export interface ExponentialScaleOptions {
+  exponent?: number; // 1 = linear, >1 = ease-in, <1 = ease-out
+  minStep?: number; // kept for compatibility; not used by per-value mapping
+  rounding?: 'none' | 'round' | 'floor' | 'ceil';
+}
+
+export interface DynamicInterpolationOptions extends ExponentialScaleOptions {
+  lowMin: number;
+  lowMax: number;
+  highMin: number;
+  highMax: number;
+  clampInput?: boolean; // clamp input inside [lowMin, lowMax]
+  ensureGteInput?: boolean; // ensure output >= input
+}
+
+export interface FluidClampOptions {
+  unit?: 'rem' | 'px';
+  baseFontSize?: number; // px per rem when unit is 'rem'
+  interpolateFrom?: number; // defaults to 23.5 (in `unit`)
+  interpolateTo?: number; // defaults to 80 (in `unit`)
+}
+
+/**
+ * Format a `[min, max]` pair into a CSS clamp() with viewport-based interpolation:
+ * clamp(min, calc(min + (max - min) * ((100vw - from) / (to - from))), max)
+ *
+ * - `from`/`to` default to 23.5 and 80 (in the selected `unit`).
+ * - `unit` may be 'rem' (default) or 'px'. When 'rem', values are converted from px
+ *   using `baseFontSize` (default 16).
+ */
+export function toFluidClamp(
+  [min, max]: Interval,
+  options: FluidClampOptions = {},
+): string {
+  const unit = options.unit ?? 'rem';
+  const base = options.baseFontSize ?? 16;
+  const from = options.interpolateFrom ?? 23.5;
+  const to = options.interpolateTo ?? 80;
+
+  const toUnit = (px: number): number => {
+    if (unit === 'px') {
+      return px;
+    }
+
+    return px / base;
+  };
+
+  const minU = toUnit(min);
+  const maxU = toUnit(max);
+  const diffU = maxU - minU;
+
+  const interp = `((100vw - ${from}${unit}) / (${to} - ${from}))`;
+
+  return `clamp(${minU}${unit}, calc(${minU}${unit} + (${diffU} * ${interp})), ${maxU}${unit})`;
+}
+
+// Batch scale helpers were removed in favor of per-value mapping.
+
+/**
+ * Map a single `value` from [lowMin, lowMax] to [highMin, highMax] using
+ * exponential easing. Optionally rounds, clamps input, and ensures the output
+ * is not below the input (enabled by default).
+ */
+export function getInterpolationFor(
+  value: number,
+  {
+    lowMin,
+    lowMax,
+    highMin,
+    highMax,
+    exponent = 2,
+    rounding = 'round',
+    clampInput = true,
+    ensureGteInput = true,
+  }: DynamicInterpolationOptions,
+): number {
+  if (lowMax === lowMin) {
+    throw new Error('getInterpolationFor: lowMin and lowMax must differ.');
+  }
+
+  const clamp = (v: number, min: number, max: number): number => {
+    if (v < min) {
+      return min;
+    }
+
+    if (v > max) {
+      return max;
+    }
+
+    return v;
+  };
+
+  const round = (v: number): number => {
+    if (rounding === 'none') {
+      return v;
+    }
+
+    if (rounding === 'floor') {
+      return Math.floor(v);
+    }
+
+    if (rounding === 'ceil') {
+      return Math.ceil(v);
+    }
+
+    return Math.round(v);
+  };
+
+  const input = clampInput ? clamp(value, lowMin, lowMax) : value;
+
+  const t = (input - lowMin) / (lowMax - lowMin);
+  const eased = Math.pow(t, exponent);
+  const mapped = highMin + eased * (highMax - highMin);
+
+  let result = round(mapped);
+
+  if (ensureGteInput && result < input) {
+    result = input;
+  }
+
+  return result;
+}
+
+export interface FluidClampForOptions
+  extends DynamicInterpolationOptions,
+    FluidClampOptions {}
+
+/**
+ * Convenience to produce a CSS clamp() for a single `value` by first computing
+ * its mapped high value via `getInterpolationFor`, then formatting with
+ * `toFluidClamp` using viewport interpolation.
+ */
+export function toFluidClampFor(
+  value: number,
+  { unit = 'rem', baseFontSize = 16, ...opts }: FluidClampForOptions,
+): string {
+  return toFluidClamp([value, getInterpolationFor(value, opts)], {
+    unit,
+    baseFontSize,
+    ...opts,
+  });
+}