@tetrax/squircle 1.0.0

package/README.md

@@ -0,0 +1,257 @@
+# @tetrax/squircle
+
+Figma-accurate squircles for React, React Native, & HTML Canvas. Install once, use with className.
+
+> Uses the same algorithm as Figma's corner smoothing — 2 cubic Bézier curves + 1 circular arc per corner (Standard mode), or Pavel Klavík's optimal cubic Bézier coefficients for pure curvature-continuous corners (G2 mode).
+
+## Install
+
+```bash
+npm install @tetrax/squircle
+```
+
+No config changes needed. Just import and use.
+
+## React / Next.js
+
+```jsx
+import { Squircle } from "@tetrax/squircle/react";
+
+function App() {
+  return (
+    <Squircle className="rounded-squircle-24 squircle-border border-gray-200 bg-white p-6">
+      <h2>Card Title</h2>
+      <p>This has squircle corners and a squircle-shaped border.</p>
+    </Squircle>
+  );
+}
+```
+
+### Available Classes
+
+| Class | Effect |
+|---|---|
+| `rounded-squircle-{0-96}` | Corner radius in px |
+| `corner-smoothing-{0-100}` | Smoothing (default: 100 = full squircle, G1 only) |
+| `squircle-g2` | Enable G2 curvature-continuous mode (ignores manual smoothing percent) |
+| `squircle-border` | Enable squircle border overlay (1px) |
+| `squircle-border-{n}` | Border width (e.g. `squircle-border-2`, `squircle-border-1.5`) |
+| `border-{color}` | Border color — standard Tailwind (e.g. `border-gray-200`) |
+| `border-{color}/{opacity}` | Border color with opacity (e.g. `border-gray-600/50`) |
+| `border-{width}` | Border width — standard Tailwind (e.g. `border-2`) |
+
+All other Tailwind classes (`bg-*`, `p-*`, `text-*`, etc.) pass through normally.
+
+### Examples
+
+```jsx
+// Basic squircle (G1)
+<Squircle className="rounded-squircle-16 bg-blue-500 p-4 text-white">
+  Hello World
+</Squircle>
+
+// G2 Curvature-continuous squircle (ultra-smooth corners)
+<Squircle className="rounded-squircle-24 squircle-g2 bg-purple-600 p-4 text-white">
+  G2 Smooth
+</Squircle>
+
+// With border (standard Tailwind)
+<Squircle className="rounded-squircle-24 squircle-border border-gray-200 bg-white p-6">
+  Card with border
+</Squircle>
+
+// Thick colored border
+<Squircle className="rounded-squircle-20 squircle-border border-2 border-emerald-300 bg-emerald-500 p-4">
+  Green card
+</Squircle>
+
+// Border with opacity
+<Squircle className="rounded-squircle-24 squircle-border border-gray-600/50 bg-white p-6">
+  Semi-transparent border
+</Squircle>
+
+// Decimal border width
+<Squircle className="rounded-squircle-16 squircle-border-1.5 border-gray-400 bg-white p-4">
+  1.5px squircle border
+</Squircle>
+
+// Custom element tag
+<Squircle as="button" className="rounded-squircle-12 bg-black text-white px-6 py-3">
+  Click me
+</Squircle>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | `""` | Tailwind classes including squircle classes |
+| `cornerRadius` | `number` | from `rounded-squircle-*` | Override corner radius |
+| `cornerSmoothing` | `number` | `1` | Override smoothing (0–1, Standard G1 only) |
+| `g2Continuous` | `boolean` | `false` | Enable pure G2 curvature continuity |
+| `preserveSmoothing` | `boolean` | `false` | Preserve smoothing at large radii |
+| `as` | `ComponentType \| string` | `"div"` | HTML tag or component to render |
+
+### useSquircle Hook
+
+For custom elements where you need more control:
+
+```jsx
+import { useSquircle } from "@tetrax/squircle/react";
+
+function MyCard({ className }) {
+  const { ref, clipPath, borderStyle, parsed } = useSquircle(className);
+
+  return (
+    <div
+      ref={ref}
+      className={parsed.restClasses}
+      style={{ clipPath, ...borderStyle }}
+    >
+      Custom element with squircle
+    </div>
+  );
+}
+```
+
+### Zero-Config: Standard HTML Elements (Optional)
+
+Alternatively, you can use standard HTML tags (like `<div>` or `<button>`) directly without wrapper components or hooks! 
+
+Once the React package is imported anywhere in your app, a global observer dynamically scans the DOM and automatically applies the Figma-accurate clip-path and border overlay styles to any element containing the `rounded-squircle-` classes.
+
+This works **directly on void elements** (like `<input>`, `<img>`, etc.) where appending children is physically disallowed by HTML. The SDK automatically detects void tags, inserts the border overlay as a sibling, and aligns it perfectly.
+
+```html
+<!-- Automatically squirckled standard div! -->
+<div class="rounded-squircle-24 squircle-border border-gray-200 bg-white p-6">
+  Hello from standard div!
+</div>
+
+<!-- Squirckled input tag (void element) — border renders perfectly! -->
+<input 
+  type="password"
+  placeholder="Thick border: yellow-400/20"
+  class="rounded-squircle-9 squircle-border-2 border-yellow-400/20 bg-[#1B1B1B] text-white px-4 py-3 outline-none"
+/>
+```
+
+## React Native
+
+```jsx
+import { SquircleNative } from "@tetrax/squircle/react-native";
+
+function Card() {
+  return (
+    <SquircleNative
+      cornerRadius={24}
+      squircleBorder
+      borderColor="#e5e7eb"
+      borderWidth={1}
+      backgroundColor="white"
+      style={{ padding: 16 }}
+    >
+      <Text>Card content</Text>
+    </SquircleNative>
+  );
+}
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `cornerRadius` | `number` | *required* | Corner radius in dp |
+| `cornerSmoothing` | `number` | `1` | Smoothing (0–1) |
+| `squircleBorder` | `boolean` | `false` | Show squircle border |
+| `borderColor` | `string` | `"transparent"` | Border color |
+| `borderWidth` | `number` | `1` | Border width in dp |
+| `backgroundColor` | `string` | — | Background fill |
+| `style` | `ViewStyle` | — | Additional styles |
+
+> React Native requires `react-native-svg` as a peer dependency.
+
+## Core (Headless & Canvas 2D)
+
+Use the math engine or direct Canvas drawing utility without React:
+
+### SVG Path Calculations
+
+```js
+import { getSvgPath, computeSquirclePath } from "@tetrax/squircle/core";
+
+// Full API (matches figma-squircle's getSvgPath)
+const path = getSvgPath({
+  width: 200,
+  height: 100,
+  cornerRadius: 24,
+  cornerSmoothing: 0.8, // Optional (default: 1)
+  preserveSmoothing: true,
+  g2Continuous: false, // Set true for G2 Béziers
+});
+
+// Convenience wrapper
+const path = computeSquirclePath(200, 100, 24, 0.8);
+
+// Use with clip-path CSS
+element.style.clipPath = `path('${path}')`;
+```
+
+### Canvas 2D Drawing Utility
+
+Draw squircles directly onto a canvas context with pixel-perfect precision matching the SVG output:
+
+```js
+import { drawSquircleRect } from "@tetrax/squircle/core";
+
+const canvas = document.getElementById("canvas");
+const ctx = canvas.getContext("2d");
+
+ctx.beginPath();
+// Supports uniform radius:
+drawSquircleRect(ctx, 10, 10, 200, 100, 24);
+
+// Supports asymmetric per-corner radii:
+drawSquircleRect(ctx, 10, 150, 200, 100, {
+  tl: 8, tr: 32, br: 8, bl: 32
+});
+
+ctx.fillStyle = "#3b82f6";
+ctx.fill();
+```
+
+### getSvgPath Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `width` | `number` | *required* | Element width |
+| `height` | `number` | *required* | Element height |
+| `cornerRadius` | `number` | `0` | Uniform corner radius |
+| `topLeftCornerRadius` | `number` | `cornerRadius` | Override top-left |
+| `topRightCornerRadius` | `number` | `cornerRadius` | Override top-right |
+| `bottomRightCornerRadius` | `number` | `cornerRadius` | Override bottom-right |
+| `bottomLeftCornerRadius` | `number` | `cornerRadius` | Override bottom-left |
+| `cornerSmoothing` | `number` | `1` | 0 = rounded rect, 1 = full squircle |
+| `preserveSmoothing` | `boolean` | `false` | Preserve smoothing at large radii |
+| `g2Continuous` | `boolean` | `false` | Enable G2 curvature-continuous mode |
+
+## How It Works
+
+### Via Component / Hook:
+1. The `<Squircle>` component (or `useSquircle` hook) wraps or hooks into your element.
+2. `ResizeObserver` measures the element's actual size.
+3. The Figma squircle algorithm generates an SVG path (2 Bézier curves + 1 arc per corner in standard mode, or 3 pure Béziers in G2 mode).
+4. The path is applied as `clip-path: path('...')` via inline style.
+5. If `squircle-border` is present, an absolutely-positioned overlay SVG renders the squircle-shaped border, inset by `borderWidth / 2` so it remains fully inside the parent's `clip-path` bounding box without clipping.
+
+### Via Standard HTML Elements:
+1. A global `MutationObserver` watches the document body for changes.
+2. When an element with class `rounded-squircle-` is added or has its classes modified, the observer registers a `ResizeObserver` on it.
+3. On size changes, it calculates the squircle path and applies it to the element's `clipPath` and `WebkitClipPath` style properties.
+4. If `squircle-border` is in the class name:
+   - **For standard container elements**: it dynamically appends and updates an `<svg data-squircle-border="true">` child overlay.
+   - **For void elements (like `<input>`, `<img>`)**: it inserts the SVG border overlay as a sibling right after the element and dynamically aligns it using the element's `offsetTop`/`offsetLeft` parameters to guarantee exact rendering alignment over the clipped control.
+
+## License
+
+MIT

package/dist/core.d.mts

@@ -0,0 +1,68 @@
+interface SquirclePathParams {
+    width: number;
+    height: number;
+    cornerRadius?: number;
+    topLeftCornerRadius?: number;
+    topRightCornerRadius?: number;
+    bottomRightCornerRadius?: number;
+    bottomLeftCornerRadius?: number;
+    cornerSmoothing?: number;
+    preserveSmoothing?: boolean;
+    g2Continuous?: boolean;
+}
+/**
+ * Generate an SVG path string for a squircle rectangle.
+ * Direct port of figma-squircle's getSvgPath(), with optional pure G2 Bézier mode.
+ */
+declare function getSvgPath({ cornerRadius, topLeftCornerRadius, topRightCornerRadius, bottomRightCornerRadius, bottomLeftCornerRadius, cornerSmoothing, width, height, preserveSmoothing, g2Continuous, }: SquirclePathParams): string;
+/**
+ * Compute an SVG path string from width/height/radius/smoothing.
+ * Convenience wrapper around getSvgPath().
+ */
+declare function computeSquirclePath(width: number, height: number, cornerRadius: number, cornerSmoothing?: number, preserveSmoothing?: boolean, g2Continuous?: boolean): string;
+/**
+ * Render a squircle rectangle directly onto a Canvas 2D context using
+ * G2 curvature-continuous Bézier curves (Pavel Klavík's optimal coefficients).
+ *
+ * FIX #5: Rewrote to use the same *relative delta* G2 coefficients as the
+ * SVG path drawer, so Canvas and SVG paths are numerically identical.
+ * Previous version used accumulated offsets (0.804, 0.912, 0.961) which
+ * did not match the SVG path coefficients (0.185, 0.293, 0.342).
+ *
+ * @example
+ * const ctx = canvas.getContext('2d');
+ * ctx.beginPath();
+ * drawSquircleRect(ctx, 0, 0, 200, 100, 24);
+ * ctx.fillStyle = '#3b82f6';
+ * ctx.fill();
+ */
+declare function drawSquircleRect(ctx: CanvasRenderingContext2D | any, x: number, y: number, width: number, height: number, cornerRadius: number | {
+    tl?: number;
+    tr?: number;
+    br?: number;
+    bl?: number;
+}, smoothing?: number): void;
+
+interface SquircleClassConfig {
+    cornerRadius: number | null;
+    cornerSmoothing: number;
+    squircleBorder: boolean;
+    borderColor: string | null;
+    borderWidth: number;
+    g2Continuous: boolean;
+    restClasses: string;
+}
+/**
+ * Parse Tailwind-style class names and extract squircle config.
+ *
+ * When `squircle-border` is present, standard Tailwind `border-{color}` and
+ * `border-{width}` classes are intercepted for the squircle border overlay.
+ * Opacity modifiers like `border-gray-600/50` are fully supported.
+ *
+ * @example
+ * parseSquircleClasses("rounded-squircle-24 squircle-border border-gray-600/50")
+ * // → { cornerRadius: 24, squircleBorder: true, borderColor: "rgba(75, 85, 99, 0.5)", ... }
+ */
+declare function parseSquircleClasses(className?: string): SquircleClassConfig;
+
+export { type SquircleClassConfig, computeSquirclePath, drawSquircleRect, getSvgPath, parseSquircleClasses };

package/dist/core.d.ts

@@ -0,0 +1,68 @@
+interface SquirclePathParams {
+    width: number;
+    height: number;
+    cornerRadius?: number;
+    topLeftCornerRadius?: number;
+    topRightCornerRadius?: number;
+    bottomRightCornerRadius?: number;
+    bottomLeftCornerRadius?: number;
+    cornerSmoothing?: number;
+    preserveSmoothing?: boolean;
+    g2Continuous?: boolean;
+}
+/**
+ * Generate an SVG path string for a squircle rectangle.
+ * Direct port of figma-squircle's getSvgPath(), with optional pure G2 Bézier mode.
+ */
+declare function getSvgPath({ cornerRadius, topLeftCornerRadius, topRightCornerRadius, bottomRightCornerRadius, bottomLeftCornerRadius, cornerSmoothing, width, height, preserveSmoothing, g2Continuous, }: SquirclePathParams): string;
+/**
+ * Compute an SVG path string from width/height/radius/smoothing.
+ * Convenience wrapper around getSvgPath().
+ */
+declare function computeSquirclePath(width: number, height: number, cornerRadius: number, cornerSmoothing?: number, preserveSmoothing?: boolean, g2Continuous?: boolean): string;
+/**
+ * Render a squircle rectangle directly onto a Canvas 2D context using
+ * G2 curvature-continuous Bézier curves (Pavel Klavík's optimal coefficients).
+ *
+ * FIX #5: Rewrote to use the same *relative delta* G2 coefficients as the
+ * SVG path drawer, so Canvas and SVG paths are numerically identical.
+ * Previous version used accumulated offsets (0.804, 0.912, 0.961) which
+ * did not match the SVG path coefficients (0.185, 0.293, 0.342).
+ *
+ * @example
+ * const ctx = canvas.getContext('2d');
+ * ctx.beginPath();
+ * drawSquircleRect(ctx, 0, 0, 200, 100, 24);
+ * ctx.fillStyle = '#3b82f6';
+ * ctx.fill();
+ */
+declare function drawSquircleRect(ctx: CanvasRenderingContext2D | any, x: number, y: number, width: number, height: number, cornerRadius: number | {
+    tl?: number;
+    tr?: number;
+    br?: number;
+    bl?: number;
+}, smoothing?: number): void;
+
+interface SquircleClassConfig {
+    cornerRadius: number | null;
+    cornerSmoothing: number;
+    squircleBorder: boolean;
+    borderColor: string | null;
+    borderWidth: number;
+    g2Continuous: boolean;
+    restClasses: string;
+}
+/**
+ * Parse Tailwind-style class names and extract squircle config.
+ *
+ * When `squircle-border` is present, standard Tailwind `border-{color}` and
+ * `border-{width}` classes are intercepted for the squircle border overlay.
+ * Opacity modifiers like `border-gray-600/50` are fully supported.
+ *
+ * @example
+ * parseSquircleClasses("rounded-squircle-24 squircle-border border-gray-600/50")
+ * // → { cornerRadius: 24, squircleBorder: true, borderColor: "rgba(75, 85, 99, 0.5)", ... }
+ */
+declare function parseSquircleClasses(className?: string): SquircleClassConfig;
+
+export { type SquircleClassConfig, computeSquirclePath, drawSquircleRect, getSvgPath, parseSquircleClasses };