figma-plugin-utilities 0.4.0 → 0.5.0

package/src/lib/scale.ts

@@ -0,0 +1,147 @@
+// Responsive scale math shared by plugins that shape a scale across
+// breakpoints, such as Vitrine Tools' Type and Spacing tabs: the ramp's quadratic
+// Bézier, blending by viewport width, values between breakpoints, fallback
+// widths and fluid CSS. Pure — no Figma API — so both threads may import it.
+//
+// Units are the caller's: the Type tab works in px along its ladder, the
+// Spacing tab in ladder rungs. Nothing here maps a value onto a ladder.
+
+/** The quadratic Bézier through p0 and p2, pulled toward p1, at t in 0…1. */
+export const bezier = (t: number, p0: number, p1: number, p2: number) =>
+  (1 - t) ** 2 * p0 + 2 * (1 - t) * t * p1 + t * t * p2;
+
+/** How far the bend may move toward either end; at 0 or 1 the curve folds. */
+export const clampPosition = (c: number) => Math.min(0.98, Math.max(0.02, c));
+
+/**
+ * The curve's parameter t for a point at x, 0…1, when the bend sits at `c`
+ * along x: the curve runs through x(t) = 2(1−t)t·c + t², solved for t in the
+ * conjugate form, which has no division by zero at c = 0.5 (where t = x).
+ */
+export function levelT(x: number, c = 0.5): number {
+  const pos = clampPosition(c);
+  return x / (Math.sqrt(pos * pos + (1 - 2 * pos) * x) + pos);
+}
+
+export const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
+
+/**
+ * Rounds halves down, so a growing value holds its smaller size a breakpoint
+ * longer — 16 16 18 18 20 rather than 16 18 18 20 20.
+ */
+export const roundHalfDown = (x: number) => Math.ceil(x - 0.5);
+
+/**
+ * How far breakpoint `index` sits from the smallest toward the largest, 0…1:
+ * by viewport width when every width is known and they widen, so the blend
+ * matches CSS vw, and evenly by position otherwise.
+ */
+export function blendAt(
+  index: number,
+  count: number,
+  widths?: number[],
+): number {
+  if (count < 2) return 0;
+  const w0 = widths?.[0];
+  const w1 = widths?.[count - 1];
+  if (
+    widths?.length === count &&
+    w0 !== undefined &&
+    w1 !== undefined &&
+    w1 > w0
+  ) {
+    return Math.min(1, Math.max(0, (widths[index] - w0) / (w1 - w0)));
+  }
+  return index / (count - 1);
+}
+
+/**
+ * A value at viewport width `width`, from its value at each breakpoint:
+ * straight between the breakpoints either side, as fluid CSS has it, and
+ * held beyond the smallest and largest. Stepped, it is the value of the last
+ * breakpoint at or below the width, as a media query holds it.
+ */
+export function valueAtWidth(
+  widths: number[],
+  values: number[],
+  width: number,
+  stepped = false,
+): number {
+  const last = widths.length - 1;
+  if (last < 0) return 0;
+  if (width <= widths[0]) return values[0];
+  if (width >= widths[last]) return values[last];
+  let b = 0;
+  while (b < last - 1 && widths[b + 1] <= width) b++;
+  if (stepped) return values[b];
+  const t = (width - widths[b]) / (widths[b + 1] - widths[b]);
+  return values[b] + (values[b + 1] - values[b]) * t;
+}
+
+/** Breakpoint widths by name, for a file that doesn't give them. */
+export const FALLBACK_WIDTHS: Record<string, number> = {
+  xs: 320,
+  sm: 400,
+  md: 768,
+  lg: 1024,
+  xl: 1440,
+  xlg: 1440,
+  "2xl": 1920,
+  xxl: 1920,
+  "3xl": 2560,
+  xxxl: 2560,
+  max: 2560,
+};
+
+/** Whether a name is one the fallback widths know, in any case. */
+export const isBreakpointName = (name: string) =>
+  Object.prototype.hasOwnProperty.call(FALLBACK_WIDTHS, name.toLowerCase());
+
+/**
+ * Each breakpoint's width: the file's (`known`), else the usual one for its
+ * name, else 400px past the one before. Out of order, a width is taken as
+ * unknown — a breakpoint can't sit narrower than the one before it.
+ */
+export function widthsFor(
+  names: string[],
+  known: Record<string, number> = {},
+): number[] {
+  const out: number[] = [];
+  names.forEach((name, i) => {
+    const previous = out[i - 1] ?? 0;
+    const given = known[name] ?? FALLBACK_WIDTHS[name.toLowerCase()];
+    out.push(
+      given !== undefined && given > previous
+        ? given
+        : previous
+          ? previous + 400
+          : 400,
+    );
+  });
+  return out;
+}
+
+/** A number as CSS writes it: no trailing zeros, at most `places` decimals. */
+export const trimNumber = (n: number, places = 4) =>
+  String(Number(n.toFixed(places)));
+
+/**
+ * A length fluid between two viewport widths, as CSS: `from` at `w0`, `to`
+ * at `w1`, straight between and held beyond — a clamp() over vw, or the
+ * length alone when it doesn't change. `length` writes a px value in the
+ * caller's unit, such as `(px) => `${px / 16}rem``.
+ */
+export function fluidClamp(
+  from: number,
+  to: number,
+  w0: number,
+  w1: number,
+  length: (px: number) => string,
+): string {
+  if (w1 === w0 || Math.abs(from - to) < 1e-9) return length(from);
+  const slope = (to - from) / (w1 - w0);
+  const intercept = from - slope * w0;
+  const vw = slope * 100;
+  const sign = vw < 0 ? "-" : "+";
+  return `clamp(${length(Math.min(from, to))}, ${length(intercept)} ${sign} ${trimNumber(Math.abs(vw))}vw, ${length(Math.max(from, to))})`;
+}

package/src/lib/colors.js

@@ -1,80 +0,0 @@
-/**
- * Color utilities for Figma plugins
- */
-
-/**
- * Convert RGB color (0-1 range) to HEX string
- * @param {{r: number, g: number, b: number}} color - RGB color with values 0-1
- * @returns {string} HEX color string (e.g., "#FF0000")
- */
-export function rgbToHex({ r, g, b }) {
-  const toHex = (value) => {
-    const hex = Math.round(value * 255)
-      .toString(16)
-      .padStart(2, "0");
-    return hex;
-  };
-  return `#${toHex(r)}${toHex(g)}${toHex(b)}`.toUpperCase();
-}
-
-/**
- * Convert HEX string to RGB color (0-1 range)
- * @param {string} hex - HEX color string (e.g., "#FF0000" or "FF0000")
- * @returns {{r: number, g: number, b: number} | null} RGB color with values 0-1, or null if invalid
- */
-export function hexToRgb(hex) {
-  const cleanHex = hex.replace(/^#/, "");
-  if (!/^[0-9A-Fa-f]{6}$/.test(cleanHex)) {
-    return null;
-  }
-  const r = parseInt(cleanHex.substring(0, 2), 16) / 255;
-  const g = parseInt(cleanHex.substring(2, 4), 16) / 255;
-  const b = parseInt(cleanHex.substring(4, 6), 16) / 255;
-  return { r, g, b };
-}
-
-/**
- * Get relative luminance of a color (for contrast calculations)
- * @param {{r: number, g: number, b: number}} color - RGB color with values 0-1
- * @returns {number} Relative luminance (0-1)
- */
-export function getLuminance({ r, g, b }) {
-  const adjust = (c) =>
-    c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
-  return 0.2126 * adjust(r) + 0.7152 * adjust(g) + 0.0722 * adjust(b);
-}
-
-/**
- * Calculate contrast ratio between two colors (WCAG formula)
- * @param {{r: number, g: number, b: number}} color1 - First RGB color (0-1 range)
- * @param {{r: number, g: number, b: number}} color2 - Second RGB color (0-1 range)
- * @returns {number} Contrast ratio (1-21)
- */
-export function getContrastRatio(color1, color2) {
-  const l1 = getLuminance(color1);
-  const l2 = getLuminance(color2);
-  const lighter = Math.max(l1, l2);
-  const darker = Math.min(l1, l2);
-  return (lighter + 0.05) / (darker + 0.05);
-}
-
-/**
- * Check if contrast ratio meets WCAG level
- * @param {number} ratio - Contrast ratio
- * @param {"AA" | "AAA" | "AA-large" | "AAA-large"} level - WCAG level to check
- * @returns {boolean} Whether the ratio meets the level
- */
-export function meetsContrastLevel(ratio, level) {
-  switch (level) {
-    case "AAA":
-      return ratio >= 7;
-    case "AAA-large":
-      return ratio >= 4.5;
-    case "AA":
-      return ratio >= 4.5;
-    case "AA-large":
-      return ratio >= 3;
-    default:
-      return false;
-  }
-}